Run multiple Claude Code agents at once, without losing track

1. Split the work first

Claude Code has no problem running several times on one Mac. Each session is its own process with its own conversation. The trouble starts when two sessions edit the same file, or when one session's half-finished change breaks the build the other one is testing.

Good parallel tasks are ones you could hand to two different people without a meeting: a bug in the API and a layout fix in the settings page, a test suite for one module and a refactor of another. Tasks that need each other's output are better done one after the other.

A useful pattern is many readers and one writer. Agents that only investigate (find where something lives, explain a failing test, review a diff) can run in any number, because their output never conflicts. Keep the agents that change code to a few, each on its own area. We wrote more about this in Scouts before editors.

2. Give each agent its own worktree

A git worktree is a second checkout of the same repository in another folder, on its own branch. Agents in different worktrees cannot overwrite each other's files, and each branch can be reviewed and merged on its own.

# from your main checkout
git worktree add ../my-app-search -b search
git worktree add ../my-app-settings -b settings-dark-mode

# start an agent in each
cd ../my-app-search && claude

When you are done, merge the branch as usual and remove the folder with git worktree remove ../my-app-search. git worktree list shows what you have.

Two things to watch for:

• Dependencies. A new worktree has no node_modules, virtualenv or build output. Install them in each worktree, or tell the agent to.
• Ports and shared services. Two dev servers on port 3000 will collide. Give each agent a different port, or have only one of them run the app.

3. Run the sessions side by side

Terminal tabs or windows

The simplest setup is one tab per agent in Terminal, iTerm2 or your editor's terminal. Name each tab after its task so you can find it again. This works well for two or three agents.

tmux

tmux gives you named windows in one session that keep running when you close the terminal:

tmux new -s agents -n search     # first window
tmux new-window -t agents -n settings
# Ctrl-b w lists windows, Ctrl-b d detaches
tmux attach -t agents            # come back later

Run claude in each window from its worktree. With set -g monitor-bell on in ~/.tmux.conf, tmux flags a window in the status bar when the program in it rings the terminal bell, which helps with the next step.

4. Know which one is waiting

This is where most parallel setups break down. Claude Code stops and waits when it wants permission to run a command, when it asks you a question, when it has a plan for you to approve, and when it finishes. In a single terminal you see that right away. With four tabs, the agent that needs you is usually the one you are not looking at.

Your options, from least to most setup:

• Check the tabs on a timer. It works, and it is how most people start. It costs attention every few minutes.
• Terminal bell plus tmux or tab badges. Have Claude Code ring the bell when it waits, and let your terminal or tmux mark the window.
• Claude Code hooks. A Notification hook and a Stop hook can post a macOS notification naming the project. The Claude Code notifications guide has a copy-paste setup.

All three tell you that something is waiting. You still switch to the right tab, read back to see what it asked, and answer there.

5. How Cadence handles it

Cadence is a free macOS app that puts every coding agent in one Inbox. It starts and tracks the agents for you and collects their questions in one place, so you answer without hunting for the tab.

Start the agents

1. Download Cadence and make sure the claude CLI is installed and signed in. Cadence uses that login; there is no separate API key.
2. On the toolbar at the edge of your screen, open ⋯ → New agent… and pick Claude Code.
3. Choose Terminal (Claude Code's own interface in a herdr terminal) or Cadence chat (runs inside Cadence).
4. Enter the Folder and an optional First message, then click Start.

You can also double-tap ⌥ and say what you want. Talk sends it to the agent already working in that area, or starts a new one in the right folder.

Worktrees without the bookkeeping

With Use a git worktree per agent on (the default, in Settings → Agents), each Cadence chat agent started inside a git repo gets its own branch, cadence/<name>-<id>, in ~/.cadence/worktrees/. Ending the agent keeps the branch so you can review and merge it. Terminal agents do not get a worktree automatically; point their Folder at a worktree you made with the commands above.

See who is waiting

The toolbar shows one dot per agent: blue is working, amber needs you, green is done. Each agent gets a short title such as "settings page dark mode", so you can tell them apart. Hold the pointer on the dots for two seconds to see what each one is on.

Amber agents land in the Inbox as cards: questions with numbered options, plans to approve, and Allow/Deny permission requests. Press 1 to 9 to answer, J and K to move between cards, and Esc within two seconds to take an answer back.

When there are too many

The toolbar shows up to eight dots. Sets put a group of terminal agents away: their windows close, the agents keep running in herdr, and their questions still reach the Inbox. To ask about all of them at once, say "is anything stuck?" and the Director answers.

Claude Code sessions you started yourself in another terminal show up too. Cadence can read them, and Talk can move one into herdr so Cadence can send it messages.

Common questions