How to run several agents at once

What each agent needs its own of

Steps

1. Make a worktree for each task

   A worktree is a second folder of the same repository on its own branch. History and remotes stay shared, the files do not.

   $ cd ~/your-project
   $ git worktree add ../wt-auth -b auth
   $ git worktree add ../wt-billing -b billing
   $ git worktree add ../wt-docs -b docs
   $ git worktree list

   Claude Code can do this itself: claude --worktree NAME makes .claude/worktrees/NAME on a new branch worktree-NAME. For Codex, codex exec --worktree runs the session in a new Git worktree.

2. Set up each worktree

   A worktree is a fresh checkout: install the dependencies again in each one. Copy the .env too: it is not in git. With claude --worktree, a .worktreeinclude file copies gitignored files such as .env into each new worktree.

   $ for d in ../wt-auth ../wt-billing ../wt-docs; do
       cp .env "$d/" && (cd "$d" && npm ci)
     done

3. Start one tmux session with a window per agent

   One session keeps all agents together. Each window starts in its own worktree.

   $ tmux new -d -s agents -n auth -c ~/wt-auth
   $ tmux new-window -t agents -n billing -c ~/wt-billing
   $ tmux new-window -t agents -n docs -c ~/wt-docs
   $ tmux attach -t agents

4. Give each agent its task

   In each window run the agent and give it one task. Tell it which port to use if it starts a server. Switch windows with Ctrl+B, then the window number; leave with Ctrl+B, then D.

   # window auth
   $ claude "Add password reset. Run the dev server on PORT=3001."
   # window billing
   $ codex "Move invoices to the new tax table. Use PORT=3002."

5. Merge and clean up

   Review each branch, merge it, then remove the worktree and the branch.

   $ git diff main...auth
   $ git merge auth
   $ git worktree remove ../wt-auth
   $ git branch -d auth

Check that it works

Each worktree should show only its own changes, and the server should have memory to spare while all agents build.

$ for d in ../wt-*; do echo "$d"; git -C "$d" status --short; done
$ free -h
$ ps -eo rss,comm --sort=-rss | head

How big a server

The agents are light; their work is not. On our computer about 400 MB went to each Claude Code session and under 100 MB to Codex. One npm ci or test run can take more than all of them together, and three agents may run three at once. Count the builds, then pick the plan.

What worktrees do not do

• They do not stop merge conflicts. Two agents that change the same lines on two branches still meet at the merge; give them tasks in different parts of the code.
• They do not share a limit fairly. Agents on one Claude plan draw from the same pool: usage limits reset on a rolling five-hour window, paid plans add weekly limits, and Claude Code draws from the same pool.
• They do not copy what git ignores: .env, node_modules and build caches start empty in every worktree.

Common problems