loop-claude

A software factory that asks you only what is yours to decide

You write down what you want and who it is for. An AI plans the work, writes the code, gets it reviewed and merges it, one pull request at a time, for as long as the plan holds work.

The problem

  • You babysit the agent. Every few minutes it asks something, or waits for a yes.
  • It forgets. Long sessions drift, and you explain the same context again.
  • It guesses. It decides what it should ask, and asks what it could decide.
  • AI review is noise. It nitpicks forever and still misses what matters. So you review it all again, and nobody can read the code six months later.

What loop-claude does

  • It runs unattended. A judge reads every run, and interrupts you only for a choice that is yours.
  • It starts fresh every chunk. The repo is the memory: goals, plan and decisions are written down.
  • It decides by your goals. An answer you give is recorded once, and never asked again.
  • Review, refined by measurement. Narrow specialist reviewers report only real defects, and stop after two rounds: 110 later rounds found no red finding. Tests are checked by breaking the code on purpose. The review is tuned by replaying past rounds.

What it aims for

  • Maintainable for years. Code that stays easy to read, change and debug, tomorrow and after seven years.
  • The highest quality, with the fewest interruptions.
  • Ask only when unsure, and never the same thing twice.
  • Keep lowering cost, unless that would cut quality.
  • The same rules in every project, and fast delivery.

Each aim has a signal it is measured by, and a counter-signal that catches it being gamed.

For developers and teams who build with AI agents and want a software factory: work that keeps flowing without someone watching it, at a quality they would sign off on.

466chunks finished since 2026-10-03, one PR each
12projects that finished a chunk
2,538commits in the setup's own repo
The flow, simply

An AI that works through your plan, one pull request at a time

Three sections. A picks the work, B does it, C checks the result. The next page opens up every box, in the same places.

Why: sources 1

The flow, every piece

The same three sections, opened up

Same layout as the previous page. Each big box there is the group of steps in the same place here.

Why: sources 1, 2, 3

Who is who

Four roles

One human. Three kinds of AI, each with one job.

Human

Write the goals and the audience in the README. Approve the plan. Answer questions. Cut releases.

Worker

A Claude Code session with no human at the keyboard. It writes tests and code, opens the PR and runs the review.

Judge

A second, short AI run after each worker run. It reads the log and decides: finished, keep going, or ask you.

Reviewers

Specialist AIs. Each looks at the change from one angle and reports problems. They never edit code.

A fresh start every chunkEach chunk gets a new AI session with an empty context. Nothing piles up, so it can run for long stretches, as far as the plan reaches.
One chunk = one PREach turn of the loop ships one small, reviewed pull request.
Many AI reviewersSecurity, stability, product, prose. Every change is checked before merge.
You stay in chargeGoals, open questions and releases are yours. Nothing ships a release without you.

Why: sources 3, 4

Where things live

Three places

Your project's repo holds its own goals, plan and decisions. The setup holds the rules, reviewers and tools that every project shares.

Your project's repo

One per project. Everything the next chunk needs.

  • README.md goals and audience
  • todo.md the plan: one scored table
  • AGENTS.md working rules, and every decision's title
  • docs/decisions.md answers given once, with the reason
  • docs/comprehension-history.md every readability score
  • docs/reading-cost.md what each chunk read
  • CHANGELOG.md what users get, if it publishes
  • the code and its tests

The setup: ~/.claude

The claude-config repo, at a tagged release. Shared by every project.

  • CLAUDE.md rules every session follows
  • rules/ topic rules, loaded when a matching file is touched
  • agents/ the reviewers
  • skills/larv-review/ the review recipe and its standards
  • skills/comprehension-panel/ the simulated readers
  • principles/ technical principles reviewers hold code to
  • bin/ the tools: loop-claude, chunk-preflight, chunk-pr, rule-hook, rank_todo.py, run-heavy and more
  • settings.json runs rule-hook before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call

The machine and the forge

Not tracked by either repo. The archive and the models file sit inside ~/.claude, but git ignores them.

  • ~/code/<repo>-item-<ID> a worktree per chunk; its branch item-<ID> becomes the PR
  • ~/.claude/loop-claude-transcripts/ every run's full log
  • ~/.local/state/larv-review/ every review report
  • ~/.claude/loop-claude-models.json each project's model
  • the forge (GitHub or Gitea) the pull request and CI

