Worktrees and multi-repo work

Once you're comfortable with Claude Code, you'll hit a wall that every productive user hits: you want to work on more than one thing at a time. A long-running task on branch A. A quick experiment on branch B. A code review on branch C. If you only have one checkout of your repo, switching between them means stashing, checking out, losing context, going back, hoping nothing got tangled.

Git worktrees fix this. Combined with Claude Code, they unlock running parallel agents on the same project without interference.

What a worktree is

Normally, one git repo = one folder on disk. Whatever branch you have checked out is what you see. A worktree is an additional folder linked to the same repo, with a different branch checked out. The underlying history is shared; the working files are separate.

# In your existing repo
git worktree add ../my-project-experiment experiment-branch

# Now you have two folders:
#   ~/Projects/my-project/             (main checked out)
#   ~/Projects/my-project-experiment/  (experiment-branch checked out)
# Both connected to the same git history.

Each worktree behaves like its own copy. You can run different builds, run different tests, run different Claude Code sessions — and none of them know about each other.

Why this matters for Claude Code

Three things become possible:

• Long-running work doesn't block quick work. Claude is grinding on a big refactor in worktree A; you start a fresh session in worktree B to answer a quick question.
• Parallel agents on the same codebase.Three worktrees, three Claude sessions, three branches — all progressing simultaneously. The branches don't collide because each session only sees its own folder.
• Risk isolation.If Claude takes a wrong turn in one worktree, the others are untouched. Delete the worktree, you lose only that branch's in-progress work.

A practical workflow

Here's a pattern that scales:

1. Keep your "main" checkout on the main branch for quick reviews and pulls.
2. For each big task, git worktree add ../proj-task-name task-name and start a Claude session there.
3. When the task is done and merged, git worktree remove ../proj-task-name to clean up.

Three or four active worktrees is comfortable. Beyond that, you start losing track of which is which. Name folders clearly —proj-billing-refactor not proj-task-3.

The isolated-worktree pattern

Claude Code can also create temporary worktrees on its own. When you spawn a subagent with an isolation flag, it works inside a fresh git worktree, makes its changes there, and you end up with a branch (or set of changes) you can review without any of it touching your primary checkout.

This is particularly useful for risky tasks: experimental refactors, large dependency upgrades, things where you want the option to throw the whole attempt away. The worktree is the "quarantine" container.

Multi-repo work

Sometimes a task crosses repo boundaries. The frontend lives in one repo, the backend API in another, a shared library in a third. The Claude Code default — one session, one project folder — chafes here.

The patterns that work:

• One session per repo, coordinated by you. Three terminal tabs, three Claudes, you carry decisions between them. Most explicit.
• One umbrella folder with multiple sub-repos. Start claude from the parent folder. It can see all three repos. Convenient, but the context budget gets spent fast and Claude may struggle to know which repo a given change should live in.
• One session per repo, with one acting as coordinator. A primary Claude that calls subagents (which can be pointed at the other repos) to handle work there.

For most real multi-repo work, option one (you as the human coordinator) is the most reliable. Claude Code is improving at cross-repo work; the limits of today are not the limits of tomorrow.

Discipline that keeps the parallel mode sane

Running three agents at once feels powerful, and it is — until you lose track of which one is doing what and end up with a merge conflict you can't untangle. A few habits to keep in place:

• One concern per worktree.Don't spread a single task across multiple worktrees. Don't mix two tasks in one.
• Merge often. Long-lived branches go stale fast. Merge from main into your worktree daily.
• Close worktrees you're done with.Stale worktrees become forgotten worktrees become "wait, what was I doing in this one?"
• Keep a short list.A sticky note, a quick markdown file, anything that says "what's in each worktree right now." A minute of bookkeeping prevents an hour of confusion.