Parallel Sessions and Git Worktrees¶

Some tasks take a while. When you ask an AI coding agent to refactor a module, write a test suite, or trace a bug through a large codebase, it can churn for 30 minutes or more. Sitting and watching it is a waste of your time. The natural move is to start a second piece of work in parallel.

This page is about doing that with structure — so that running two, three, or four agents at once makes you faster instead of creating a mess you have to clean up later.

Why this matters for AI's limits. Each agent session has its own context window, and that window degrades as it fills up (limitation #1). Parallel sessions let you give each task a clean, focused context instead of cramming everything into one over-stuffed conversation. The cost is on the human side, and this page is honest about that at the end.

Worktrees, parallel agents, and where the human becomes the bottleneck — 1 min 58 s.

When parallel work pays off¶

Not every task should be split. Parallelism helps most when the streams are independent — they do not depend on each other's output and do not fight over the same files.

Good candidates:

Compare N approaches. Spin up one agent per implementation strategy (e.g. "do this with a queue," "do this with a cron job," "do this with a webhook") and read the results side by side before committing to one.
Code + review. One agent writes a feature while a second agent reviews the diff with fresh eyes and no stake in the code it is critiquing.
Investigate while building. One agent digs through production logs to characterize a bug while another writes the failing test that reproduces it.
Explore risky ideas safely. Try a speculative rewrite in a throwaway workspace without polluting the context (or the working tree) of your main task.

Rule of thumb: if you would be comfortable handing the two tasks to two different people who never talk to each other, they parallelize well. If they would constantly need to sync, keep them in one session.

The collision problem¶

Here is the catch. A normal git checkout gives you one working directory per repository. If two agents edit files in that one directory at the same time, they overwrite each other, trip over half-finished changes, and produce diffs that are impossible to untangle.

Switching branches does not solve it either: git checkout other-branch changes the files in place, so the agent that was mid-task suddenly sees a different codebase under its feet.

You need each parallel stream to have its own set of files. That is what worktrees are for.

Git worktrees, explained¶

For everyone: a worktree is a second (or third, or fourth) working folder backed by the same repository. Each folder can have a different branch checked out at the same time, and they all share the same history and commits underneath. Think of one library (the repo) with several reading desks (the worktrees) — everyone reads from the same collection, but each person has their own desk with their own open books.

A single git clone normally gives you one folder. With git worktree add, the same repo projects multiple independent folders, each on its own branch:

# From inside your main repo
git worktree add ../myproject-feature-a feature-a
git worktree add ../myproject-experiment-b -b experiment-b

git worktree list      # see all active worktrees
git worktree remove ../myproject-experiment-b   # clean up when done

Now you can open one agent session in ../myproject-feature-a and another in ../myproject-experiment-b. They edit, build, and run tests completely independently. Neither can clobber the other.

Claude Code has native worktree support, so in practice you may never touch the raw git worktree commands above — it can create and manage the isolated workspace for you. See Getting started.

Why this beats juggling one checkout¶

Single checkout, switching branches	One worktree per task
`git stash` / `git checkout` dance between tasks	Each task just stays put in its own folder
Agents overwrite each other's uncommitted work	Physically separate files; no collisions
Build artifacts and caches thrash on every switch	Each worktree keeps its own build state
One polluted context affects everything	Each session stays focused on one workspace

For engineers: worktrees share the object database and refs, so they are far cheaper than full clones — no re-downloading, no duplicated history. Each linked worktree gets a private entry under the repo's worktrees/ metadata directory. Note the shared-state caveats: you cannot check out the same branch in two worktrees at once, and refs/bisect and a few others are per-worktree. See the official git worktree docs for the full model.

Merge only the useful parts back¶

Because each worktree is on its own branch, finishing a parallel stream is just a normal merge or pull request. This is the real payoff of the "compare N approaches" pattern: you keep the one approach that worked, merge that branch, and throw the others away by removing their worktrees. The dead ends never touched your main line of work.

Keep findings out of the context window¶

A parallel agent's conclusions are useless if they evaporate when its session ends. Two habits prevent that:

Have sub-agents write results to files. Instead of returning a wall of text into a parent conversation, tell an investigating agent to save its findings to a markdown file (e.g. notes/log-analysis.md). The file is durable external memory; it survives the session and any other agent or human can read it. This directly counters limitation #1 — the agent's working memory is fragile, but a file on disk is not.
Summaries, not transcripts. When a sub-agent reports back, ask for the conclusion and the key evidence, not the entire log it waded through. Verbose output belongs in the sub-agent's own context, not yours.

Constrain scope and tokens¶

Parallel agents can each individually balloon — reading the whole repo, running every test, fetching huge files — until they are slow, expensive, and confused. Rein them in:

Give each agent a narrow, explicit task and the specific files or directories it should touch.
Restrict tools where you can, so an agent doing read-only investigation cannot start editing.
Prefer delegating big reads to a sub-agent so the bulky output stays in its window, not the one you are supervising.

Claude Code's sub-agents are built for exactly this: each runs in its own isolated context with its own tool permissions and can even use a cheaper, faster model. See the Claude Code sub-agents documentation.

The honest part: the human bottleneck¶

Worktrees solve the machine collision problem. They do nothing for the human one, and the human is usually the real limit.

Context-switching is expensive for you, not just the model. Bouncing between two very different tasks — a database migration and a CSS refactor — forces your brain to reload the entire mental model each time. Two similar tasks switch cheaply; two unrelated ones can leave you slower than if you had done them one after another.
You can only supervise what you can hold in your head. Reviewing an agent's work means understanding what it changed and whether it is correct. A feature spanning frontend, backend, and one database is usually within reach for one person. Work spread across many services, multiple processes, or concurrent/multi-threaded behavior is genuinely hard to hold all at once — and if you cannot hold it, you cannot meaningfully review what the agent did to it.

Practical ceiling: most people can truly supervise two, maybe three parallel streams if the streams are similar and self-contained. Beyond that you are not parallelizing — you are rubber-stamping, which is where bad code slips in. Start with two. Add a third only when the first two are running smoothly without you.

This is also a reminder of limitation #2: the agent does not "remember" or "reason about" the whole system between sessions the way a senior engineer carries it in their head. You are still the one holding the architecture together. Parallelism multiplies your output only up to the point where it overflows your own ability to keep the picture.