The worker never commits to main. The setup itself is developed in ~/code/claude-config, by the same loop; ~/.claude only ever holds a release.

Why: sources 5, 6

Zoom in: A · Start

A · Start, in detail

Plain code, no AI. It decides what the next chunk is, and which model does it.

Before anything

The README must hold ## Goals and ## Audience. Without them the loop refuses to start.

Each worker waits until a quarter of the machine's memory is free.

Prepare

chunk-preflight fetches the repo and reads todo.md as main holds it.

It makes a worktree beside your checkout, on its own branch. There it runs four checks: the plan's ranking, whether a readability score is due, the reading cost, and the hardest places to read.

The first prompt

The task, the README's goals and audience, and every fact Prepare found: the last release, unreleased changes, the item, the items that may join it, the files it names, open PRs.

It also names the models to review on.

Rank the plan, then pick the work

  • Rank: rank_todo.py scores every item by the goals it moves and its size, and sorts the plan. A program refuses a commit that leaves todo.md unranked.
  • An item waits while it is a question for the human, or while an item that blocks it is still in the plan.
  • The chunk takes the first item that doesn't wait, plus every item of the same release that needs the same reviewers.
  • A risky item (page 12) ships alone. Up to ten tiny items can share a chunk.

Pick model

By the item's scores: page 13.

When the next release…The chunk is
has a ready itema normal chunk
has no items left, but unreleased workthe release review
has had its release reviewnone: the loop stops, and the human cuts the release
has no items and no work yetplanning: the worker moves the best items in, and the human approves them

Why: sources 2, 25

Zoom in: B · Work

B · Work, in detail

The worker follows a fixed recipe, called larv-review. The same six steps as page 3.

Build

A test comes first, and the worker sees it fail. Its expected values come from the item, never from the code.

Then the simplest change that makes it pass. A draft PR opens, so CI runs while review goes on.

Stuck? The same test fails after two fixes, or a round 2 still reports a red finding: the hard part goes to a stronger model.

Review

Specialist reviewers, in waves. At most two rounds each per chunk. Only the fix for a red finding runs a reviewer again.

The release review adds the architect and the principles auditor on top: the whole project, up to five rounds each.

Gate

Merge the latest main in. Check the plan's format. Run the tests. Wait for every CI check.

Mark the PR ready. Then wait up to ten minutes for the repo's own review bot, if it has one.

Goals check

Does the PR break a goal the project must keep? Then it does not merge. The change is redesigned, or its item dropped.

Does it work against a goal the project aims for? Then the human is asked.

Readability

When due, simulated readers score the project, or compare it before and after. It never blocks the merge. A low score adds a refactor item to the plan.

Merge

Merge the PR. Remove its items from todo.md, and move them to CHANGELOG.md if the repo publishes something.

The session ends. The next chunk starts fresh.

A planning chunk follows the same steps. Its change is plan rows, and the human approves them before any code is written. Why: sources 7, 8, 19, 20, 21

Zoom in: B · Work → Review

The reviewers

Each reviewer has one narrow job. When two were merged into one, it missed findings (source 14). They run in waves, each once the one before is done. Wave 1 runs only in the release review.

ReviewerRuns whenWhy it is its own reviewer
ArchitectureOnly in the release review, the last chunk of a release.Structure drifts slowly over many small PRs; only a read of the whole project shows it. Each finding names a future change the code makes harder.
PrinciplesOnly in the release review.Holds the whole project to the goals and the written technical principles: a checklist read, not a design read.
SecurityCode or config changed. A deeper multi-agent scan instead when it touches login, permissions, secrets, crypto, untrusted input or a new outside surface.Finding holes takes an attacker's mindset. A correctness reviewer looks for what breaks, not for what can be abused.
OverridesThe worker bypassed a rule that a program enforces, with a written reason.The worker cannot judge its own exception. A second opinion keeps the rule, or accepts the reason.
StabilityCode, config or tests changed.Bugs, edge cases, error handling, line by line. It breaks the changed lines on purpose (mutation testing) to see whether the tests notice.
Product ownerSomething users see changed: an API, CLI flags or exit codes, a file format, UI, error text, docs.Reads the change as a user would. Ease of use and upgrade paths are invisible from inside the code.
ProseText changed: docs, comments, help, error messages. One round.Writing has its own rules: short, clear, most important first. A docs-only change runs just this light pass, plus product owner for docs outside readers see.

