--- title: "Claude Code worktrees: parallel agents without collisions" description: "Run parallel Claude Code sessions in git worktrees: claude --worktree, .worktreeinclude, cleanup, subagent isolation, and one task per worktree." url: https://projectify.si/guides/claude-code-worktrees updated: 2026-10-28 --- # Claude Code worktrees: parallel agents without collisions > Run claude --worktree (or -w) and Claude Code creates a git worktree under .claude/worktrees/ on a new branch worktree-, then starts the session in it. Each session edits its own files, so two sessions never overwrite each other. Worktrees stop file collisions; a claim on a board stops two sessions doing the same task. ## 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 ```bash 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: ```text .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: ```json { "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: ```text .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 --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 `. ## Worktrees for subagents and background sessions A subagent can run in its own temporary worktree. Add `isolation: worktree` to its frontmatter in `.claude/agents/`: ```markdown --- 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 ` 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](/guides/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. ## Run parallel Claude Code sessions in worktrees: the steps 1. **Ignore the worktree folder.** Add .claude/worktrees/ to .gitignore. 2. **Copy local config.** List .env and other gitignored files every session needs in .worktreeinclude. 3. **Start each session in its own worktree.** Run claude --worktree in a separate terminal per session. 4. **Claim one task per worktree.** Have each session claim its task on the board, naming its worktree and branch. 5. **Open one pull request per worktree.** Push the branch, open a PR and let the worktree be cleaned up on exit. ## Questions ### How do I use git worktrees with Claude Code? Run claude --worktree . Claude Code creates .claude/worktrees/ on a new branch worktree- and starts the session there. Run it again with another name for a parallel session. ### How do I copy .env files into a Claude Code worktree? Add a .worktreeinclude file at the project root in .gitignore syntax, listing files such as .env and .env.local. Files that match and are gitignored are copied into every new worktree. ### Do worktrees stop two Claude sessions doing the same task? No. Worktrees isolate files, not work. To keep sessions off the same task, have each one claim the task on a shared board first; Projectify claims carry the worktree and branch. Start free: https://app.projectify.si/signup. More guides: [Claude Code agent teams: run a team of agents on one board](https://projectify.si/guides/claude-code-agent-teams.md), [Claude Code agents: subagents, background agents and fleets](https://projectify.si/guides/claude-code-agents.md), [Run Claude Code overnight: a fleet that works your board while you sleep](https://projectify.si/guides/run-claude-code-overnight.md), [Project management for Claude Code](https://projectify.si/guides/claude-code-project-management.md), [Linear pricing explained, and what Projectify costs](https://projectify.si/guides/linear-pricing.md), [Jira pricing explained, and a simpler option](https://projectify.si/guides/jira-pricing.md).