Git worktree
Git worktrees let you check out multiple branches of the same repo into separate directories simultaneously — ideal for parallel AI coding agents.
Git worktrees let you have multiple branches of the same repository checked out in different directories at the same time. You keep one .git database but project several working trees from it — each is a normal directory that can build, run tests, and hold dirty changes independently. It's built-in functionality in Git, not a plugin.
Why it matters
For agentic coding, worktrees are the single best pattern for running parallel agents. Instead of one Claude Code session switching branches, you create a worktree per task and run one agent per worktree. No branch-switching, no stashing, no accidental cross-contamination.
SpaceSpider pairs naturally with worktrees: create one space per worktree, pick your CLI for each pane, and you have a fleet of isolated agentic workspaces on one machine. See /blog/git-worktrees-with-claude-code if we've published on this.
How it works
Core commands:
git worktree add ../myrepo-feature feature-branch— check outfeature-branchinto../myrepo-featuregit worktree list— show all worktreesgit worktree remove ../myrepo-feature— delete a worktreegit worktree prune— clean up stale entries
Each worktree has its own index, working tree, and HEAD, but they all share the same object database and refs. You cannot check out the same branch in two worktrees at once (unless you use --force), which protects you from split-brain commits.
How it's used
Common patterns:
- One worktree per in-flight feature branch, so you never need to stash
- Worktree for code review — check out a PR branch without disturbing your main worktree
- Worktree per agent — Claude Code here, Codex CLI there, each in its own directory
- Hotfix worktree that's always checked out to
mainfor emergency fixes
Related terms
- Space — SpaceSpider's workspace unit, pairs with worktrees
- Agentic coding — the workload worktrees accelerate
- Claude Code — works great one-per-worktree
- Checkpoint — complementary safety net
- Subagent — you can delegate a whole worktree to a subagent
FAQ
Do worktrees use extra disk?
Each working tree holds a full checkout, so disk use scales roughly linearly with number of worktrees. The .git object database is shared, which saves significantly over multiple full clones.
Can I convert an existing clone into a worktree setup?
Yes — keep your existing repo as one worktree and use git worktree add to create siblings. You don't have to re-clone.
What happens if I delete a worktree directory manually?
The worktree registration remains. Run git worktree prune to clean up stale entries.
Related terms
- Agentic codingAgentic coding is software development where an LLM-powered agent plans, edits, runs, and verifies code on its own using tools, not just autocomplete.
- AI pair programmingAI pair programming is a collaboration style where an LLM assistant sits alongside you, suggesting code and reviewing changes in real time as you work.
- ANSI escape codesANSI escape codes are control sequences that terminals interpret for colors, cursor movement, and screen clearing — the language of every modern CLI UI.
- Autonomous agentAn autonomous agent is an AI program that perceives, decides, and acts on its own toward a goal — the architecture behind modern coding CLIs.
- CheckpointA checkpoint is a saved snapshot of file state that lets you roll back an AI coding agent's changes to a known-good point.
- Claude CodeClaude Code is Anthropic's official command-line agent that plans, edits, runs, and verifies code across your repo using Claude models and tool use.