Claude Code worktrees: parallel agents without collisions

Why worktrees

A git worktree is a second working directory for the same repository: its own files and its own branch, sharing history and the remote with your main checkout. Run two Claude Code sessions in one folder and they edit the same files; run them in two worktrees and each has its own copy.

Start a session in a worktree

claude --worktree feature-auth

Claude Code creates .claude/worktrees/feature-auth/ at the repository root, on a new branch worktree-feature-auth, and starts the session there. Run it again with another name in a second terminal for a second isolated session. Leave out the name and Claude makes one up.

Add the folder to .gitignore so the worktrees do not show up as untracked files:

.claude/worktrees/

You can also ask Claude mid-session to "work in a worktree", and it moves the session into one.

Which branch it starts from

By default a new worktree branches from the repository's default branch on the remote, freshly fetched, so it starts clean. To branch from your current local HEAD instead, with your unpushed work, set this in settings:

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

To start from a pull request, pass its number: claude --worktree "#1234".

Set up the environment

A worktree is a fresh checkout, so gitignored files such as .env are not there, and neither are installed dependencies. Two fixes:

• Copy secrets automatically with a .worktreeinclude file at the project root, in .gitignore syntax. Only files that match and are gitignored are copied:

.env
.env.local
config/secrets.json

• Install dependencies in the worktree, or ask Claude to. With pnpm, the shared store makes this fast.

Watch for ports: two dev servers on 3000 will fight. Give each worktree its own port through an env var.

Cleaning up

When you exit an interactive worktree session, Claude Code checks for work. A clean, unnamed worktree is removed with its branch. If there are changes or commits, it asks whether to keep the worktree; keep it and it prints the claude --worktree <name> --resume command to come back. Worktrees made for subagents and background sessions are swept after cleanupPeriodDays, unless they still hold unpushed work.

By hand, the usual git commands work: git worktree list, git worktree remove <path>.

Worktrees for subagents and background sessions

A subagent can run in its own temporary worktree. Add isolation: worktree to its frontmatter in .claude/agents/:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the refactor across every affected file, then run the tests.

Background sessions take the same flag: claude --bg --worktree fix-dates "Fix the flaky date test". Inside a worktree session, Claude Code blocks edits and git commands that would reach the main checkout, so a background agent cannot wander into your working copy.

What worktrees do not solve

Worktrees stop two agents writing the same file. They do not stop two agents doing the same task. Start three sessions on "the next thing in the backlog" and you can get three branches fixing one bug, each in a tidy worktree of its own.

That is a coordination problem, and it needs something every session can see:

• A claim per task. In Projectify, a session claims a task before it changes code, and the claim names its worktree and branch. Another session asking for work is told the task is held, by whom and in which worktree, and gets the next one instead.
• A lease, not a lock. The claim renews with every call and frees itself 30 minutes after the holder goes quiet, so a crashed session never blocks the board.
• A room per project. Sessions say when they start and warn before they touch something others depend on, such as a shared schema or a migration.
• A handoff at the end. The next session, in any worktree, starts from what this one did.

Let the board start the worktrees

The Projectify fleet goes one step further and creates the worktrees itself. projectify fleet starts each worker as claude --bg --worktree <task> in the project's repo, so every ready task gets its own branch, its own pull request and its own claim, and no two workers ever take the same task. Run Claude Code overnight shows the setup.

A checklist

1. .claude/worktrees/ in .gitignore.
2. A .worktreeinclude for the env files every session needs.
3. One port per worktree for dev servers.
4. One task per worktree, claimed on the board before the first edit.
5. One pull request per worktree; review on GitHub.

Projectify is free for one person with every feature, and agents never take a seat.