Files
claude-config/bin/loop_claude/loop/usage.py
T

129 lines
9.0 KiB
Python

HELP = """Run a task as headless claude cycles; a judge interrupts only when a decision is the human's.
usage: loop-claude <task>
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
premises; 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 README.md voids it, choose between ways to deliver the chunk's todo.md 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,
~/.claude/rules/*.md and ~/.claude/skills/larv-review/standards/*.md, 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. Words:
~/.claude/CLAUDE.md → "Vocabulary".
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
loop-claude prints the question on its terminal and lists it in loop-inbox, which shows the
interrupts of every loop on the machine. The first answer counts, from either place:
- 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 session with `claude --resume` where it was typed, to read the diff or
discuss first. Once that claude exits, the judge rules on what was typed there.
- Enter alone, on loop-claude's terminal: stops the loop.
A release ready to cut opens that session on the terminal at once, since only the human may cut it;
loop-inbox lists it too. While claude is open, Ctrl-C reaches it alone, and the loop goes on.
Where ~/.claude/.env exists, loop-claude also sends the human each question, each release ready
to cut and each stop as a Mattermost DM, as bin/mattermost-dm sends it. Two stops are left out:
Ctrl-C, and printing this help. A DM that fails is said on stderr, and the loop goes on.
While it runs, loop-claude also lists itself in loop-inbox, with the todo.md items its chunk takes,
as bin/loop_state/running_loops.py describes.
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree 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.
Each project has one session, named "A <key> loop-claude", where <key> is the checkout's path
relative to ~/code, or to / outside it. The session is deleted when its chunk finishes. At every
interrupt, and as every cycle ends, Ctrl-C and a failure included, the session's transcript is
copied into a folder per chunk under $LOOP_CLAUDE_TRANSCRIPTS/<key> (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 <key> 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-inbox doesn't list that
question. 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.
Where the project's model is on the routing ladder (bin/model_routing/ladder.py), the worker and the
session /talk opens run on the rung that the chunk's todo.md 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.
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; loop-inbox lists it too. 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
- README.md, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
~/.claude/skills/larv-review/standards/*.md where they exist, cannot be read or is not UTF-8
- README.md holds no premises
- the models file cannot be read or written
- 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, here or in loop-inbox, 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 resumes any open session."""