Git Worktrees and Parallel Feature Work

Auth feature. Critical bug. New API endpoint someone just asked for. Normally you grind through these one at a time. Branch, work, commit, switch, repeat.

What if you ran three Claude Code sessions at once, each on its own branch, none of them stepping on each other?

Git worktrees let you do exactly that. Multiple working copies of your repo, each on a different branch, all sharing the same .git history. Claude Code has a --worktree flag that handles setup.

What Git Worktrees Actually Are

A worktree is another checkout of your repo. Same .git directory under the hood, completely separate folder on disk with its own branch.

Your main repo lives at ~/projects/my-app. A worktree might live at ~/projects/my-app/.claude/worktrees/feature-auth/. All your files, its own branch, its own working state. Changes in one worktree don't touch another.

Don't confuse this with creating a branch. Branches share one set of files on disk. You stash or commit before switching. Worktrees give each branch its own directory. No stashing. No context switching. No "oh no I forgot to commit before checking out."

Three terminals, three Claude Code instances, three features progressing at the same time.

Using Worktrees with Claude Code

The --worktree (or -w) flag handles the whole thing. Creates the worktree, checks out a new branch, starts a session inside it.

claude --worktree feature-auth

This creates a worktree at <your-repo>/.claude/worktrees/feature-auth/ on a branch called worktree-feature-auth, based on your default remote branch. Clean, up-to-date code.

Spin up as many as you want:

claude --worktree feature-auth
claude --worktree bugfix-123
claude --worktree new-api-endpoint

Three terminals, completely isolated from each other.

No name in mind? Just pass the flag bare:

claude --worktree

Claude Code generates a random name like bright-running-fox. Fun, but you'll want meaningful names so you remember what each one is doing.

You can also create worktrees mid-session. Tell Claude Code "work in a worktree" during your conversation and it sets one up on the spot.

Try it

Open two terminal windows. In the first:

claude --worktree add-tests

In the second:

claude --worktree fix-navbar

Give each session a different task. When both finish, two branches ready for review. No merge conflicts from interleaved work.

Cleanup

When you exit, Claude Code checks for uncommitted or unpushed changes. Clean worktree? Removed automatically, branch deleted.

Changes still hanging around? Claude Code asks whether to keep or remove. You won't accidentally lose work.

Dependencies

This catches people off guard: each worktree is a fresh directory. Your node_modules don't come along.

# Inside your worktree session, make sure to run:
npm install

Same for virtual environments, compiled assets, anything that lives outside version control.

Best Practices

Add worktrees to .gitignore. Claude Code stores them in .claude/worktrees/. Keep that out of version control.

echo ".claude/worktrees/" >> .gitignore

Subagent worktrees for complex tasks. Tell Claude Code "use worktrees for your agents" and each subagent gets its own isolated worktree. They run in parallel, don't interfere with each other or your main session, and clean worktrees get auto-cleaned when the subagent finishes.

Set it up in agent configuration frontmatter:

---
isolation: worktree
---

Any agent using this config always runs in its own worktree.

Keep worktree tasks focused. One thing per worktree. "Add user authentication" is fine. "Refactor everything and also add auth and fix the navbar" is asking for merge headaches later.

Manual worktree management works too. You don't have to use the --worktree flag. Plain git:

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a
claude

More control over where the worktree lives on disk. Clean up when you're done:

git worktree remove ../project-feature-a

Merge promptly. Worktrees reduce conflicts during development but long-lived parallel branches still diverge. Merge back into main regularly. Don't let them drift.

Key Takeaways

--worktree (-w) creates an isolated worktree, branches from your default remote, and starts Claude Code inside it. Each worktree is a separate directory with its own branch, so multiple Claude Code sessions can't conflict. Clean worktrees auto-remove on exit; dirty ones prompt you. Subagents can each get their own worktree for parallel subtask execution. Remember to install dependencies in each new worktree and add .claude/worktrees/ to your .gitignore.