Claudopilot
Autonomous execution loop for Claude Code.
Feed it a roadmap of phases. The driver runs every currently-eligible phase
concurrently — bounded by MAX_PARALLEL — each in its own git worktree on
its own auto/<phase-id> branch. A phase is eligible when its state is
[pending] and every phase in its (deps: …) annotation is [merged]. Each
worker (bypassPermissions) implements its phase end-to-end and renames its
phase doc to DONE_; the driver owns the merge and the manifest (it merges
serially into the base branch and is the sole writer of the manifest), which is
what makes concurrent phases safe. See Parallel execution.
If a phase's tests refuse to go green, a supervisor agent is invoked
with a narrow mandate (read the log, apply the smallest possible fix,
exit) before the worker re-attempts. If the supervisor also fails, the
loop halts with a non-zero exit so a human can step in.
The contract is project-agnostic. The prompts assume a pnpm /
Turborepo monorepo by default but are designed to be retargeted — the
gate command, commit-message vocabulary, and project rules all live in
prompts/worker.md as text you edit, not in the
loop driver.
Parallel execution
The driver schedules by dependency graph, not by queue position. Each pass it:
- reaps finished workers; for each exit-0 worker it merges
auto/<phase-id>
into the base branch (serially — the driver is single-threaded for merges, so
package-disjoint phases never race) and flips that manifest entry to [merged];
- launches every
[pending] phase whose (deps: …) are all [merged], up to
MAX_PARALLEL, each in a fresh git worktree under .claudopilot/worktrees/
(prepared with pnpm install so the isolated checkout can build);
- exits 0 when all phases are
[merged].
This gives the /plan-build shape for free: the contracts phase has no deps so
it runs first; the fan-out streams all depend only on contracts so they run
concurrently; assembly depends on the streams; verify depends on assembly.
The contract that keeps it safe: concurrent phases must own disjoint
package sets (the worker refuses to edit outside its declared packages), and
workers never merge or touch the manifest — both are driver-owned. Manifest
states are [pending] | [running] | [merged] | [failed] | [blocked], all written by the driver.
On a phase failure: the supervisor gets up to MAX_SUPERVISOR_ATTEMPTS_PER_PHASE
tries in that worktree. By default, if it still can't recover, the phase is marked
[failed], no new phases launch, in-flight workers drain, and the loop exits
non-zero. A rate-limit-shaped exit triggers a cooldown and a relaunch.
Keep-going mode (KEEP_GOING=1) turns this into a fully-autonomous run: the
final supervisor attempt runs in best-effort mode (wider edit mandate), and a
phase that still can't go green is parked — its auto/<id> branch is committed
but not merged, marked [blocked] — while the run continues with every
other independent phase. Red work is never merged (that would break the shared
gate for all phases); parked branches stay in git for review/rollback. Dependents
of a blocked phase are skipped. The run ends with a summary (N merged, M blocked)
and exit code 8 if anything was parked. It's all in git — flip a [blocked]
entry back to [pending] and re-run to retry.
Key knobs (full list under Configuration):
MAX_PARALLEL (default 3), GATE_CMD (the per-phase quality gate; must match
worker.md and the pre-commit hook), WORKTREE_PREPARE_CMD, POLL_SECONDS.
Generate a compatible roadmap with the repo's /plan-build skill — it emits
roadmap/EXECUTION-MANIFEST.md (with (deps: …)) + per-phase docs whose
package-disjoint streams map straight onto this scheduler.
Contents
