Git Worktrees for AI Agents Intro: How to use them and why
The decade-old Git feature is now essential for running parallel AI coding agents.
Git worktrees shipped in 2015. For a decade, most developers never touched them. Then AI coding agents arrived, and suddenly a feature designed for emergency hotfixes has became the backbone of parallel local agentic development.
“Really love the worktree management… I built worktree support into @VibeTunnel” — Peter Steinberger @steipete
At Ramen Space, the watercooler discussions about worktrees have surged. Why? Running many agents in the same directory is chaos, using git worktrees is the easy fix (for now).
The Shared Workspace Problem
Two agents editing the same workspace (ie. working directory) is a recipe for corrupted state. Agent A writes to OrderService.ts while Agent B is reading it. Agent A runs npm build while Agent B is mid-refactor. You’ve probably hit this wall if you’re using Claude Code, Cursor, or any agentic coding tool.
Git worktrees solve this by giving each agent its own isolated working directory. Same .git database, different folders. Each agent operates on its own branch without stepping on anyone’s files.
How Git Worktrees Work
A worktree is a linked working directory attached to your repository. Create one with:
git worktree add ../agent-feature-1 -b feature/task-1Now you have a separate folder with a complete checkout. Your AI agent works there while you continue in main. When the task is done, merge the branch and remove the worktree.
The productivity advantage is immediate. Developers running 3-5 parallel Claude Code sessions in worktrees report 5x throughput gains. The incident.io team runs 4-5 agents in parallel using this pattern, completing work in hours that previously took days.
Git Worktrees Pros and Cons for AI Agents
| Pros | Cons |
|---|---|
| Complete filesystem isolation — agents can’t corrupt each other’s state | Disk usage grows — node_modules and build artifacts multiply per worktree |
| No context pollution — each agent starts fresh without inherited cruft | Setup repetition — dependencies don’t carry over; each worktree needs npm install |
| Parallel development — run 3-5+ agents simultaneously on separate tasks | Port conflicts — dev server default’s can be tricky (eg. 3000, 5432, 8080) |
| Simple merging — standard git branch workflow, nothing special | Tooling quirks — some editors and language servers get weird with multiple instances |
| Shared git history — objects stored once, branches linked to same repo | Manual cleanup required — forgetting to prune leaves stale references |
Developer Experiences with Worktrees
Not everyone is happy:
“It’s easiest to run parallel agents each in their own git branches checked out into their own worktrees. The problem is git worktree UX is horrible.” — banteg (@banteg)
Banteg’s point is fair. Native git worktree commands are verbose. That’s why tools like Worktrunk, git-wt, and Cursor’s built-in automation have emerged to smooth the rough edges.
When to Skip Worktrees
Not every task needs isolation:
- Quick bug fixes (under 30 minutes) — overhead isn’t worth it
- Tightly coupled features — two agents touching the same files will create merge conflicts regardless
- Near API rate limits — parallel agents burn quota faster
- Run dangerously! — if you like to live on the edge, just fire up many agents in one workspace! Losing is fun!
The rule of thumb without worktrees: if two tasks could cause a merge conflict, don’t run them in parallel.
What’s Next
The general vibe is that worktrees are, for now, a necessary challenge for those looking to jump in early. If you want to avoid the pain, use a worktree automation tool (Flocker does).
It seems likely that inter-agent communication will reduce the need in the near future… if providers can agree on a mechanism.
Further reading:
- What 371 Git Worktrees Taught Me About Multi-Agent AI
- How Git Worktrees Changed My AI Agent Workflow
- Worktrunk CLI — worktree management for agent workflows