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

178 lines
12 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: 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 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 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-<key>, such as loop-claude-config. <key> 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 <task>
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 <window>, 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
<task> starts it again before any other. To stop every chunk, press Ctrl-C in each window. A chunk's
claude session is named "A <key> loop-claude <window>", 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
<session>:<window>, 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 <ID> 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/<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_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 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.
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/<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, 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 <task> starts the chunks that may start, a stopped one first, and each
resumes its claude session where it is open."""