Planned tasks, run in parallel: waves of agent sessions in git worktrees

A backlog of tasks with dependency arrows; the tasks that touch different files form a wave, each runs in its own worktree through build, review and docs, and they merge into dev in a planned order.

CRUX team · · Updated · 11 min read

To run several Claude Code sessions in parallel, give each task its own git worktree and pick only tasks that touch different files. The worktree keeps one agent's edits out of another's checkout, and the plan keeps the tasks from colliding at merge. We let an agent read the backlog and propose such a batch, a wave, and a person approves it before anything starts.

One agent at a time is the slow part

A coding agent finishes a task in an hour or two. Most of that time you are not needed: the agent reads code, writes it, runs tests. If you run one task at a time, you spend the day waiting for the next approval checkpoint.

The obvious fix is to run several tasks at once. It looks like ten sessions should finish ten tasks in the time of one. In practice two things go wrong:

  • The sessions step on each other. Two agents in the same checkout edit the same files, one agent's half-done change breaks the other's tests, and nobody can tell whose change is whose.
  • The tasks collide at merge. Even in separate checkouts, two tasks that change the same file, the same database table or the same generated code give you a merge conflict at the end, or a broken build after both merge.

Git worktrees fix the first problem. Planning fixes the second. This article is about using both, with an agent doing most of the planning work.

New to CRUX? Start with How CRUX works. The workflow side of parallel sessions is in Stop writing prompts: why AI coding agents need a workflow.

A worktree per task

A git worktree is a second working directory for the same repository, on its own branch. It shares the history with your main checkout, but its files are separate: what one agent edits there, no other agent sees until it is merged.

In CRUX every task gets its own worktree, named after the task: .claude/worktrees/CR-1729 on branch CR-1729. The crux-worktree skill creates it, or reuses it if it already exists, and moves the session into it. A project can plug in its own setup command. Ours links the local .env, installs dependencies and gives the branch its own test database, so tests in one worktree never write into another's.

Every agent of a task works in the same worktree. The developer writes the code there, the reviewer reads the same branch and commits its fixes there, and the docs step reads the final diff from it. Nobody has to look a branch up.

A worktree keeps the files apart. It does not tell you which tasks can run side by side. That is a planning question.

Plan first, so the parallelism is visible

Parallel work is only safe when you know, before you start, what each task will touch and what it waits for. You get that from planning ahead, not from the agents in the middle of the work.

On CRUX itself a feature usually starts as a short design spec. The spec is broken into tasks, and each task says three things:

  • What it changes, in a few lines, with the area of the code: "the Jira adapter", "the shared UI filter bar", "the token_usage table".
  • What it waits for: a "blocked by" relation in the tracker, such as "the API contract task merges first".
  • Merge notes when it shares a file with a sibling: "merge after the schema task", "rerun the code generator on rebase".

This costs a little time up front, and it pays back every time you plan a wave. Tasks written this way can be compared side by side.

Ask an agent which tasks can run together

Picking a wave by hand means reading every ready task, checking each blocker, remembering which files each one touches and which of them overlap. With forty tasks in the backlog, that is an afternoon. An agent does it in minutes.

We open a chat session and ask, roughly: "Look at the backlog and find the tasks we can start now as one parallel wave." The agent follows a skill, queue-advice, and works through the board:

  1. It reads the queue. Every task that is ready for implementation, with its level, priority, estimate and relations.
  2. It checks every blocker. A task blocked by something still in progress is not pickable, even if it sits in the ready column. A blocker in the "done" group is not a blocker any more.
  3. It checks what is already done. Boards lag behind the code. Our commits are titled CR-N: …, so the agent searches the history and finds tasks that were merged but never moved. In one pass it found 36 of them.
  4. It sends sub-agents to read the tasks. For a large backlog, the main session hands groups of tasks to read-only sub-agents. Each reports, per task: is the description ready to build, which files and areas it will touch, does it need live accounts or a decision, and which pairs of tasks overlap.
  5. It builds the wave. Tasks with no open blockers and no dangerous overlap go in. The rest are sorted into "next wave" and "outside the wave", each with a reason.