Reviewers only report; a program refuses every edit they try. The repo's own review bot, if it has one, runs at the Gate. Why: sources 14, 16, 17, 18, 26

What reviewers report

Findings and rounds

Every finding gets a colour. The colour decides what must happen.

RedMust fix. Never declined.
YellowFix, or decline with a written reason.
GreenA nit. Fix, answer, decline with a reason, or file.
QuestionAnswered from the repo, or asked.

Why: sources 15, 16

Zoom in: B · Work → Readability

The comprehension panel

Simulated readers, from junior to architect, read the whole project and score it from 1 to 10.

They score four things

Navigation
Can I find where things are?
Locality
Can I change one piece without holding the rest in my head?
Shape
Does each level have few parts, with names that tell the truth?
Self-sufficiency
Does the code explain itself?

Real numbers: this setup's own latest scoring run (PR #397). Under 7.0, a refactor item is filed and ranked high.

Two ways to ask

Scoring run

Four readers give a 1–10 score. Runs when a release's items run out, or when an item aims at the 7.0 target.

Paired ruling

Two readers compare before and after: better, same or worse? Runs in each release review.

Readability doesn't block a merge. It steers the plan: code health ranks first among every project's goals. Why: sources 22, 23, 24

Zoom in: C · Check

C · Check, in detail

A short AI run after every worker run. It decides what happens next, and when to ask the human.

What it reads

The end of the worker's log. The README's goals and audience. The project's AGENTS.md and docs/decisions.md. The setup's CLAUDE.md, rules/ and review standards.

What it may answer

A question those files already answer. It quotes the answer word for word, and the worker goes on.

A quote not found word for word goes to the human instead.

Checks on its reply

A reply in the wrong shape, or quoting the log wrongly, counts as a failure and is retried. Three failures in a row stop the loop.

VerdictWhenWhat happens next
FinishedThe PR is merged, and every answer the human gave is written down.Back to A. A new session, with a fresh, clean context.
UnfinishedWork is left.Back to B. The same session goes on, told what is left.
Already settledThe worker asked something the repo's docs already answer.Back to B, with the quote.
Human's callOnly the human can decide.The human types an answer, or opens /talk. Back to B with it.

Rules it follows

Why: sources 3, 4, 26

What to do next

The plan is one scored table

Every item gets numbers. A program sorts them. The top item is next.

IDReleaseItemLEIRSMovesScore
2810.7.0Remove a merged chunk's worktree and branch and fast-forward the main checkout with one command.323631.4 by 2, 1.5 by 21.6
2860.7.0Lower the reading cost of the files a chunk reads most before its first commit.322551.4 by 41.0

Two real rows from this setup's own todo.md.

Why: sources 9, 10, 11, 12, 13

Right model for the job

The model ladder

Easy work runs on a cheaper model. Risky work gets a stronger one, and stronger reviewers.

How a rung is picked

  • Worker: L 1–2 one rung down, L 3 the project's rung, L 4 one up.
  • Reviewers: never below the project's rung or the worker's. E + I of 5 or more steps them up, one rung per point.
  • Readers and security: always the project's rung. The judge: never below it.

When the worker climbs

  • The same test fails after two fixes.
  • A reviewer still finds a red problem in round 2.
  • A review rules the work below standard.

At most two rungs above the start without asking you. The ladder shown is for a project on Opus 5.5.

Why: sources 25, 26

From chunks to a version

A release

Chunks fill a release. A final review cleans up. You cut it.

  • Release review: the architect and the principles auditor read the whole project, up to five rounds each. The worker fixes what they find.
  • Then the readers compare before and after.
  • When the release is ready, the loop stops and opens a session for you. It never starts the next release on its own.
  • Version number and publishing are always yours.

Why: sources 17

Part 2 · In depth

