HELP = """Run a task as headless claude cycles; a judge interrupts only when a decision is the human's. usage: loop-claude Run it anywhere inside a project checkout whose goals file has ## Goals and ## Audience, the premises. The goals file is the one the project's config, ~/.claude-projects//config.toml, sets as goals-and-audience: a file, or a Jira epic's description. `project-config goals-and-audience` prints where it is. The task runs at the checkout root. Each cycle a worker runs the task. A chunk's first worker prompt also quotes the premises. They, with code health (~/.claude/CLAUDE.md → "Shared goal") ranked first unless the goals file voids it, choose between ways to deliver the chunk's plan items, or else the task, and never widen them. A judge then reads the transcript's end, the premises, and the records: the project's AGENTS.md and docs/decisions.md, and the human's ~/.claude/CLAUDE.md and ~/.claude/rules/*.md, then the .md files in the folder of review standards the project's config sets, where they exist. It rules whether the chunk, the work of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a later chunk could need is recorded: the premises or the records hold it, or the transcript shows the worker writing it into the premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A choice the worker made that the premises or the records settle is not asked about. When the worker asks a question they answer, the judge quotes the answer, loop-claude prints it, and the worker resumes with it. A quote they do not hold word for word is dropped, and the question goes to the human. So does a question asked again after its answer. A question the human answered earlier in the chunk goes back to the worker with that answer, unless the question quotes the words of the answer that leave it open. The fourth question they answer in one cycle goes to the human too, with the quote. An unfinished chunk resumes its session next cycle, and the worker is shown the passage the judge quoted as the work remaining. The next chunk starts a fresh session. Cycles continue until an exit below or Ctrl-C, either of which stops that one chunk. Words: ~/.claude/CLAUDE.md → "Vocabulary". loop-claude needs tmux 3.2 or later, and checks it before it starts anything. Each chunk runs in its own window of one tmux session per project, named loop-, such as loop-claude-config. is the checkout's path relative to ~/code, or to / outside it, with a dash for each character other than a letter, a digit, _ or -. The tmux session's @loop-root option names its checkout, and a checkout whose key maps to a tmux session another checkout runs is refused. loop-claude starts the chunks that may start now, then attaches to the tmux session, or switches to it inside tmux; detaching leaves the chunks running. Off a terminal it prints the command that attaches. Where no chunk may start, it says so, and the task starts in no new window. At most parallel-chunks chunks run at once, a whole number the project's config sets, 1 by default. The first starts from the plan's next item, and each other from an item whose `Touches:` prediction overlaps neither one before it nor an item another chunk holds (touch-predictions --help). A window is named for the item its chunk starts from, as item-372; a chunk without a plan item, such as planning a release or its release review, runs alone in the window no-item. Each window runs a loop-claude for that one chunk, started with --chunk , which nobody types. As a chunk finishes, its loop starts each chunk that may start then, with the task it ran itself, and exits, which closes its window. A loop that stops, by Ctrl-C, an exit below or a failure, keeps its window, with its last lines, and its chunk keeps its items; the next loop-claude starts it again before any other. To stop every chunk, press Ctrl-C in each window. A chunk's claude session is named "A loop-claude ", so a rerun resumes a chunk left open, and is deleted when the chunk finishes. A fresh worker is told the items the project's other chunks hold, running or stopped: each one's own and those on its latest `Chunk items:` line, and leaves them out. A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py). loop-claude prints the question in the chunk's window and rings its bell. Until it is answered the window's name ends in " ?", as in "item-372 ?", which tmux's status bar shows. The human answers it there: - A line of text: the worker resumes headless with it. The judge reads it as the human's, so the chunk stays unfinished until the answer is recorded. - /talk: opens the worker's claude session with `claude --resume` on the terminal, to read the diff or discuss first. Once that claude exits, the judge rules on what was typed there. - Enter alone: stops the loop. A release ready to cut opens that claude session on the terminal at once, since only the human may cut it. While claude is open, Ctrl-C reaches it alone, and the loop goes on. Where the project's config sets notifier, loop-claude also sends the human each question, naming its tmux window as :, each release ready to cut and each stop as a DM, as bin/notify sends it. Four stops are left out: Ctrl-C, printing this help, the loop-claude that started the windows once it attaches or prints how to, and a loop whose chunk finished once it started the next chunks. A DM that fails is said on stderr, and the loop goes on. As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree, adding --item in a window named for an item, and quotes what it prints in the first prompt (prompts.preflight_facts in bin/loop_claude/cycle/prompts.py); chunk-preflight --help says what it finds and makes. A preflight that fails, or is still running after 600 s and is stopped, leaves the worker to find the facts itself. At every interrupt, and as every cycle ends, Ctrl-C and a failure included, the claude session's transcript is copied into a folder per chunk under $LOOP_CLAUDE_TRANSCRIPTS/ (default root ~/.claude/loop-claude-transcripts), named by its hash, with an outcomes file beside it: the task, then each verdict, quoted answer, rejected judge reply, step-up and stop, each opened by its UTC time. The layout, and when a copy is replaced, are in bin/transcript_archive/__init__.py. Before each worker starts, loop-claude waits until at least a quarter of the machine's memory is available (bin/machine_load/memory.py). Each worker's claude, the session /talk opens and the subagents either launches run with a 200k auto-compact window (CLAUDE_CODE_AUTO_COMPACT_WINDOW, bin/loop_claude/cycle/worker.py), so each compacts its context at about 170k tokens. Every claude loop-claude starts runs the project's model, saved per in ~/.claude/loop-claude-models.json and read each cycle, unless routing, below, puts the worker, the session /talk opens and the judge on another rung, a model at an effort. A project without an entry, as on its first run, is asked for one on the terminal. LOOP_CLAUDE_JUDGE_MODEL overrides the model for the judge, LOOP_CLAUDE_WORKER_MODEL for the worker and the session /talk opens; with both set, nothing is asked. The routing ladder is a list of rungs, least competent first, each a model at an effort. Where the project's model is on it, the worker and the session /talk opens run on the rung that the chunk's plan item picks, and the judge of some models on another; a chunk no item routes runs on the project's model. The worker's prompts name the rungs it launches its reviews on. The worker's rung steps up as a chunk stays unfinished, when the worker names on its `Chunk items:` line an item that picks a higher rung, or when the judge finds in the transcript an escalation trigger that fired and the worker asked for a higher rung. The rules are in bin/loop_claude/routing.py and bin/model_routing/ladder.py, the choice of each review's rung in bin/model_routing/review_choice.py, and the prompts' wording in bin/loop_claude/cycle/prompts.py. Each verdict, interrupt, quoted answer, stop and step-up in the archive ends with a Worker: line, the route as JSON (Route.worker_line in bin/model_routing/route.py); a rerun resumes an open chunk on the latest route named there. A todo.md or an archive that cannot be read or parsed is said on stderr, and the chunk is routed without it. The ladder is a JSON file, each rung a model's full name and an effort of low, medium, high, xhigh or max: [ {"model": "claude-opus-5-5", "effort": "medium"}, {"model": "claude-fable-5-2", "effort": "low"} ] It holds one model of each family, such as opus, since the Agent tool launches a subagent or a review by its family's name. This setup ships one, bin/model_routing/routing-ladder.json. A project that keeps a routing-ladder.json in its config's folder, ~/.claude-projects//, runs on that ladder instead, whole: write there every rung the project may run on. loop-claude reads the project's ladder as each cycle starts, says on stderr where the project runs on its own, and never commits the file. subagent-rung and rule-hook read the same ladder; the routing figures, judge-replay and review-replay, which span every project, read the shipped one. Once 20 cycles have closed across all projects in the archive since the last measurement, the next loop to close one measures every finished chunk there, with no model run, and writes routing-figures.md at the archive's root (bin/routing_figures/). Each call the figures make for a routing change, unless raised before, is an interrupt: claude, on the project's model, on the terminal in the setup's development clone, ~/code/claude-config, asked to put the calls to the human. Once that claude ends, the calls are listed in routing-calls-raised.md beside the figures, kept in routing-state.json, and not raised again. Off a terminal, the calls are said on stderr, the loop goes on, and they are raised again at the next measurement. A change to bin/loop-claude or any bin/**/*.py takes effect at the next cycle boundary, once loop-claude --help succeeds: the loop reloads into the edited script. Exit 1, saying why, when: - no task is given - git cannot start or finds no checkout - tmux is missing or older than 3.2 - --chunk is given outside a tmux window - a chunk's window cannot be started, as when the project's config cannot be read, or the tmux session runs another checkout's chunks - the tmux session cannot be put on the terminal - the goals file, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or the project's review standards where they exist, cannot be read or is not UTF-8 - no config names the checkout, its config cannot be read, or the goals file holds no premises - the models file cannot be read or written - the project's routing ladder cannot be read or holds a fault - claude leaves no transcript - a transcript cannot be read or archived - a finished chunk's session cannot be deleted - claude cannot start for an interrupt - python cannot start for a reload - a reload cannot read the state the running script handed it, likely because the edit changed that handover - the worker or the judge fails three times running, retried a minute apart within the cycle. A worker fails when claude cannot start, exits non-zero, is killed, or ends without a result event; a judge when claude cannot start, exits non-zero or prints no json reply, or its reply misses or mistypes a field, interrupts or quotes an answer without a question, or quotes a passage the transcript does not hold; it holds an elided passage when each fragment appears in order. A usage limit is not a failure, and restarts the count of three: the worker or the judge is retried 2 minutes after the limit resets, or every 10 minutes when the reset time is unknown or more than 2 minutes past. The judge's reply gives its reset time only as text, so the judge is always retried every 10 minutes. stderr says when the next try is due. Exit 2, when the human is needed to go on: - stdin or stdout is not a terminal, when a model must be picked or an interrupt answered - the input ends while a model is picked - an interrupt's answer is empty, or the input ends before one is typed - the claude opened for /talk, or for a release ready to cut, ends without anything typed - the judge rules a chunk unfinished 6 cycles running; rerun to give it 6 more Rerunning loop-claude starts the chunks that may start, a stopped one first, and each resumes its claude session where it is open."""