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

132 lines
7.1 KiB
Python

"""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 judge then reads
the transcript's end, the premises, and the project's records: AGENTS.md and docs/decisions.md,
where they exist. It rules whether the chunk, the work of one PR, is finished. 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. The fourth question they answer in one cycle goes to the
human too, with the quote.
A question only the human can answer, or a release ready to cut, is an interrupt: `claude --resume`
on the terminal, every worktree first marked trusted in ~/.claude.json. An unfinished chunk resumes
its session next cycle; the next chunk starts a fresh session.
Cycles continue until an exit below or Ctrl-C. Words: ~/.claude/CLAUDE.md → "Vocabulary".
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 to $LOOP_CLAUDE_TRANSCRIPTS/<key>/<chunk>/<sha256>.jsonl (default
~/.claude/loop-claude-transcripts), named by its hash. <chunk> is the hash of the transcript's first
line with a timestamp, the same for every cycle of a chunk. Beside the copy, <sha256>.outcomes.md
holds the verdict, and why the loop stopped. Claude Code keeps a folder per session beside its
transcript, holding the subagents' transcripts among other files; that folder, and every other file
named after the session except the transcript, are copied into <chunk>/session/. A file there is
replaced only by a version that grew from it. A file Claude Code rewrote lands beside its copy as
<name>.<hash of its content>.
Every claude loop-claude starts runs the project's model, saved per <key> in
~/.claude/loop-claude-models.json and read each cycle; a project without an entry, as on its first
run, is asked for one. LOOP_CLAUDE_JUDGE_MODEL overrides it for the judge, LOOP_CLAUDE_WORKER_MODEL
for the worker and the interrupt; with both set, nothing is asked.
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 or docs/decisions.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 cycle number, checkout root and task 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 or exits non-zero, 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 and cannot answer:
- 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 ends with nothing typed
Rerunning resumes any open session.
"""
import dataclasses
import pathlib
import sys
import typing
from loop_claude.project.checkout import checkout_root, project_key
from loop_claude.cycle.run import Cycle, run_cycle
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from loop_claude.effects import Effects
from loop_claude.project.model_choice import get_or_ask_models
from loop_claude.paths import Paths
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_claude.claude_code.session import session_for
from loop_claude.stop import Stop
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> int:
try:
stop = run_loop(argv, env, paths, launcher, cwd, effects)
except KeyboardInterrupt:
stop = Stop(130, "")
if stop.reason:
print(stop.reason, file=sys.stderr if stop.code else sys.stdout)
return stop.code
def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> Stop:
loop_run = loop_run_from(argv, cwd, effects)
if isinstance(loop_run, Stop):
return loop_run
baseline = fingerprint(launcher)
key = project_key(loop_run.root, paths.code)
session = session_for(key, paths)
while True:
if stop := exec_if_edited(launcher, baseline, loop_run, effects):
return stop
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
premises = read_premises(loop_run.root)
if isinstance(premises, Stop):
return premises
records = read_records(loop_run.root)
if isinstance(records, Stop):
return records
models = get_or_ask_models(key, paths, env, effects)
if isinstance(models, Stop):
return models
print(f"\n=== cycle {loop_run.cycle_number} ===", flush=True)
if stop := run_cycle(Cycle(effects=effects, models=models, paths=paths, premises=premises, project_key=key, records=records, root=loop_run.root, session=session, task=loop_run.task)):
return stop
def loop_run_from(argv: list[str], cwd: pathlib.Path, effects: Effects) -> LoopRun | Stop:
if argv[:1] != [RELOAD_FLAG]:
task = " ".join(argv)
if task in ("", "-h", "--help"):
return Stop(0 if task else 1, __doc__.strip())
root = checkout_root(cwd, effects)
return root if isinstance(root, Stop) else LoopRun(0, root, task)
loop_run = decode_handed(argv[1], LoopRun) if len(argv) == 2 else None
if not (loop_run and loop_run.root and loop_run.task):
return Stop(1, f"the edited loop-claude cannot read the cycle number, checkout root and task the running one handed it, likely because the edit changed that handover; rerun loop-claude <task>. Handed: {' '.join(argv[1:])}")
return loop_run