e55b8826fb
# Conflicts: # bin/agent_cycle/interrupt.py # bin/agent_cycle/run.py # bin/agent_cycle/states.py # docs/reading-cost.md # todo.md
183 lines
13 KiB
Python
183 lines
13 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 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, the plan or a 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/agent_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. Where no answer has come 10 minutes before the
|
|
worker's hour-long prompt cache expires, and the worker's context holds at least 60k tokens,
|
|
loop-claude compacts the worker's session with `claude -p /compact` and keeps waiting, so the resume
|
|
doesn't write the whole context again.
|
|
|
|
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/agent_cycle/worker.py), so each
|
|
compacts its context at about 170k tokens. They also save a Bash result of more than 6,000
|
|
characters to a file and see its path and the first 2,000 characters (BASH_MAX_OUTPUT_LENGTH,
|
|
bin/claude_code/output_limits.py).
|
|
|
|
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 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/agent_cycle/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 and bin/agent_cycle/worker_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 plan 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."""
|