How to run a wave of GitHub issues in parallel with Claude Code

FlowConversational

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Intermediate7 min readNeedscckit installed & initializedseveral unblocked issues

What you’ll do: clear a whole wave of ready work at once. cckit wave writes the fan-out brief and the agent spawns one subagent per unblocked issue, each opening its own PR. The captain (cckit watch) then gates the resulting PRs and merges the ones that pass — so the board advances wave by wave until it’s drained.

Steps

1. Ask Claude to clear the next wave.

   Prompt to paste

   Clear the next wave of ready work. Fan the unblocked issues out so they're worked in parallel,
   then gate the resulting PRs and merge the ones that pass. Advance to the next wave and keep going
   until the board is drained.

2. cckit fans out the wave and gates the PRs.

   cckit wave             # emit the wave-0 subagent fan-out brief
   # …the agent spawns one subagent per issue, each opens a PR…
   cckit watch --merge    # gate open PRs, squash-merge the clean ones, advance the wave

3. Let it advance. watch --merge merges every PR that passes its gate and moves on to the next wave. It stops when there’s nothing left unblocked.

How it works

A wave is exactly “what can run in parallel right now” — every issue that nothing is blocking. Because the issues in a wave touch different files and each runs in its own worktree, their PRs merge cleanly. cckit watch is the captain: it doesn’t write code, it reviews the fan-out’s PRs against the gate and merges only the clean ones, then advances to the wave those merges just unblocked.

Waves come from the dependency graph

You don’t assign waves by hand. cckit reads the blocked-by links and computes them — see Efforts, waves & worktrees.

Troubleshooting

A PR didn’t merge. The captain merges only PRs that pass the gate. Read the gate output on that PR, fix the finding, and re-run cckit watch --merge — the rest of the wave isn’t held up.

Two subagents edited the same file. Those issues shouldn’t be in the same wave. Add a blocked-by link so the dependent one lands in a later wave, then re-run.

The wave brief is empty. Nothing is unblocked. Run cckit sync to see what’s blocking the remaining issues, or start an effort to create some.

Related tutorials

Break a big feature into an effort Where the waves of sub-issues come from.

Run Claude Code unattended Drive waves with no one watching.

Take a GitHub issue to a merged PR The single-issue lifecycle each subagent runs.