Claude Code + Git Worktree - Run Multiple AI Agents in Parallel

The Problem: One Claude Code, One Branch, One Task at a Time

When you run Claude Code in a repository, it operates on whatever branch is currently checked out. That sounds obvious — until you realize it means:

  • ❌ You can only run one Claude Code task at a time per repo
  • ❌ Each task blocks you from working on anything else
  • ❌ If Claude modifies files mid-task, you can't test or review another branch in parallel
  • ❌ Long-running agents (5-20 min) mean massive idle time

The fix isn't to work slower — it's to work in parallel. And the primitive that makes parallel Claude Code possible is git worktree.

This guide shows you exactly how to wire them together — both by hand, and with ParallelCode's one-click UI.

Why git worktree Is the Right Tool for Claude Code

A git worktree is a second (or third, or tenth) working directory attached to the same repository, each on its own branch. Because they share the object database, they're cheap. Because they're physically separate folders, Claude Code running in one cannot touch files in another.

That gives you three things simultaneously:

  1. Isolation — each Claude instance sees only its own branch's files
  2. Parallelism — N agents, N worktrees, N terminals, N tasks running at once
  3. Safety — a buggy task in one worktree cannot corrupt work in another

New to worktrees? Start with the Git Worktree Complete Guide.

The Manual Setup: Claude Code + git worktree by Hand

Here's the raw workflow, no tooling. You'll see how simple the primitive is.

Step 1: Create a Worktree for Your Task

# From your main repo
cd ~/projects/myapp

# Create a worktree for a new feature
git worktree add ../myapp-feat-auth -b feat/auth origin/main

This creates ~/projects/myapp-feat-auth/ on the feat/auth branch.

Step 2: Launch Claude Code in the Worktree

cd ../myapp-feat-auth
claude

Claude Code starts with the worktree as its CWD. It sees feat/auth, not main. Any file edits, any commits, stay in this worktree.

Step 3: Repeat for Parallel Tasks

Open a second terminal:

cd ~/projects/myapp
git worktree add ../myapp-feat-search -b feat/search origin/main
cd ../myapp-feat-search
claude

Now you have two Claude Code sessions running simultaneously, on two different branches, completely isolated.

Add a third if you want:

git worktree add ../myapp-fix-login -b fix/login-bug origin/main
cd ../myapp-fix-login
claude

Step 4: Merge What Works, Discard What Doesn't

When Claude finishes a task:

# In the worktree: review changes
git diff main

# If you like them: push the branch
git push -u origin feat/auth

# Merge via PR, or locally:
cd ~/projects/myapp
git merge feat/auth

# Clean up the worktree
git worktree remove ../myapp-feat-auth
git branch -d feat/auth

If Claude did something wrong, just delete the worktree and branch — zero impact on your main work.

A Concrete 3-Task Parallel Example

Say you have a Friday afternoon and three tickets:

  1. AUTH-42: Add "forgot password" flow
  2. SEARCH-17: Improve search ranking
  3. BUG-203: Fix a timezone display bug

Old way (sequential, ~4 hours)

15:00 — Claude works on AUTH-42     [you wait]
15:45 — Review AUTH-42, commit, checkout main
15:55 — Claude works on SEARCH-17   [you wait]
16:40 — Review SEARCH-17, commit
16:50 — Claude works on BUG-203     [you wait]
17:20 — Review BUG-203, commit, done

You spent 2h 20min waiting.

Worktree way (parallel, ~1 hour wall clock)

git worktree add ../myapp-auth-42   -b AUTH-42   origin/main
git worktree add ../myapp-search-17 -b SEARCH-17 origin/main
git worktree add ../myapp-bug-203   -b BUG-203   origin/main

Three terminals, three claude sessions, all kicked off at 15:00. By 15:50 all three are done, and you spend 16:00–17:00 reviewing three PRs instead of writing code in idle time.

Time saved: ~2-3 hours per batch. Do this twice a week, that's a whole day back.

The Gotchas Nobody Warns You About

Running Claude Code in worktrees works great — after you survive these rough edges.

1. node_modules isn't shared

Each worktree is a separate folder. Claude Code will happily run pnpm install in each of them, duplicating node_modules across 3 worktrees = 3× disk usage.

Fix: Use pnpm (content-addressable store, dedupes automatically) or configure a shared cache:

# .npmrc in each worktree (or globally)
store-dir=~/.pnpm-store

For Python, uv's global cache solves the same problem.

2. Dev servers fight over ports

Claude spins up pnpm dev on port 3000. Second worktree's Claude tries port 3000 → crash.

Fix: Teach Claude (via CLAUDE.md or slash commands) to pick a free port, or set PORT differently per worktree:

# In each worktree
echo "PORT=3001" > .env.local  # different number per worktree

3. .env files don't copy

.env is (rightly) gitignored. When you create a new worktree, it starts without secrets, and Claude can't run the app.

Fix: After git worktree add, copy:

cp ../myapp/.env ../myapp-feat-auth/.env
cp ../myapp/.env.local ../myapp-feat-auth/.env.local

Or write a small wrapper script.

4. Hooks running in the wrong directory

.git/hooks/ lives in the main repo. A hook that does cd "$(pwd)" will cd into the current shell's pwd, which is fine — but a hook that uses $GIT_DIR may resolve to the main repo, not the worktree.

