Wave
cckit wave reads your open efforts and proposes the incoming waves of work.
What a wave is
Section titled “What a wave is”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 waveand it proposes the next set. The board drains itself, wave by wave.
One turn of the loop
Section titled “One turn of the loop”-
Propose the wave —
cckit wavereads 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 -
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.
-
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 --mergeIf 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.
-
Advance — merging unblocks the next wave. Re-run
cckit waveand the loop repeats until there’s nothing left to propose.
One writer per branch
Section titled “One writer per branch”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 waveThe 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.
The commands
Section titled “The commands”| Do this | Command |
|---|---|
| Propose the wave (fan-out brief) | cckit wave |
| Scope to one effort | cckit wave --effort <N> |
| Gate + merge the wave | cckit watch --merge |
| Let the captain self-pace | cckit watch --loop |
| Machine-readable plan | cckit plan --llm |
| Read a recorded verdict | cckit receipt show <issue> review |
Links to learn more
Section titled “Links to learn more”- Efforts, waves & worktrees — where the waves come from.
- Driving cckit from agents — the full agent-facing surface.
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