132 lines
7.1 KiB
Python
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
|