Skip to content

Wave

cckit wave reads your open efforts and proposes the incoming waves of work.

An effort is a goal broken into many issues. Some issues block others, so they can’t all start at once. A wave is the set of issues that are unblocked right now — everything ready to be worked in parallel.

cckit wave looks at your open efforts, works out that set, and writes a brief: one task per issue, each scoped to its own isolated worktree so the parallel work can’t collide. It doesn’t run anything itself — it hands the brief to the agent, and the agent does the work.

Here’s the whole shape, then the steps below walk each part:

  • One wave → many agents. The brief lists each unblocked issue as a self-contained task. The agent (Claude Code) spawns one subagent per task. They run at the same time, in separate worktrees, each implementing its issue and opening a pull request.
  • The captain gates and merges. The captain is cckit watch — one long-running process that steers the whole wave. It checks every open pull request the subagents opened; the clean ones — tests passing, no conflicts — get merged; the rest are reported with exactly what to fix.
  • Merging unblocks the next wave. Closing this wave’s issues frees the ones that depended on them. Re-run cckit wave and it proposes the next set. The board drains itself, wave by wave.
  1. Propose the wave — cckit wave reads the board, finds the issues unblocked right now, and writes the brief: one subagent task per issue, each in its own worktree.

    Terminal window
    cckit wave
  2. Fan out — the agent spawns one subagent per issue from that brief. They run in parallel, each implementing its issue and opening a pull request.

  3. Gate + merge — the captain (cckit watch, the process that steers the wave) checks every open pull request. The clean ones are merged; the rest are reported with what to fix.

    Terminal window
    cckit watch --merge

    If you have configured a review stage, a PR the captain would merge goes to a reviewer first and waits for its verdict — one extra turn of the loop, not a separate command.

  4. Advance — merging unblocks the next wave. Re-run cckit wave and the loop repeats until there’s nothing left to propose.

Git refuses to check one branch out in two worktrees. That is a narrower guarantee than it sounds: it says nothing about two agent processes driving the branch cckit just handed them — a second wave launched onto a branch a live worker is still pushing, or a re-run of orchestrate over an issue whose pane is already open.

So orchestrate takes a lease on every branch in the wave before it starts a single pane. A branch already owned by a live writer refuses the launch, and every lease the wave took is released — a half-launched wave is worse than none.

orchestrate: #323 — another writer already owns effort/318-agents-run-by-profile-in-herdr;
not launching this wave

The ledger lives with the rest of cckit’s local state, so every worktree of the repo reads the same one. A lease is dropped only on positive evidence the holder is gone: its worktree no longer exists, or the process died on the host that recorded it. A lease written on another machine is never reclaimed on a process check — process ids are not comparable across hosts, and stealing a live remote worker’s branch is the corruption the lease exists to prevent. It expires on age instead, after BO_LEASE_TTL (default 24 hours), so a decommissioned host cannot wedge a branch permanently either.

Do thisCommand
Propose the wave (fan-out brief)cckit wave
Scope to one effortcckit wave --effort <N>
Gate + merge the wavecckit watch --merge
Let the captain self-pacecckit watch --loop
Machine-readable plancckit plan --llm
Read a recorded verdictcckit receipt show <issue> review

Independent, educational project — not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic PBC.Disclaimer & trademarks ·

From Mexico withloveby josegtz