How to run Claude Code agents in parallel

To run Claude Code agents in parallel, give each agent its own git worktree on its own branch, start one Claude Code session in each, and merge the branches back one at a time. That keeps agents from editing each other's files. On one account, though, every session draws from the same limit.

Why one folder isn't enough#

Two agents in one folder share one working tree, one index and one checked-out branch. If one is halfway through rewriting auth.ts, the other's npm test runs against the half-written file. If one runs git stash, the other's uncommitted edits go into the stash with it, and git commit -a from either one commits both agents' work under one message.

A git worktree is the fix. Anthropic's docs describe it as "a separate working directory with its own files and branch, sharing the same repository history and remote as your main checkout". Each session "gets a separate copy of the files to edit, so one session can build a feature while a second fixes a bug" (Claude Code docs). Why every chat gets its own git worktree is our case for making it the default in Shuriken.

The commands#

With plain git#

git worktree add ../myapp-feat-api -b feat-api
git worktree add ../myapp-fix-login -b fix-login

cd ../myapp-feat-api && claude      # terminal 1
cd ../myapp-fix-login && claude     # terminal 2

git worktree list                   # see them all
git worktree remove ../myapp-feat-api   # when it's merged

With Claude Code's --worktree#

Claude Code makes the worktree itself: "Pass --worktree or -w with a name to create an isolated worktree and start Claude in it" (Claude Code docs).

claude --worktree feat-api      # terminal 1
claude --worktree fix-login     # terminal 2

By default the checkout goes in .claude/worktrees/<name>/ on a new branch called worktree-<name>, so claude --worktree feat-api works on worktree-feat-api. Add .claude/worktrees/ to .gitignore. On exit, Claude Code deletes a clean worktree without asking only if you never named the session; otherwise it asks. Pull request checkouts, hooks and the rest of the flag's rules are in Claude Code --worktree, explained.

Two defaults catch people out. A worktree is a fresh checkout, so .env and node_modules aren't in it: run your install in each one, and name the gitignored files to copy (.env, .env.local) in a .worktreeinclude file at the project root. And new worktrees branch from your default branch, not from whatever you have checked out; set worktree.baseRef to "head" in settings to start them from your current work.

How many agents at once?#

Anthropic publishes no cap on separate sessions. What stops you is the machine and the plan.

Your machine#

• Memory: each session is its own claude process, and each one starts more of them (test runners, dev servers, tsc --watch). Five sessions with a dev server and a test watcher each are fifteen processes.
• Disk: each worktree is a full checkout plus whatever you install. The .git history is shared, but node_modules is not, so du -sh node_modules in one worktree times the number of worktrees is roughly the bill.
• Review: every branch ends as a diff someone has to read before it merges.

Your plan#

On a Claude subscription every session on one account counts against the same limits. Anthropic's help page says limits "are shared across Claude and Claude Code, meaning all activity in both tools counts against the same limits", and that Pro and Max both "have a five-hour session limit and a weekly limit" (Anthropic).

Five busy agents on one account therefore move through its 5-hour window about five times as fast as one. That's division, not a benchmark, and Anthropic's cost docs point the same way: spend varies with "usage patterns such as running multiple instances or automation", and for agent teams "token usage is roughly proportional to team size" (Claude Code docs). Claude's weekly limit, explained has the numbers for the limit that hurts most.

Conflicts and port clashes#

Worktrees keep agents apart on disk. Three collisions remain.

1. Merge conflicts. If two agents both change routes.ts, the second merge stops with CONFLICT (content), worktrees or not. Give agents different areas (API, UI, tests), merge one branch, run git rebase main in the next, and go again. A branch merged the day it is done collects fewer conflicts than one that waits for Friday. Resolving merge conflicts with Claude Code has the prompt we give Claude when a rebase stops anyway.
2. Ports. Every worktree has the same package.json, so every dev server asks for the same port: 3000, or 5173 for Vite. The second one fails with EADDRINUSE, or moves to 3001 without saying so, and an agent then tests the wrong branch on localhost:3000. lsof -i :3000 shows which process holds it. Read the port from a PORT variable, one per worktree (if .worktreeinclude copies the same .env into each, change PORT after the copy), and make the server exit when its port is taken; in Vite that is server.strictPort: true.
3. Shared state outside git. One local Postgres, one Docker volume, one fixtures folder in /tmp: two agents running migrations against the same database will break each other. Give each worktree its own database name, or run the agents that need it one after another.

Tools that do this for you#

By hand works; Claude Code sessions in tmux sets up one pane per worktree. These tools wrap the same idea. We read each one's own description on 22 October 2026.

Best tools for parallel coding agents lists more, with where each one fits better than Shuriken.

How Shuriken does it#

We built Shuriken around parallel chats because we work that way.

• Every chat except the Main chat gets its own branch in its own git worktree, made when the chat starts. The Main chat works on your own branch, for quick changes in place.
• Shuriken sets no limit on how many chats run at once. Your machine and your plans do. If you want a floor, two queue settings, Hold below free memory and Hold below battery, make new work wait below the GB or percentage you pick, and the waiting chat says which one it is waiting on.
• Claude Code in one chat, Codex or Gemini CLI in the next, on the same repo.
• Finish runs the checks listed under checks in shuriken.json, then rebases and squash-merges, or opens a pull request with auto-merge (Finish has every step).
• Activity shows subagents, workflow phases and background commands live, with an "N running" pill.
• Run on…, in the chat's menu, moves a chat to another of your computers or servers. It gets the repo there and the same chat carries on, with its uncommitted work and history. That helps when the laptop runs out of memory.
• Several Claude accounts work as a pool. When the one in use reaches your switch point, 99% by default, its chats move to the account with the most room, a Claude Code chat on its next request. Use only accounts you own and are entitled to use; providers' terms may not allow sharing a subscription sign-in.

The parallel agents page has the rest. If you'd rather have the worktrees made, merged and cleaned up for you, download Shuriken.