How do you run Claude Code in parallel?

The short answer

Claude Code is a single-conversation CLI bound to one working directory. To run it in parallel you do not start multiple conversations inside one repo — you create multiple repos. git worktree add gives you a second working tree backed by the same .git directory, on its own branch. Open a terminal in that worktree, run claude -p, and you have a second Claude session that cannot collide with the first. Do this four times and you have four Claudes typing into four branches simultaneously.

Spinning up the worktrees and the CLI processes is two minutes of shell. The hard part is keeping a coherent view of what each one is doing, paying for the right number of tokens, and merging the results in an order that does not produce four reverts. That is the part KanBots does for you.

How it actually works under the hood

A worktree is a directory and a branch, sharing the object database of a primary repo. The minimal recipe for two parallel Claude runs from a repo on main:

# in the main repo
git worktree add ../my-app-claude-1 -b feature/auth
git worktree add ../my-app-claude-2 -b feature/billing

# terminal A
cd ../my-app-claude-1
claude -p "implement issue #42 (auth)" \
  --output-format stream-json \
  --verbose \
  --permission-mode bypassPermissions

# terminal B (different tab)
cd ../my-app-claude-2
claude -p "implement issue #43 (billing)" \
  --output-format stream-json \
  --verbose \
  --permission-mode bypassPermissions

Each Claude only ever sees its own working tree. Both processes share the same .git object store — refs are namespaced per branch, so writes never tear. --output-format stream-json makes Claude emit NDJSON: one JSON object per line, each one a system, assistant, tool_use, tool_result, or result event. If you tee that to a file you get a full, replayable transcript of each run.

When a run finishes you have two options. Cheap: cd into the worktree and git push the branch, open a PR. Cheaper still: cherry-pick or fast-forward into a feature branch you control. Heavier: delete the worktree with git worktree remove, keep the branch, throw it away later. Either way, you never need to git stash, never lose your editor cursor, and you can keep coding in the main checkout while the agents run.

Why four terminal tabs is the naive answer

The naive answer to "run N Claudes" is: open N terminal tabs, do the dance above N times. It works for one afternoon. Then it stops working because:

• There is no shared status. You alt-tab through tabs to see which one finished. One of them is silently rate-limited and you do not notice for an hour.
• Costs are invisible. The result event in the stream-json output carries token counts and dollars, but you have to parse them yourself. You do not know which task spent $4 and which spent $0.40 until you add it up.
• Decision prompts are buried. Claude pauses and asks "should I delete this file?" and the prompt sits in a backgrounded tab while you work in another tab. The run idles.
• Cleanup is manual. You either accumulate dozens of ../my-app-claude-N worktrees on disk or you forget which ones you already promoted.

How KanBots does this specifically

KanBots is the supervisor that owns the worktree-per-card pattern as a product. You drop a folder onto the desktop app, get a kanban board, and clicking Dispatch on a card runs exactly the recipe above:

• Creates .kanbots/worktrees/issue-<n>-<runId>/ off the repo’s default branch.
• Names the branch kanbots/issue-<n>-<runId> so you can identify agent work at a glance and so a single global pre-push hook can block accidental remote pushes.
• Spawns claude -p with --output-format stream-json --permission-mode bypassPermissions, parses every NDJSON event, and forwards it to the UI as a live agent thread.
• When the agent emits a decision request, the run pauses and a numbered prompt pops on the card. You click an option, the run continues.

Autopilot — feature-devmode — runs up to four such cards concurrently in slots. Each slot is a separate worktree, a separate kanbots/issue-N-M branch, and a separate Claude process. The board updates live as runs progress; per-card cost and per-session cost accrue in the UI; you can stop the whole tree from one button. Personas (product author, engineer, reviewer, tester) round-robin through the slots, so a four-card run is really one issue being chewed on from four angles in parallel.

Same board works with Codex. KanBots speaks both stream formats behind a single AgentCliAdapter interface, so you can mix claude and codex runs on different cards on the same board. More on that in how to spawn multiple coding agents from one machine.

A concrete walkthrough

Say you have four GitHub issues you want to push through tonight: #42 add OAuth, #43 fix flaky webhook test, #44 migrate util to TS strict mode, #45 wire up CSV export.

1. Open KanBots, pick the repo folder. The board loads with GitHub issues mirrored in.
2. Drag #42, #43, #44, #45 from Backlog to Todo. Click Dispatch on each. Four cards now show a pulsing “running” dot.
3. On disk you now have .kanbots/worktrees/issue-42-1/ through .kanbots/worktrees/issue-45-1/, each on kanbots/issue-<n>-1, each with a live claude -p against it.
4. One card opens a decision: “Refactor user.go or add a new file?” You click “Refactor”. The run continues. The other three keep working.
5. Each card hits In review as its run completes. You open the card, scroll the thread, hit Branch preview on #45 to see the export live. Hit Open draft PR. #42 needs another round — reply on the thread with a slash command (/review tighten the rate limiter) and the worktree resumes.

Nothing leaves the machine without you. The pre-push hook installed in every worktree blocks git push from inside the worktree, so an agent cannot accidentally publish a branch with half-written code. Promoting is always an explicit human action.

Common failure modes

Disk fills up with abandoned worktrees

Each worktree is a full checkout. Four parallel runs against a 2 GB monorepo cost you ~8 GB on disk plus whatever the agents write. The fix is to discard runs you do not keep: KanBots’s Discard button runs git worktree remove --force and deletes the branch. If you are doing this by hand, git worktree list shows everything; git worktree prunecleans up records of worktrees you rm’d the directory of.

Two runs race for the same review

If two agents finish at nearly the same moment and both ask for a decision, you will see two awaiting-decision prompts at once. Answer them in the order the work depends. The worker that does notget answered does not block the others — runs are independent. The race only matters when you intended one card to be a dependency of another; in that case dispatch them sequentially, not in parallel.

Cost runs away

Four Claudes is four times the burn rate. A naive setup has no cap; autopilot in KanBots ships per-session cost budgets that hard-stop the loop. See how to parallelize AI coding agents safely for the budget pattern and how it ties to the kanban status columns.

When this is the wrong tool

Parallel agent execution is the right hammer when the tasks are independent: separate features, separate bug fixes, separate refactors that touch disjoint files. It is the wrong hammer when:

• The tasks are inherently sequential — e.g. “migrate schema, then update all callers, then delete the old code.” Run those one card at a time.
• You are pair-debugging a single problem. Two Claudes on the same bug just produce two different fixes for you to compare; that is rarely faster than one Claude and a careful review.
• The repo is tiny. The setup overhead of worktrees + a board is not worth it for a weekend script.

For everything else — a backlog you want to drain, a refactor that fans out across modules, a Sentry queue of unrelated errors — parallel Claude Code in worktrees is the right shape. See the git worktree workflow for the exact commands, and can Claude Code work on multiple tasks at the same time for why this is the safe multiplexing pattern.