queue-advice is our own project skill and is not in the public plugin yet. The prompt above is enough to try the idea.

The answer is a plan in chat. A shortened example:

WAVE: can start now (8 tasks)
- WA-01  shared UI: help hint, section rail. Unblocks WA-07 and the rest of the epic.
- WA-03  API: bindings list
- WA-05  Jira board columns
- TL-01  database schema. The only migration in this wave.
- TL-03  task summaries in all 4 tracker adapters
- TL-06  shared UI: filter bar
- PS-01  public status DTO. Unblocks PS-02 and PS-04.
- MT-01  remove the stdio transport. Unblocks MT-02.

MERGE ORDER where tasks share files
- shared UI index: WA-01, TL-06. Small text conflicts, merge one at a time.
- Jira adapter: TL-03 and WA-05, one after the other.

HELD FOR WAVE 2
- SP-01 changes the same table as TL-01. Two migrations on one table
  conflict in the schema file. No delay: SP-05 waits for TL-07 anyway.

OUTSIDE THE WAVE
- CL-10 load benchmark: needs an idle machine, run it alone.
- SG-08 widens CI: needs your decision.

The agent advises; it does not decide. You read the plan, move a task in or out, answer the open questions, and say "start".

Rules that keep a wave from colliding

Over two dozen waves we collected a short list of rules. The agent applies them when it builds the wave, and the tasks name them in their merge notes.

  • One migration per wave, or one at a time. Two tasks that change the database schema conflict in the schema file and in the migration order. Either keep one per wave, or merge them one by one and regenerate after each rebase.
  • One repository-wide task per wave, merged last. A rename, a codemod or a package move touches nearly every file. Run it beside tasks in other areas, merge everything else first, then rebase it and rerun the codemod on the final tree.
  • Shared files get a merge order. Index files, generated code, a shared API contract: tasks that touch them are fine in parallel, but the plan says who merges first and who regenerates after.
  • Name the shared helper up front. When four sibling tasks build parts of one page, each will happily write its own copy of the same helper. Say in the tasks which one owns the shared module and which ones reuse it.
  • Mind the machine. Every session runs its own tests, type checks and pre-push gate. Once we ran a wave of 30 tasks. The laptop's load went past 100, the gates queued for twenty minutes and tests timed out in files nobody had touched. We now keep a wave to about ten tasks.

Start the wave

Once the plan is agreed, the coordinating session starts it with crux-dispatch developer from our Claude Code plugin. For each task it does two things:

  1. Claims the step for you, so no one else on the team is offered the same task.
  2. Prepares a session card in Claude Code desktop. In a terminal runner, it prints one command per task instead.

Nothing starts by itself: each session begins when you click its card. The new session fetches the developer agent's instructions from CRUX, moves into the task's worktree and starts with the checkpoints from your workflow: it agrees the approach with you, writes the code, opens a pull request. When it is done it prepares the next step for the same task, the reviewer, and after that the docs update.

You now have eight or ten tasks moving through the same pipeline side by side. Your job is to answer the checkpoints as they come in: a plan to approve here, a review finding to confirm there.

Know which session is doing what

Ten sessions at once are easy to lose track of. Two things keep them apart.

Everything is named after the task. A session is titled CR-1729 · developer, its worktree is .claude/worktrees/CR-1729, its branch is CR-1729, our commit messages start with CR-1729, and its pull request is linked on the task. The reviewer for the same task is CR-1729 · reviewer. When a question comes in, the title tells you which task and which step it is about.

