Git worktrees for parallel AI coding agents: a safe workflow

Know what a linked worktree separates

A linked worktree creates another checkout attached to the same repository; it is a separate task workspace, not a separate repository or runtime environment.

Git defines one main worktree and zero or more linked worktrees. Each linked worktree has its own checked-out files and private administrative state for items such as HEAD and the index. This is what allows two branches to be checked out at once without repeatedly stashing and switching the main directory.

The repository remains shared. Git documents that refs are generally resolved through the common directory, with limited per-worktree exceptions. Objects, configuration, and repository-level operations can therefore affect more than one workspace. Outside Git, a worktree does not automatically provide separate dependency caches, environment variables, credentials, databases, servers, or ports.

Parallelize tasks, not dependencies

Use concurrent worktrees when the tasks have distinct outputs and can be reviewed independently; keep dependent or heavily overlapping changes sequential.

Good candidates include a read-only investigation beside an implementation, tests for an already agreed contract, or changes in separate packages with a stable interface between them. Poor candidates include two agents editing the same component, migrations that depend on a still-changing schema decision, or a refactor and feature whose target API has not been settled.

Before creating another workspace, name the reason parallel execution helps. If the workstreams need constant synchronization, the coordination cost is evidence that one bounded sequence may be clearer. Parallel agents should reduce waiting, not create competing versions of the same decision.

• The tasks can be described without referring to unfinished output from each other.
• File or symbol ownership is distinct enough to make conflicts exceptional.
• Each branch has a focused check that can run before integration.
• One person or primary agent owns shared product and architecture decisions.

Create one named branch and path per task

Start from a known commit, choose an explicit branch name and sibling path, then confirm the resulting worktree list before assigning an agent.

First inspect the main worktree and decide which commit the task should start from. Then create a linked worktree with a new task branch, for example `git worktree add ../brief-auth -b agent/auth-refresh`. Git also supports attaching an existing branch or creating a detached worktree for experiments, but a named task branch is easier to review and retain for normal implementation work.

Run `git worktree list` and enter the new path before starting the agent. Record the absolute workspace path and branch in the task. Git normally prevents the same branch from being checked out in multiple worktrees; do not work around that safety check for routine parallel development.

1. Inspect the source branch and confirm the intended starting commit.
2. Choose a short task branch and a specific sibling-directory path.
3. Create the linked worktree with `git worktree add <path> -b <branch>`.
4. Run `git worktree list` and confirm the branch-to-path mapping.
5. Start the agent from that worktree, not from the main checkout.

Give each worktree one bounded mission

Workspace separation helps only when each agent also has a distinct outcome, scope, validation plan, and stop condition.

For every worktree, name the observable result, files or package likely in scope, non-goals, reusable patterns, and the checks expected before handoff. State which shared interfaces are fixed and which decisions belong to the integrator. If an agent discovers that it must edit another workstream's owned surface, it should stop or renegotiate scope rather than quietly crossing over.

Brief can route repository and path-specific evidence inside each workspace. The mission receipt belongs to that branch and task state; it does not prove the other agents saw the same sources. Keep one primary owner responsible for comparing outputs and updating the shared plan when a dependency changes.

Coordinate the state Git does not isolate

Treat servers, ports, databases, caches, generated artifacts, credentials, and external writes as a separate concurrency problem.

Two worktrees can still start the same development server port, run migrations against the same local database, overwrite a shared generated cache, or use credentials with production reach. Give each task an explicit runtime plan: unique ports or databases where needed, safe test accounts, and clear ownership for external mutations.

Repository-level commands also deserve care because the worktrees share common Git data. Coordinate rebases, branch deletion, aggressive cleanup, and hooks. Agents may read shared refs, but only the integrator should rewrite or remove branches that another worktree may still use.

Verify branches separately, then verify the combined change

A passing check in each worktree is necessary evidence, but only integration can expose conflicts between the branches' assumptions.

Before integration, each agent should inspect its branch diff, run the focused checks from that worktree, and hand off changed files, exact results, skips, and remaining risk. The integrator should review each diff against its mission before choosing an order for merge, rebase, or cherry-pick. The right operation depends on the team's Git policy; worktrees do not require one integration strategy.

After combining the branches, rerun checks at the boundary the tasks now share. This may be a package test, a contract suite, a build, or a user flow. A branch can be internally correct and still rely on an interface another branch changed. Do not mark the parent task complete merely because every worker reported completion.

Remove a worktree only after the branch is retained

Confirm the useful changes are committed or otherwise preserved, then use Git's worktree commands to remove the linked workspace and inspect what remains.

Run `git status` inside the linked worktree and confirm the branch or commits are available from the integration path. Use `git worktree remove <path>` for normal cleanup. Git can refuse removal when a worktree contains modifications; treat that refusal as a prompt to inspect the state, not as a reason to force deletion.

If a directory disappeared without a proper removal, `git worktree prune` can clean stale administrative records. Prune is not a substitute for reviewing uncommitted work. Finish by running `git worktree list` so the surviving branch-to-path map is explicit.