Talking to the loop

You start it with one command. It interrupts you in its terminal.

# inside a project checkout whose README has ## Goals and ## Audience
$ loop-claude "Do the next chunk."
… worker running: item 12 on claude-opus-5-5 at medium effort
… judge: unfinished; resuming the same session
… worker running
? The worker asks: goal 2 says the CLI stays stable, but item 12 renames a flag.
  Keep the old name, or change goal 2?
answer › Keep the old name. Record it in docs/decisions.md.
… worker resumes with your answer
✓ judge: finished · PR merged · next chunk starts in a fresh session

An example. Only a choice reserved for the human interrupts: a goal, a release's items and its cut, or the model ladder. Why: sources 4, 28

You typeWhat happens
a line of textThe worker resumes headless with your answer. It must record it before the chunk can finish.
/talkOpens the worker's session for you (claude --resume). Read the diff, discuss, then exit.
Enter aloneStops the loop. Rerunning resumes where it was.

When the loop stops by itself

It stops only when it needs you, or something is broken.

ReasonWhat to do
Release ready to cutIt opens a session for you. Cut the release.
6 unfinished verdicts in a rowLook at what is stuck; rerun to give it 6 more.
Worker or judge failed 3 timesRead the reason it prints. A usage limit is not a failure; it waits instead.
No goals in the READMEWrite ## Goals and ## Audience first. Nothing else runs until they exist.

Guard rails

Rules a program can check are enforced by a program, not by trust.

RailWhat it does
SandboxRun it only on a dedicated machine, such as a VM with no access to production: Claude Code skips permission prompts there.
rule-hookRuns before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call. Blocks e.g. multi-line commit messages, unpinned images, containers without memory limits, a third review round. Some rules allow a written override; the Overrides reviewer judges each one.
run-heavyHeavy commands (builds, mutation tests, full test runs) wait for a shared slot: one per 4 CPUs on the machine.
MemoryEvery container gets a memory limit. A new worker starts only while a quarter of the machine's memory is free.
ContextEach worker session, the /talk session and their subagents compact their context at about 170k tokens, keeping what the chunk still needs.
ArchiveEvery run's full log is saved. Every 20 cycles, figures from it may ask the human to change which model does what.
Main branchNothing is pushed to main. Every change merges through a PR whose gate passed.

Measured, so it can improve

Why: sources 5, 27

Why it works this way

Each choice rests on research, a book, our own measurements, or trial and error. The numbers match the "Why" line on each page.

The loop

1A fresh, clean context every chunkReasoning Every turn re-sends the whole context, and compaction loses detail. The repo holds the memory between chunks, so a new chunk loses little.
Own measurement Simulated on 90 archived chunks, compacting at about 170k tokens would save about $78, 21% of the workers' spend. 36 times the cache had expired and the whole context was sent again, costing $61, up to 785k tokens each. Within a chunk the session goes on: a fresh context for review would save $39, but compaction already saves that as part of its $78.
Research Models use facts in the middle of a long context worst: Liu et al., "Lost in the Middle", TACL 2024. Answers degrade as input grows: Hong et al., "Context Rot", Chroma Research, 2025.
2Several items per chunk; risky items aloneOwn measurement Over 165 chunks, one item cost a median 1.30M tokens and two items 1.33M. Review costs about the same per chunk, so sharing it is cheap. At risk R 6 the median rose to 2.7M, and one in ten passed 8.8M, so R above 5 ships alone.
3The worker makes its own small choicesOwn measurement 92 of 255 interrupts already held the worker's recommendation. A chunk with an interrupt took a median 7.1 hours, against 0.44 hours without one. So the worker takes its recommendation on any choice no rule reserves for the human, and records it.
4Every answer is written downReasoning A finished chunk's session is deleted. An answer kept nowhere else would be asked again in a later chunk. One goal of the setup is to never ask the same thing twice.
5A program enforces every rule it can checkVendor docs Anthropic's best-practices page calls CLAUDE.md advisory and hooks deterministic. So rule-hook blocks a rule-breaking tool call before it lands, in every project.
Own measurement The override marker's spelling was picked by a panel of three fresh readers, two to one.
6Rules load by topic, not all at onceResearch Anthropic's memory docs say a longer CLAUDE.md reduces adherence. IFScale (arXiv:2507.11538) measures adherence falling as the number of instructions grows. So each topic's rules load only when a matching file is touched.
7The worker hands subagents only searches and independent workOwn measurement A subagent's report cost a median 8% of the worker's peak context. Search output (sed, grep) was 41% of its shell results. So searches, and work independent enough to run in parallel, go to subagents; edits stay with the worker, which would re-read a delegated diff anyway.
8A limit on how much the worker reads at onceOwn measurement Under "no more than 80 lines of a file, or 3,000 characters of output, at once", three test tasks read 45–60% less, at the same or lower cost, every task done as well.

