Git Worktrees for Parallel Coding Agents

Running two agents in different panes gives you two visible sessions. It does not automatically give them separate files. If both terminals point to the same repository directory, their edits affect the same working tree.

Herdr GPUI overview and setup builder

Decide whether the tasks can run independently

Start with a task split you can describe precisely. For example, one agent can investigate a failing test while another explains the affected code. These read-only investigations can proceed separately and produce findings you compare before allowing edits.

Two editing tasks need more planning. A documentation update and a targeted test addition may be independent. Two agents rewriting the same function are likely to overlap, even if you give them different branch names.

For each task, record the files or area it owns, the expected output, and the verification step. Explain which changes require returning for review. This is a suggested workflow, not a claim that parallel sessions inherently improve speed or correctness.

Prepare separate checkouts

Git worktrees allow multiple working trees connected to one repository. See the Git worktree documentation for the command's behavior.

First inspect the current repository:

git status --short
git worktree list

Keep existing uncommitted work intact. New worktrees created from the current commit do not automatically include the main checkout's uncommitted edits.

For example, create two new task branches and adjacent directories:

git worktree add -b agent/docs ../project-docs
git worktree add -b agent/tests ../project-tests

These names are examples: use available branch and directory names appropriate to your project. If a name already exists, choose another or intentionally attach the existing branch; do not force-reset it to make the command succeed.

Attach each task to the right directory

Open one workspace or pane for each checkout and verify its current directory before starting an agent. Put the task name and branch in a visible note or workspace name.

An agent that starts in the main checkout can still modify the wrong files even when its prompt mentions a worktree. Verify the actual working directory, not just the intended branch name.

Install or prepare dependencies according to your project's normal instructions. Worktrees separate files and Git state; they do not automatically isolate databases, external accounts, development-server ports, or other services. Resolve only the shared resources involved in your tasks.

Give each agent a concrete assignment

For the documentation task, ask it to explain a specific feature using verified behavior, change only the relevant documentation, and list any facts it could not confirm.

For the test task, identify the behavior to protect, request a focused regression case, and specify the project's relevant checks. Avoid asking it to redesign unrelated areas merely because they are nearby.

If an agent discovers overlapping work, stop and revise the split before merging. Keep findings and implementation decisions visible so the reviewer can understand why each change exists.

Review results before combining them

Inspect each checkout's diff and the checks the agent actually ran. A done indicator tells you to review a task; it does not certify the implementation.

Combine changes through your normal branch-review workflow. Re-run the affected checks after integration when the combination changes behavior. Keep the task checkout until its work has been preserved and verified; removing a worktree should be an intentional cleanup step.

Use the macOS setup guide if you still need a first local session. For missing sessions or connection errors, follow the connection checklist.