145 lines
10 KiB
Python
145 lines
10 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 goals file has ## Goals and ## Audience, the
|
|
premises. The goals file is the one the project's config, ~/.claude-projects/<key>/config.toml, sets
|
|
as goals-and-audience; `project-config goals-and-audience` prints it. 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 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.
|
|
|
|
The routing ladder is a JSON list of rungs, least competent first, each a model at an effort of low,
|
|
medium, high, xhigh or max:
|
|
|
|
[
|
|
{"model": "claude-opus-5-5", "effort": "medium"},
|
|
{"model": "claude-fable-5-2", "effort": "low"}
|
|
]
|
|
|
|
This setup ships one, routing-ladder.json at its root. A project that keeps a routing-ladder.json in
|
|
its config's folder, ~/.claude-projects/<key>/, 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, 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.
|
|
|
|
Where the project's model is on its routing ladder, 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
|
|
- the goals file, 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
|
|
- 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, 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."""
|