The plan

9Goals with a signal and a counter-signal; achieve vs. maintainResearch Specific, hard goals beat vague ones: Locke & Latham 2002. A narrow goal makes people neglect the rest: Ordóñez et al. 2009, "Goals gone wild". A measure made a target gets gamed: Manheim & Garrabrant 2018 (arXiv:1803.04585). Goals that keep a state differ from goals that reach one: van Lamsweerde 2001 (KAOS).
Research Instruction files alone did not raise agents' success (arXiv:2602.11988). So each goal names a signal that shows it still decides cases.
10Risk adds L, E and I, each level about ×10Research Multiplying 1–10 labels misleads: Stevens 1946; Cox 2008, Risk Analysis. Adding levels on a ×10 scale multiplies the real chance and cost: Kaplan & Garrick 1981. Impact is the worst case, not a sum: NIST; CVSS v4.
11What makes L high: size, spread, something new, live configResearch Size predicts a defect best: Zeng et al. 2021, ISSTA. So does spread across files: Kamei et al. 2013. About 70% of Google's outages come from changes to a live system: Google SRE book. Complexity metrics add little once size is known: El Emam et al. 2001.
12Order the plan by value over sizeBook Doing the highest value per unit of work first minimises total waiting: Smith's rule, 1956; Reinertsen, The Principles of Product Development Flow, 2009 (WSJF).
13Check every score against finished chunksResearch Compare guesses with outcomes: Brier 1950. Correct estimates against similar past cases: Flyvbjerg 2006. Anchor each level to real examples: Smith & Kendall 1963. People are overconfident: Hubbard, How to Measure Anything.
Own measurement score-outcomes shows each finished item's guessed scores beside what its chunk measured.

Review

14Narrow, separate reviewersExperience Early on, a reviewer with too broad a responsibility found fewer issues.
Own measurement On 2026-11-09, merged reviewers were replayed on archived rounds. Stability, product owner and prose as one reviewer cost half as much, but found 15 of 34 prose findings again, against 22–23 for the prose reviewer. Architect and principles auditor as one found 5 of 17 principles findings, against 10, and lost both red ones. Even stability and product owner alone, as one, found 4–5 of 16 product-owner findings, against 7–10. In every merge, one absorbed pass lost findings, at a third to half the cost. Method and figures: reviewer-merge-trials/ in the setup's repo. Merging reviewers that check the same kind of thing did hold up: one principles auditor found as much as several.
15At most two rounds per reviewerOwn measurement Since 2026-10-21, across all projects: round 1 ran 357 times and found 59 red findings. Round 2 ran about 200 times and found 12, mostly in round 1's fixes. Rounds 3 and later ran about 110 times and found none, for about $125. Asks for more rounds were 24 of 59 interrupts.
16Reviewers report only real problemsVendor docs Anthropic's Claude Code best practices: "A reviewer prompted to find gaps will usually report some, even when the work is sound."
Own measurement 320 of the setup repo's first 876 commits, by 2026-10-13, answered a review round. So stability and product owner report only defects, broken requirements or broken principles.
17Architect and principles only in the release reviewOwn measurement The principles audit was the costliest reviewer after the worker, and filed findings unrelated to the chunk. Run once per release over the whole project, it catches the same drift.
18Security: /security-review, not a hand-written reviewerReasoning Its tuned exclusion list and confidence floor would be reproduced worse by hand.
Own measurement Run beside the deep scan, it returned a near-identical report, so the deep scan replaces it when both would run.
19Mutation testing instead of coverageResearch Coverage barely predicts fault detection: Inozemtseva & Holmes, ICSE 2014. Surviving mutants do predict real faults: Just et al., FSE 2014. Google runs mutation testing in code review: Petrović et al., arXiv:2102.11378.
20Test first, with expected values from the itemResearch Tests that copy the code's current output pass on a bug: Charoosaei et al., arXiv:2610.11835 (preprint); Mathews & Nagappan, arXiv:2412.14137. Agents add mocks more often than people: Hora & Robbes, MSR 2026.
Book Software Engineering at Google, ch. 11, 12, 14; Beck, "Test Desiderata"; Khorikov, Unit Testing, ch. 4.
21The worker reads a principle only when a finding names itOwn measurement Over five chunks on each side of the change, review rounds per reviewer fell from 2.26 to 1.52.

