Git Worktrees for AI Coding Agents: The Isolation Standard

Published July 10, 2026 · by the AQ team

A git worktree is an additional working directory attached to the same repository: one repo, many checkouts, each on its own branch. For AI coding agents, worktrees have become the standard isolation mechanism because they give every agent a private copy of the files without the cost of a second clone.

This guide explains what worktrees are, why agents need them, the exact commands to manage them by hand, the gotchas that bite in practice, and how AQ automates the whole lifecycle.

What is a git worktree?

By default a git repository has exactly one working directory. git worktree add creates more: extra directories that share the same object database and refs but hold independent checkouts. Edits, builds, and test runs in one worktree never touch the files in another.

Two rules define the model:

• One repo, many working directories. All worktrees share history, objects, and remotes. A commit made in any worktree is instantly visible to all of them, and a fetch in one updates the refs for all.
• One branch per worktree. Git refuses to check out a branch that is already checked out in another worktree. This constraint is a feature: it makes "which directory owns which branch" unambiguous.

Compared to cloning the repo again, a worktree is faster to create, shares disk for git objects, and keeps everything under one remote configuration.

Why are worktrees the standard isolation for coding agents?

An AI coding agent is an aggressive concurrent writer. It edits many files per minute, runs formatters and test suites, and sometimes stages or commits. Put two agents (or one agent and one human) in the same checkout and they overwrite each other's edits, race on the index, and produce test failures neither caused.

Worktrees solve exactly this class of problem:

• File isolation. Each agent sees only its own working tree. No clobbered edits, no dirty-state surprises.
• Branch isolation. Each agent's work lands on its own branch, so every task maps cleanly to one reviewable PR.
• Cheap creation and teardown. Spinning up isolation per task is a one-second git operation, not a multi-minute clone.
• Shared history. Agents can still rebase onto the latest main, because all worktrees see the same refs.

Containers and full clones also provide isolation, but worktrees hit the sweet spot for agents: strong enough to prevent interference, light enough to create one per task without thinking about it.

The manual commands

Create a worktree with a new branch, work in it, and remove it when done:

# From your main checkout: new directory, new branch
git worktree add ../myapp-fix-auth -b fix/auth-timeout

# Or base it explicitly on the latest remote main
git fetch origin
git worktree add ../myapp-fix-auth -b fix/auth-timeout origin/main

# See every worktree and its branch
git worktree list

# When the work is merged: remove the directory, then the branch
git worktree remove ../myapp-fix-auth
git branch -d fix/auth-timeout

# Clean up records of worktrees whose directories were deleted by hand
git worktree prune

That is the whole API surface you need day to day: add, list, remove, prune.

What are the gotchas with git worktrees?

• Shared refs cut both ways. Because worktrees share one ref store, you cannot check out the same branch twice, and a branch deleted in one worktree disappears for all. Force-operations on refs (rebases, resets) in one worktree can surprise an agent working in another if they touch shared branches. Keep each agent on its own branch and rebase only its own branch.
• Dependencies are per worktree. node_modules, virtualenvs, and build caches live in the working directory, so every new worktree needs its own install. For a JavaScript repo that is often the slowest step of setup by far, and it is the one people forget: the agent starts, runs the tests, and everything fails with module-not-found.
• Untracked files do not come along. A fresh worktree contains only tracked files. Your .env files, local databases, and seed data must be copied or regenerated per worktree.
• Cleanup is on you. Deleting the directory with rm leaves a stale worktree record (fix with git worktree prune), and git worktree remove does not kill processes still running inside the directory. Orphaned dev servers and test watchers from removed worktrees are a real source of mystery CPU load.
• Disk adds up. Git objects are shared, but working files and dependencies are not. Ten worktrees of a large monorepo with node_modules each is tens of gigabytes.

How AQ automates the worktree lifecycle

AQ is the multiplayer workspace where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. Under the hood, an AQ workspace is exactly the setup described above, automated end to end:

• Workspace = worktree. Creating a workspace creates a git worktree in the repo's .worktrees/ directory, based on the latest fetch of the default branch.
• Deterministic branch naming. Each workspace gets a branch named ai/{id}-{slug}, derived from the task. Every branch on the remote traces back to exactly one workspace, which is also how AQ later matches agent-opened PRs to their workspace.
• Dependencies installed for you. AQ installs dependencies when the worktree is prepared, restoring node_modules from a content-addressed cache when the lockfile matches, so a fresh workspace is ready in seconds instead of sitting through a full install.
• Rebase onto main as an action. When main moves ahead, AQ rebases the workspace branch onto the latest default branch, and backs off cleanly (aborting the rebase) if there are conflicts for a human to resolve.
• Real teardown. When a workspace is closed, AQ kills any processes still running inside the worktree before removing it, then prunes stale worktree records on a schedule. The orphaned-dev-server problem is handled by the platform, not by whoever remembers.

Agents run as real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or a plain shell) inside tmux in that worktree, on your own VM or an AQ-managed one, streamed to the browser. The agent commits, pushes, and opens PRs on the workspace branch with the user's own GitHub credentials; the worktree mechanics are invisible.

When should you manage worktrees by hand?

If you are one engineer running one or two agents, manual worktrees are genuinely fine: learn add, remove, and prune, script your dependency install, and you have a solid setup. Automation earns its keep when the numbers grow: many tasks per day, several agents in flight, or a team that needs to see and share each other's agent sessions. At that point the worktree ceremony (create, install, copy env, assign ports, tear down, prune) is a measurable tax, and a platform that treats worktree-per-task as a first-class primitive pays for itself in the setup time alone.