Run Claude Code in parallel with git worktrees

Claude Code is one process in one directory, and you can start as many as you want: a feature in one session, a bugfix or a review in another. What goes wrong is pointing two of them at a single checkout, then losing track of which terminal is sitting on a question.

Two sessions, one checkout

Two claude processes in the same folder share the files, the index, and git status. One session's edit lands in the file the other is halfway through. An install or a generated file changes the tree the other is reasoning about, and a commit in either session can pick up the other's unfinished work. Give each task its own checkout. A git worktree is a second working directory with its own branch, sharing that repository's history and remotes.

One worktree per session

Let Claude Code create it

From the repository, one terminal per task:

claude --worktree feature-auth

Claude creates .claude/worktrees/feature-auth at the repo root, on a new branch named worktree-feature-auth, and starts the session there. A second terminal, same repository:

claude --worktree fix-billing

Leave the name off and Claude generates one. Pass a name you already used and that worktree opens again. The directory has to be trusted first: run claude once in the repo and accept the dialog, or --worktree exits and tells you to. Add .claude/worktrees/ to .gitignore so those directories are not untracked files in the main checkout.

A new worktree branches from the remote's default branch, usually main. To start from your current HEAD, including commits you have not pushed, set worktree.baseRef to "head" in .claude/settings.json:

{
  "worktree": { "baseRef": "head" }
}

The worktree checks out tracked files only. node_modules and .env stay in the checkout where you created them, so install dependencies in the new directory. To copy gitignored files into every worktree Claude creates, add a .worktreeinclude at the repo root. Patterns work like .gitignore, and only gitignored files that match are copied:

.env
.env.local

When you leave an interactive session, a clean unnamed worktree is removed, branch included. A named worktree, or any worktree with changes or new commits, asks you to keep it or remove it. Keeping it prints a resume command to run from the main checkout:

claude --worktree feature-auth --resume

The flag, .worktreeinclude, and cleanup are documented at code.claude.com/docs/en/worktrees.

Or create the worktree yourself

Use git worktree add when the session should start on a branch that already exists, or when you want the folder beside the repo so searches in the main checkout do not walk every session:

cd ~/code/shop-web
git worktree add ../shop-web-auth -b feature/auth
git worktree add ../shop-web-billing fix/billing

-b creates the branch from your current HEAD. The second command checks out a branch that is already in the repository. Install, copy env, and start Claude there:

cd ~/code/shop-web-auth
npm install
cp ../shop-web/.env .env
claude

git worktree list shows every checkout. git worktree remove ../shop-web-auth deletes one you created, once its branch has landed or you have decided to drop it. Git refuses to check out a branch that another worktree already has, which keeps two sessions from committing onto one branch.

One tmux window or iTerm tab per session

A worktree isolates files. A permission prompt in a pane you are not looking at still waits until you find it. Give each session a window you can name.

tmux

One tmux session for the repo, one window per task. If Claude is creating the worktree, start in the main checkout. If you already ran git worktree add, start in that directory and run claude with no flag:

tmux new-session -s shop -n auth -c ~/code/shop-web
claude --worktree feature-auth

A second task stays inside shop, so one status line lists every session:

tmux new-window -n billing -c ~/code/shop-web-billing
claude

The prefix then n or p moves between windows. In ~/.tmux.conf, mark a window that prints while you are in another one:

set -g monitor-activity on
set -g visual-activity on

The window name highlights in the status line. A highlight means that window produced output: a session streaming a long edit highlights the whole time, and a session that was quiet and then highlights is the one to open.

Look at the bottom of the pane. A question is a numbered list with a footer that starts with Esc, and a digit answers it in one keystroke. A bare ❯ prompt is an idle agent. Claude's one-minute "still waiting for your input" reminder prints even when nobody asked you anything. Tall panes also leave blank rows under the dialog, so find the Esc footer before you decide the session is stuck.

tmux is also how replies get typed inside Ghostty, Warp, Alacritty, or Terminal. Those apps can show the agent, and Claude's hook can answer a question from outside. Typing into the terminal itself goes through tmux.

iTerm

In iTerm, use one tab per worktree: ⌘T, cd to the worktree, claude. Rename the tab to the branch (Session › Edit Session, or the tab's menu) so a row of identical titles becomes auth, billing, and main. Leave the tab activity indicator on. The mark means output arrived; open the tab and look for the Esc footer.

cmux

In cmux, each pane is already a session. Still use one worktree per pane, and start claude --worktree <name> in the pane the same way.

What still collides

• Same branch. git worktree add aimed at a branch that is already checked out fails. Pass -b.
• Dependencies. Each worktree has its own node_modules or virtualenv, so install again. .env stays behind unless you copy it or list it in .worktreeinclude.
• Ports and data. Two dev servers will fight over one port. Tell each session which port it owns. A local database, Docker, and caches are shared too.
• Stash. Worktrees share the stash and the remotes. git stash pop in one can pop a stash another session made. Commit on that session's branch instead.
• Merge time. package.json, route tables, and migrations get touched by almost every task. Land the shared change first. Two branches that each edit the same file still conflict.
• Permissions. "Yes, and don't ask again" in a worktree is saved in the main checkout's .claude/settings.local.json and then applies in every worktree of that repo.
• Usage. Several busy sessions spend the plan that many times faster, on one account. A subagent runs inside one session; a second conversation is a second window.
• Leftovers. git worktree list when you sit down. If remove says the path is locked, git worktree unlock it first. Removing a worktree Claude created also removes its branch.

Which session needs you

AgentDock reads Claude Code sessions you already started, from ~/.claude and, where it can, from the terminal. Creating the worktrees, merging, and launching Claude stay in the terminal. Each session is a dot on the screen edge: blue while the turn runs, amber when it is waiting on you, green when the turn finished, gray when idle. With the Claude Code hook on, amber means a permission prompt or a question dialog, and the one-minute reminder leaves the status alone. cmux reports that reminder as needs-input; AgentDock reads the pane and returns the session to idle when no dialog is showing. The hook applies to sessions started after you turn on Settings › Agents › Claude Code › Know when Claude Code needs you. Ghostty, Warp, Alacritty, and Terminal leave typing to tmux, so run Claude inside tmux there when you want the answer typed in.

The Inbox (⌃⌥I) collects the questions. The same digit answers the card. AgentDock waits two seconds, Esc takes it back, then it types into that tmux pane or iTerm tab, and clicking the dot jumps there. iTerm asks to be controlled the first time. cmux needs Socket Control Mode set to Password. The row shows the git branch, and a linked worktree is labeled with the repository name, so the sessions read as shop-web on worktree-feature-auth, on fix/billing, and on main. Group by repository (Settings › Appearance › Hover card) puts one repo together. ⌥⌥ sends a message from any app; auth: narrows to that branch, and ⇧↩ holds it until the session is idle. macOS asks for Accessibility permission the first time you use ⌥⌥.

Two sessions that still share a checkout and both change one file within 20 minutes get a red ring on both dots, and a notification if Settings › Inbox leaves it on. Separate worktrees are separate checkouts, so that ring stays off. After the trial the dots and hover card keep working. The Inbox and ⌥⌥ need a license.