ClaudeZero

ClaudeZero is an open-source, MIT-licensed shell script built and maintained by Ivan Rublev that acts as a supervisor for Claude Code, Anthropic's coding agent. It runs claude in a loop over a Markdown todo list, guiding it to implement, commit, and check off each task one at a time — unattended. The project is self-hosted, free to use, and available on GitHub.

What It Is

ClaudeZero sits at the "loop engineering" layer of AI-assisted software delivery. Rather than prompting Claude Code manually turn by turn, ClaudeZero automates the outer loop: it claims a task, forks a git worktree, lets Claude implement and commit, merges back to the base branch, ticks the checkbox, and restarts for the next task. Multiple instances can run in parallel, coordinating through git worktrees and flock-serialized merges so no two instances race on the same task.

How the Loop Works

The kata every instance follows is strict and deterministic:

• Find & validate — reads the todo file; a missing or duplicate task ID stops the loop with a report.
• Judge independence — a task is only blocked if its body explicitly consumes an unchecked task's output; adjacency alone is not a dependency.
• Claim & re-check — one task per git worktree (branch name = claim), then guards against a peer who already landed it.
• Implement & check off — scoped to that task, ticks only its box, commits.
• Merge serially — on conflict or over-check, self-heals once; otherwise stops and hands off to the user.
• End the session — the shell starts a fresh one for the next task, or waits without spending a token while peers hold the rest.

Context Rot Prevention

A core design concern is "context rot" — the quality decay that happens as a long Claude session accumulates tool output, dead ends, and superseded reasoning. ClaudeZero's Stop hook monitors cumulative token usage and SIGTERMs the session before rot sets in, then restarts on a fresh context. The thresholds are model-aware: models with a 1M context window restart at 200,000 tokens; all others restart at 160,000 (80% of an assumed 200k window). Because all durable state lives in git and the todo file, the restart is amnesiac by design — only what was committed survives, which is exactly what should survive.

Parallel Execution and Crash Resilience

Running claudezero todo.md in multiple terminal windows spawns parallel instances. Each instance gets a short human-readable nickname (e.g., "moss") so operators can identify and kill specific sessions without reading hex IDs. Crash resilience is built in: if a claude process dies mid-task, its worktree and claim branch remain; the next instance to come by reclaims the branch, finishes the work, and merges it back. A task only counts as done once its checkbox is ticked on the base branch.

Loop Engineering Philosophy

ClaudeZero is the mechanical layer of a three-level framework the author calls "loop engineering":

1. Spec — the todo file plus per-task issue files with acceptance criteria.
2. Harness — CLAUDE.md conventions, tests, linters, and review checks.
3. Loop — ClaudeZero, which owns the prompting cycle so the developer designs the system rather than driving it turn by turn.

ClaudeZero never writes CLAUDE.md itself, keeping the harness learning-agnostic. A --taskprompt flag lets operators inject a reflection step — for example, instructing Claude to append a lesson to CLAUDE.md after each task so future sessions and parallel peers inherit what was learned.

Setup Path

ClaudeZero supports macOS and Linux (bash 3.2-safe). Installation is via Homebrew on macOS (brew install IvanRublev/tap/claudezero) or a single curl command on Linux. Prerequisites are bash, git, the claude CLI, and flock. The script guard-checks prerequisites at startup and exits with a clear message if anything is missing. End-to-end tests live in TEST.md and are designed to be executed autonomously by an LLM agent.