Readability

22Code that fits in your head: about seven things per levelBook Seemann, Code That Fits in Your Head, 2021. Ousterhout, A Philosophy of Software Design (deep modules).
Research Working memory holds about four chunks: Cowan 2001. A list found by name is no memory limit: Nielsen Norman Group. No study supports a fixed limit on function length: Jones 2023.
23Reader panel: before-and-after rulings, never blockingOwn measurement Two independent four-reader runs moved up to 0.4 on near-identical code (PR #224). Readers comparing before and after should cancel that noise. A check of that is still pending: it needs 10 commits each scored twice.
Research No published study validates simulated reader panels yet. So the panel steers the plan and doesn't block a merge.
24Reading cost: the median of five chunksOwn measurement One chunk read 2.99M tokens before its first commit, against a typical 80k–370k. An average let that one chunk decide the trend alone, so a rise is the last five chunks' median above the five before.

Models

25The model ladder, and no HaikuBenchmark The rungs follow the Artificial Analysis Intelligence Index: a rung stays only where no cheaper one scores as high.
Own measurement A chunk on Haiku 5.5 ran 2 h 17 min and wrote 3.1M tokens. The chunk before it, on Sonnet 5.5, took 29 min and 111k. Chunks on Haiku took 7.8 extra review rounds, against 2.8 on Sonnet. So Haiku left the ladder.
26Judge and reviewers never run below the project's modelOwn measurement 39 judge verdicts were replayed. The reference judge reproduced 31; on those, Opus 5.5 at medium missed none, and Sonnet 5.5 mislabelled 3 interrupts. A replay of review rounds: Sonnet 5.5 missed 44–55% of what the project's model found.

The machine

27Shared heavy slots and memory limitsExperience On 2026-10-22 an 8-CPU, 16 GiB machine thrashed for hours: four to six loops ran mutation tests, builds and e2e tests at once. The next day, with 7.6 GiB, it hung until a hard reset, from containers with no memory limit. So heavy commands wait for a slot, one per 4 CPUs, and every container gets a limit.
28Names and syntax picked by the people who use themOwn measurement A panel of three readers, seated as the users, picks each new name or spelling. It picked /talk, which opens claude for a question.

Most measurements come from loop-claude's archive of every run, across all projects; others from git history, review replays, the readability history and two machine incidents. The setup's own docs/decisions.md and docs/scoring-and-goals-research.md hold the full reasoning.

Words used here

Chunk
One unit of work, shipped as one pull request. One or more plan items.
Cycle
One worker run plus the judge's verdict on it.
Item
One row of todo.md: a bold one-sentence summary of the change, and its scores.
Worker
The headless Claude Code session that does the chunk.
Judge
The short AI run that reads each worker run and gives a verdict.
Interrupt
A question only you can answer, asked on loop-claude's terminal.
Pass
One kind of review, such as Stability. It runs in rounds.
Round
One review by one reviewer. At most two per pass per chunk, five in the release review.
Gate
The checks a PR must pass to merge: tests, CI, plan format.
Rung
A model at an effort level, such as "Opus 5.5 at xhigh".
Release review
A release's last chunk: whole-project review before you cut it.
Worktree
A separate git checkout per chunk, so your main checkout stays untouched.

The command you use

$ loop-claude "Do the next chunk."   # start the loop in a project