Fix: In hooks, use git rev-parse --show-toplevel to find the current worktree root:

WORKTREE_ROOT="$(git rev-parse --show-toplevel)"
cd "$WORKTREE_ROOT"

5. Claude Code's permissions/allowlist

Claude Code reads per-project settings from .claude/settings.json. Each worktree has its own copy (since it's under the worktree's root). If you want all worktrees to share your allowlist, keep it in ~/.claude/settings.json (user-level) instead.

6. You'll forget which worktree is which

After a week of parallel work, you have myapp, myapp-feat-auth, myapp-feat-search, myapp-fix-login, myapp-old-experiment, and can't remember which is live.

Fix: git worktree list — this is your best friend. Run it every morning.

Why Teams Move from "Manual Worktree" to ParallelCode

Once you've run this for a week, the friction becomes obvious:

  • Creating a worktree = 3-4 commands + .env copy + install
  • Launching Claude = another command + waiting for context
  • Cleanup = worktree remove + branch delete + check for uncommitted work
  • Status overview = git worktree list + remember which branch does what

This is exactly the UI ParallelCode builds on top of git worktree + Claude Code:

Manual workflowParallelCode
git worktree add ... && cd ... && cp .env && pnpm i && claudeOne click
Track worktrees in your headVisual dashboard
Terminal tab soupTabbed agent sessions in one window
Manual cleanupArchive / delete / merge buttons
claude CLI onlyClaude Code + Cursor Agent + local agents side-by-side

You can absolutely do this with raw shell scripts — but once you're running 3+ agents daily, the click-driven version pays for itself in a week.

Download ParallelCode — Free →

Keyboard-Only Power Setup (for Terminal Purists)

If you live in tmux/zellij, here's the closest you'll get to a ParallelCode workflow without a GUI.

1. Install the worktree shortcut

Add to your shell (.zshrc / .bashrc):

wt() {
  local branch="$1"
  local repo_name="$(basename "$(git rev-parse --show-toplevel)")"
  local dir="../${repo_name}-${branch//\//-}"
  git worktree add "$dir" -b "$branch" origin/main
  cp .env "$dir/.env" 2>/dev/null
  cp .env.local "$dir/.env.local" 2>/dev/null
  cd "$dir"
  echo "✓ worktree ready: $dir"
}

Now wt feat/auth does the whole setup.

2. Claude Code in a tmux layout

# New tmux window with 3 panes, each in its own worktree
tmux new-window -n parallel
tmux split-window -h && tmux split-window -v
tmux select-pane -t 0 && tmux send-keys "cd ../myapp-feat-auth && claude" C-m
tmux select-pane -t 1 && tmux send-keys "cd ../myapp-feat-search && claude" C-m
tmux select-pane -t 2 && tmux send-keys "cd ../myapp-bug-203 && claude" C-m

Bind this to a key and you're flying.

3. Prune dead worktrees weekly

Friday afternoon habit:

git worktree list | grep -v main
# Identify stale ones, then:
git worktree remove ../myapp-old-experiment
git branch -D old-experiment

Anti-Patterns to Avoid

After watching hundreds of devs adopt this workflow, the common mistakes:

❌ One worktree, branch-switching inside it Defeats the purpose. Each long-running task = one worktree.

❌ Running Claude on main in the main repo One slip and Claude commits to main. Always use a worktree with a feature branch.

❌ Never cleaning up 30 worktrees after a month. git worktree list becomes unreadable. Set a "Friday cleanup" ritual.

❌ Running Claude Code and a human editor in the same worktree Claude rewrites files, your editor reloads, you lose unsaved changes. Use separate worktrees for "your work" vs "agent work."

❌ Sharing a worktree between two agents Claude Code and Cursor Agent writing to the same files = chaos. One agent per worktree.

Claude Code + Worktree FAQ

Q: Does Claude Code know it's in a worktree? A: It sees a normal-looking Git repo. It can read .git metadata and will honor the current branch. No special awareness needed.

Q: Can Claude Code create worktrees itself? A: Yes — you can allow git worktree add in .claude/settings.json and ask Claude to spin up a worktree for itself. Some users do this as an autonomous "branch per task" pattern.

Q: Does /resume work across worktrees? A: Session state is per-directory. A session started in myapp-feat-auth/ is resumed from that worktree. Moving the worktree breaks the path; avoid it.

Q: Will my MCP servers conflict between parallel sessions? A: Most MCP servers handle concurrent connections fine. If one holds an exclusive lock (e.g., a local SQLite), run it as a shared process, not per-session.

Q: What about secrets and API keys? A: Use ~/.claude/settings.json (user-level) for API keys so every worktree inherits them. Project-level .claude/settings.json per worktree for project-specific tools.

Q: Can I do this with Cursor Agent too? A: Yes — the same worktree pattern works for Cursor Agent, Aider, Codex, or any CLI-based AI tool. ParallelCode supports mixing them in one dashboard.

Stop running one Claude Code at a time.

ParallelCode wires git worktree + Claude Code + Cursor Agent into a single dashboard. Create a worktree, launch an agent, switch tasks — all without leaving the UI.

Free, open source, works with your existing Git repos.

Download ParallelCode → · Quick Start →

Related posts