Guide ·
How to Run Multiple Claude Code Agents in Parallel With Git Worktrees (in Any Terminal, or TRMNLY)
Give each Claude Code session its own git worktree so parallel agents never edit the same files. Step-by-step commands, the gotchas, and how the TRMNLY terminal automates it.

To run multiple Claude Code agents in parallel, give each one its own git worktree: a separate checkout of the same repository, on its own branch, in its own folder. Start one claude session per worktree (claude --worktree <name> does both steps at once) and the agents can work at the same time without overwriting each other's edits.1,2
The rest of this guide covers the plain-git way, the problems you'll hit once three or four agents are running, and how the TRMNLY terminal handles the bookkeeping for you.
Why one checkout isn't enough
Two Claude Code sessions in one folder share one working tree. Agent A rewrites auth.ts while agent B is halfway through reading it, B's tests run against A's half-finished change, and both try to commit to the same branch. Separate terminal tabs don't help: the tabs are separate, the files aren't.
A worktree fixes that at the git level. Every worktree shares the repository's .git data, so creating one is fast and cheap, but each has its own files, its own index and its own checked-out branch.1
Doing it with plain git (any terminal)
You need a repository with at least one commit. From the repository root:
# one worktree per task, each on a new branch, beside the main checkout
git worktree add ../myapp-auth -b feature/auth
git worktree add ../myapp-billing -b fix/billing-rounding
# start an agent in each, in separate tabs or panes
cd ../myapp-auth && claude
cd ../myapp-billing && claude
Claude Code can also create the worktree for you. Run the same command with a different name in each terminal:2
claude --worktree feature-auth
claude --worktree fix-billing
When a branch is merged, clean up:
git worktree list
git worktree remove ../myapp-auth
git branch -d feature/auth
That is the whole technique. It works in iTerm2, Ghostty, Kitty, WezTerm, Warp or Apple's Terminal.
The gotchas at three or more agents
The worktree solves file collisions. It doesn't solve these:
- Untracked files don't come along. A new worktree is a clean checkout, so
.env,node_modulesand build caches are missing, and the agent's firstnpm testfails. Copy them in by hand, or use Claude Code's.worktreeincludefile, which lists the ignored files to copy into new worktrees.2 - Ports collide. Two agents both running
npm run devboth want port 3000. Give each worktree its own port, or have one agent stop its server before another starts. - You lose track of who is doing what. Six terminal tabs that all say
claudedon't tell you which agent is waiting on a permission prompt and which finished twenty minutes ago. - Removing a worktree deletes its folder. Commit and push before you clean up.
- Merging is still your job. Parallel agents produce parallel branches. Someone has to review them, open the PRs and resolve conflicts between them.
How TRMNLY does it
TRMNLY is a macOS terminal built on Ghostty, with git worktrees built into its projects. Here is what changes compared with doing it by hand.
A worktree in one keystroke. Select a project and press ⌃⌘N (New Worktree…). Give it a branch name and, if you like, a base ref. TRMNLY runs git worktree add, puts the checkout in <project>-worktrees/<branch> beside your project, and clones untracked files matching your env-copy globs (.env, node_modules, .next and so on) so the new checkout works without a fresh install.3
Tabs belong to a worktree. Each tab is tagged with its worktree, and the sidebar's tab list shows only the active worktree's tabs. ⌃⌘1–⌃⌘9 switch worktrees by position, and ⌃⌘] / ⌃⌘[ cycle through them. Shells export $TRMNLY_WORKTREE_BRANCH, so your prompt can say which checkout a pane is in.3
Claude Code uses TRMNLY's worktrees. With the MCP bridge connected, Claude Code gets TRMNLY's worktree_* tools and a trmnly-worktrees skill that tells it to create and switch worktrees through them, so each checkout is registered with the project and gets its env files. A worktree made another way can be registered with worktree_adopt.3
You can see which agent needs you. Every pane can report a title, status and progress with the trmnly command (trmnly set-status running, trmnly set-title "Auth"), and the sidebar shows it, so six agent panes don't all read claude.4
Pull requests from the worktree. The worktree menu has Open PR…, and Manage Worktrees… has Commit & Push…, Merge PR & Clean Up… and the rest for each row.3 The Worktrees lesson walks through it in 12 minutes.
Let a fleet work the board
If you have more tasks than you want to babysit, Fleet runs a pool of agents against the project's kanban board. You set how many workers (up to eight) and a budget, then press Start. Each worker claims a ready card, works it in its own worktree, can have its branch reviewed by another agent, and lands it under a policy you choose. The default opens a pull request and leaves the merge to you.5
Workers use an installed Claude Code, Codex or Gemini CLI first, so a long run bills against the subscription you already pay for, and TRMNLY's approvals and audit log still apply.5
Want several attempts at the same task instead? race_start gives one prompt to several agents, each in its own worktree, and race_pick keeps the branch you like and removes the others.5
Which approach should you use?
If you run two agents now and then, plain git worktree or claude --worktree in any terminal is enough, and it costs nothing. The overhead appears at three or more agents: copying env files, keeping track of tabs and status, and getting branches merged. That's where TRMNLY saves time. We wrote more about the design in Five agents, five branches, one repo, and /compare shows how other agent workspaces handle worktrees.
TRMNLY is a $99 one-time seat that includes 12 months of updates, with optional $69 renewals. It's invite-only while in early access. Request access to try it. To have Claude Code drive those worktrees, panes and ports itself, see TRMNLY as an MCP server for Claude Code.
Sources
- 1.Git documentation, "git-worktree: Manage multiple working trees." git-scm.com
- 2.Claude Code docs, "Common workflows: Run parallel sessions with worktrees" and "Worktrees." code.claude.com
- 3.TRMNLY docs, "Worktrees." trmnly.dev/docs/worktrees
- 4.TRMNLY docs, "Pane manifests, flags, and the
trmnlyCLI." trmnly.dev/docs/pane-manifests - 5.TRMNLY docs, "Fleet." trmnly.dev/docs/fleet