How to Run Several Claude Code Agents at Once

Running two coding agents side by side is mostly about keeping them out of each other's files. Running three, four or five copies of the same agent adds problems two never hit: they share one subscription, they all stop to ask you things, and they all want the same port. This guide covers what changes past two, using Claude Code as the example. The basics (one git worktree per agent, clear ownership, a shared task list) are in How to Run Claude Code and Codex Side by Side, and they still apply.

1. One worktree per agent, created in one go

Each session needs its own directory and branch. With more than two, script it so the names stay consistent:

$ for name in api ui tests docs; do git worktree add ../myapp-$name -b agent/$name; done

A worktree shares the repository's history but not its untracked files, so each one needs its own dependencies before the agent starts:

$ cd ../myapp-api && npm install

2. Give each one its own port

Agents start dev servers and test servers on their own. Four of them on one machine will fight over the same port, and the loser often reports a failure that has nothing to do with its change. Give each worktree a port of its own, for example in an untracked .env file the agent's instructions point at:

$ echo PORT=3101 > ../myapp-api/.env
$ echo PORT=3102 > ../myapp-ui/.env

3. They share one subscription

Every session signed in to the same account draws on the same plan's usage limits. Four agents use them up roughly four times as fast as one, and when the limit arrives it arrives for all of them at once, usually in the middle of something. Start with fewer agents than you think you need, give the long and expensive tasks to one of them, and stagger the rest.

4. Decide how much each one may do without asking

Claude Code asks before it edits files or runs commands, and with several sessions you will spend the day switching terminals to answer. Shift+Tab cycles a session's permission mode: the default asks every time, accept-edits lets it change files on its own, and plan mode has it propose a plan without touching anything. A reasonable split is plan mode for the session exploring a hard problem, accept-edits for sessions working inside a worktree you will review anyway, and the default for anything that touches shared files.

5. Know when one is waiting on you

The costliest failure with several sessions is not a wrong answer. It is a session sitting idle for an hour on a question you never saw. Claude Code can run a command when it needs your attention, through a Notification hook in its settings, so a waiting session can show a desktop notification instead of waiting in a terminal you are not looking at.

6. Run the well-defined tasks headless

Not every task needs a conversation. A clearly specified job, such as adding tests for one module or updating one dependency, can run without an interactive session at all, in print mode, and leave its result in the worktree for you to review:

$ cd ../myapp-tests && claude -p "Add unit tests for src/search.ts. Do not change src/."

Keep the interactive sessions for the work that needs your judgement.

7. How many is too many

The limit is rarely the machine. It is how much work you can review well. Each agent produces a branch you have to read, test and merge, so the right number is the number whose output you can still check properly the same day. For most people that is three or four, not ten.

When you are done, merge one branch at a time with the tests run on each, then remove the worktrees:

$ for name in api ui tests docs; do git worktree remove ../myapp-$name; done

Where Harmony fits

Everything above works with plain terminals. Harmony is a free desktop app that takes over the bookkeeping: every agent opens in its own tab in one window, each can work in its own worktree, the agents share one task board and can message each other, a tab shows, when Harmony can tell, that its agent is waiting on you, and the sessions keep running when you close the window. It works with Claude Code and with Codex, Cursor, Gemini and the other coding CLIs you already use.

To be precise about how finished that is: the workspace, task board, messaging and worktrees ship today as preview features, and fully autonomous multi-agent runs are still experimental. The features page labels every capability with its status.

Try the steps above by hand first. If switching between terminals is what slows you down, download Harmony and run the same setup in one window.