If you’re using Claude Code or CLI-based AI agents alongside your editor, Git worktrees are a superpower. They give you multiple, lightweight checkouts of the same repo so humans and agents can work in parallel—without stepping on each other.
Why worktrees > “just branches” in one folder
- True parallel sandboxes. Agents often run builds/tests/watchers. With worktrees you can run multiple dev servers, test runs, and editors side-by-side—no
git checkoutthrash, no editor re-indexing during branch switches, no dropped language-server state. - Stable file paths per task. Tools that cache absolute paths or embed them in prompts (Claude’s context, many CLI agents) don’t break when you switch branches. Each worktree keeps a stable path (e.g.,
../repo-fix-typo/), so logs, artifacts and prompts stay consistent. - Fewer Git lock fights. Agents and scripts can trigger
index.lockconflicts if they overlap. Separate worktrees = separate indexes; far fewer “Another git process seems to be running” errors. - Isolated dependencies. Each worktree can have its own
.venv,node_modules,.env, and build cache. That lets one agent install experimental deps without poisoning your main workspace. - Fast & space-efficient. Worktrees share the object database with the main repo, so they’re almost as cheap as a branch but behave like a separate checkout—much lighter than full clones.
- Better context for AI tools. Switching branches mid-session can confuse tools that snapshot the repo (RAG embeddings, context windows). Worktrees keep the code snapshot stable for the duration of the task, which improves answer quality and reduces “stale diff” mistakes.
- Long-running jobs stay alive. Background processes (linters, watchers, migrations) keep running in their own worktree while you code elsewhere. With one folder + branch switches, you’d constantly restart them.
- Side-by-side review. Open two branches at once to compare, test, or demo flows—no gymnastics.
- Great for monorepos. Build/test different packages concurrently without stepping on each other.
Compared to alternatives
- Separate clones: also isolate, but waste disk/time (fresh
.git, duplicate history) and slow down fetch/push. Worktrees share.git/objectsand remotes. - Stashes / WIP branches in one folder: still force frequent checkouts; easy to lose state and annoys AI tools relying on stable context.
- Git workspaces (some GUIs): usually wrappers around worktrees; the core benefits are from worktrees.
Quickstart: spin up an isolated worktree for an agent spike
# from your main repo folder
git fetch origin
# 1) Create an isolated checkout for an agent spike
git worktree add -b spike/agent-rewrite ../repo-agent-rewrite origin/main
# 2) Give it its own env & caches
cd ../repo-agent-rewrite
python -m venv .venv && source .venv/bin/activate # or: fnm use; pnpm i
cp ../repo/.env.example .env # isolate secrets/config
# 3) Point Claude/agent to this path
# (e.g., open this folder in editor; run the agent CLI here)
# 4) When done, merge back from *another* terminal in main worktree
cd ../repo
git checkout main
git merge --no-ff spike/agent-rewrite
git push
# 5) Clean up the sandbox
git worktree remove ../repo-agent-rewrite
git branch -d spike/agent-rewrite
git worktree pruneHandy commands
git worktree list # show all worktrees
git worktree add ../foo -b feature/foo
git worktree remove ../foo # removes the worktree folder safely
git worktree lock ../foo # prevent accidental deletionWorkflow: you need to do a quick task while another is already running
Local-only (no push). Merge back into your original branch later.
# From your repo root
BASE=$(git rev-parse --abbrev-ref HEAD) # remember current branch
TASK=feature/my-task
WT=../$(basename "$PWD")-${TASK##*/}
git worktree add -b "$TASK" "$WT" "$BASE" # create worktree from current branch
code -n "$WT" # or: cursor -n "$WT"# Inside the worktree — do work and COMMIT (merges bring commits)
cd "$WT"
git add -A
git commit -m "feat: implement my-task"# Back in the original repo folder — merge locally, then clean up
cd - # return to original repo
git switch "$BASE"
git merge --no-ff "$TASK" # OR: git merge --squash "$TASK" && git commit -m "feat: my-task"
git worktree remove "$WT"
git branch -d "$TASK"
git worktree pruneTip: if you want a linear history, do
git rebase "$BASE"inside the worktree before the merge, or use--ff-onlywhen possible.
Why this matters for AI-assisted dev
AI tools snapshot and reason about your codebase. Worktrees keep each agent’s view stable (consistent paths, caches, and build state), which cuts down on “stale diff” mistakes, reduces lock conflicts, and lets long-running jobs continue while you iterate elsewhere. In short: faster feedback, less friction, and cleaner merges.