CRUX shows the state of every step. The Workspace page in the CRUX dashboard lists the tasks by status. Each task card shows its numbered pipeline, for example 1 Developer, 2 Reviewer, 3 Wiki curator, with each step's state and how long it took, and how many steps are done (3/3). Open a step and the side panel shows its session: which agent, where it ran (a session in your own Claude Code is marked External), when it started and ended, and what it produced, such as the pull request and the review report. The Needs you and Running filters narrow the list to the sessions that wait for you or are still at work, and the bell in the header counts the ones waiting for you in every project. You don't have to open ten sessions to find the one that is stuck.

The CRUX Workspace page: two tasks in Implementation, each with a three-step pipeline (Developer, Reviewer, Wiki curator), every step done with its duration; the side panel shows a reviewer session that ran in Claude Code, marked External, with its start and end time, its task and its outputs, a pull request and a review report.
The Workspace pageEach task's numbered pipeline with every step's state and duration; the side panel shows the open step's session, its task and what it produced.

While the wave runs

The coordinating session stays open and keeps the wave in order:

  • It merges in the planned order. When the first task on a shared file merges, it tells the sessions that come after it to pull the latest dev and rebase.
  • It relays decisions. A question that affects several tasks gets one answer from you, and the coordinator sends it to every session that needs it.
  • It can pause the wave. If the machine runs out of CPU, it stops the running sessions, tells each one not to rerun its tests, and resumes them a few at a time.

After the wave

When every pull request of the wave has merged, the coordinator cleans up before it plans the next one:

  • checks that every pull request, code and docs, really merged;
  • moves the merged tasks to the right status on the board;
  • archives the wave's sessions;
  • removes the worktrees that are clean, and reports the ones with uncommitted work instead of deleting them.

Then it reads the backlog again. Tasks that were blocked an hour ago are now free, and the next wave is often already there.

What two weeks of it looked like

We build CRUX with CRUX. From October 22 to November 5, more than 300 pull requests merged into dev, covering more than 250 tasks, every wave planned and started from one coordinating session. Counted from merged pull requests and task keys in our git history.

The plan is what kept it manageable. Each wave had been checked for overlaps before it started, so a conflict was something the plan expected, with a merge order and a rebase step ready, not a surprise at the end.

Where people stay in the loop

Running ten agents at once does not mean letting them run on their own. A person is in charge at each point where a wrong turn would be expensive:

  • the spec and the task breakdown;
  • the wave: which tasks, in what order, and what waits;
  • each task's checkpoints: the approach, the review, the docs;
  • the merge.

The agent does the reading and the bookkeeping in between.

Try it

The CRUX plugin for Claude Code is public: github.com/cruxteam/skills. crux-dispatch starts a wave, crux-run starts one step on one task, and crux-worktree moves a session into its task's worktree. Install it with:

claude plugin marketplace add cruxteam/skills
claude plugin install crux@cruxteam

Even without CRUX, try the idea on your next batch of work: write each task down with the files it will touch and what it waits for, then ask your agent which of them can run side by side.

Frequently asked questions

What is the difference between a git worktree and a branch?

A branch is a line of commits; a worktree is a folder where one branch is checked out. Two sessions on two branches in one folder keep switching each other's files. Two worktrees give each session its own folder and its own branch over one shared history.

How many Claude Code sessions can run in parallel?

As many as your machine can test at once. Every session runs its own tests and type checks. Past about ten on one laptop, ours started queueing and timing out, so we keep a wave to about ten tasks.

How do you choose tasks that will not collide?

Pick tasks with no open blockers that change different files. Where two tasks have to share a file, give them a merge order, and keep database migrations and repository-wide changes to one per wave.

How do I see which session is waiting for me?

Claude Code's own Agent View (claude agents) lists the sessions that wait for input. Name everything after the task, so a session's title tells you the task and the step. In CRUX the Workspace page shows each step's state, and Needs you lists the sessions that wait for your answer.

Try this on your own project. CRUX is free for one person, no card.

Start free

Next: Our project wiki: memory that AI agents can read and write

All articles