Orbit

Git worktrees for AI coding agents: a practical guide

Chris Rupp

Give each independent implementation a checkout, an owner and a review plan. You can do this with native tools before adopting a queue or desktop manager.

Official documentation checked October 23, 2026.

Start with Git or the agent’s native workflow

A linked worktree provides another working directory for the same repository. Git shares repository data while keeping per-worktree state such as HEAD and the index separate. By default, Git refuses to check out a branch already used by another worktree. See the official worktree manual.

For managed alternatives, Claude Code documents claude --worktree <name>, while OpenAI documents a Worktree option for Codex tasks. Choose these if their setup and review flow already fit your work.

Create two explicit checkouts

From an existing repository, replace main with your base branch. These commands follow Git’s add -b and list syntax:

git worktree add -b agent/api ../repo-api main
git worktree add -b agent/tests ../repo-tests main
git worktree list

Start each agent in its assigned directory. For a complete terminal example, see running multiple Claude Code agents.

Before launching, write a task boundary: who owns the API, who owns tests, what interface they share, and which check proves the combined result. If the tests depend on an interface still being designed, agree that interface first or run the tasks sequentially.

Plan dependencies and shared services

A checkout is only part of an execution environment. Treat the following as setup decisions for your project:

Git’s worktree documentation describes filesystem and repository separation. Process, dependency and service isolation require your own environment design.

Review and integrate one branch at a time

First review each task against its acceptance criteria. Require a committed result and check evidence. Use the Branch → Review learning path if this workflow is new; the glossary explains branches and conflicts.

In a dedicated integration checkout on your target branch, start clean. The following uses the official merge workflow:

git merge agent/api
# Run the project's checks and inspect the result.
git merge agent/tests
# Repeat the checks on the combined result.

Git can stop on conflicting changes. Resolve the affected files, stage the resolution and finish the merge, or use git merge --abort to abandon it. The merge manual explains these paths and warns against starting with uncommitted changes.

Assign one reviewer to reconcile intent. A clean textual merge can still combine incompatible assumptions: a renamed response field and an old consumer may live in different files. Run an acceptance example through the complete behavior after integration.

Clean up after acceptance

Stop the worker and preserve anything needed for review first. From another checkout, use Git’s worktree cleanup commands:

git worktree remove ../repo-api
git worktree remove ../repo-tests
git worktree prune --dry-run

Removal normally requires a clean worktree. Do not force removal to silence unexpected changes. prune cleans stale administrative records after a directory has disappeared; it does not integrate work.

Orbit’s isolated-run path

Orbit’s Sandbox documentation describes a worktree per sandboxed prompt and a choice to Promote, Discard or View Cumulative Diff afterward. Use that path for one isolated worktree per run, with the result kept available for a review decision.

Apply the same dependency, service and acceptance checklist to managed runs. A separate checkout makes concurrent work easier to inspect; it does not choose the correct combined behavior for you.