Looper: a design layer for Claude Code agent loops

The gap Looper claims: nobody reviews the loop before it runs

Claude Code's own loop taxonomy, as the README summarises it, sorts loops by what you hand off. Turn-based loops hand off the check. Goal-based loops hand off the stop condition through /goal. Time-based loops hand off the trigger through /loop and /schedule. Proactive loops hand off the whole prompt. The README's argument is that every one of those primitives runs a loop, and none of them critiques the loop you just described. Looper is positioned as the layer in front of all four. You invoke /looper, it interviews you, and it produces a spec that any of those runners can execute. The intended user is someone who already automates work in Claude Code and has noticed that a vague goal produces a confidently wrong run. The README puts the failure mode plainly: garbage goal in, confidently-wrong loop out. That is the problem statement, and it is a design problem rather than an execution one.

What /looper actually writes to disk

The skill's output is a set of files, not a running process. According to the README, invoking /looper writes RUN_IN_SESSION.md, loop.yaml, a compiled loop.resolved.json, a human-readable LOOP.md, a thin run-loop.py that you own and edit, an empty loop-workspace/ directory, and a README for the loop itself. That file list is the clearest statement of what the project is. loop.yaml is the source design. loop.resolved.json is the compiled form, described as versionable and reviewable, and the README suggests handing it to a routine and auditing it later. RUN_IN_SESSION.md is the default handoff prompt for running the loop in the current conversation. The split matters: the YAML is what you edit, the resolved JSON is what a scheduler would repeat, and the Python file is deliberately thin rather than a framework you inherit. If you expected Looper to be an execution engine, the artifact list corrects that expectation before you install anything.

Gates, typed verification and the cross-model judge

The mechanism visible in the README's example loop is a two-gate pipeline. A goal plus context (process notes and a definition of done) feeds a plan step that drafts plan.md. A plan gate then judges it, and the diagram shows a revise path capped at three attempts before a pass moves work forward. Delivery writes delivery-N.md, then a delivery gate runs a programmatic check plus a judge, again with a revise cap of three. Verification is typed in three tiers: programmatic first, judge rubric second, human signoff last. The judge is the part Looper differentiates on. The README states that /goal's stop condition is checked by an evaluator model from the same vendor in the same pipeline, with no typed rubric behind the verdict, and that Looper defaults to a different model family for blind-spot coverage. The example loop names hosts and judges concretely (a codex or gpt-5 host drafting the plan, a reviewer-1 judge at the gate), which indicates non-Claude models are first-class in the design rather than an afterthought.

Stop guards and the state files that make a run auditable

The example diagram attaches two side channels to the pipeline. One is state: state.json and run-log.md record the plan and delivery steps as they happen. The other is stop guards, which watch both gates: a maximum of 12 iterations, a no-progress condition that fires after two stalled cycles, and budget caps. These are the constraints that /goal alone does not give you, since the README describes its termination as goal-condition only. The distinction is practical. A goal-condition stop asks whether the objective is met. An iteration cap asks how much work has been spent trying. A no-progress guard asks whether the last two cycles changed anything. Looper puts all three in the design before the loop starts, and the state files are what a later reviewer would read to reconstruct what happened. The README does not specify the schema of state.json or the exact syntax of the budget cap, so treat those as things to inspect in a generated loop rather than documented guarantees.

Getting it running and linting the design in CI

Two entry points appear in the material. The first is the slash command: invoke /looper inside Claude Code to start the interview and generate the artifact set. The second is looper lint, introduced in v0.4.0 alongside the runner contract, and described as CI-friendly static design checking. That is the piece worth pausing on. A lint step over loop.yaml means the design can fail a build before a runner ever picks it up, which is a different posture from a prompt you paste into a session. The README does not give the exact lint invocation, the rule set, or the exit-code behaviour, so I cannot tell you what lint rejects beyond the general claim of static design checks. If you plan to wire it into a pipeline, the first thing to do is run looper lint against the bundled example at examples/ai-workflow-mapping/loop.yaml and read the output, because that example is the only design the README shows in full.

Where the design layer stops

The README's own comparison table marks Looper as running the loop, with the cell text truncated mid-word in the supplied material, so the claim that it executes is present but its scope is not fully documented here. What is documented is narrower and more honest: Looper writes files and hands the current session a clear execution prompt, and run-loop.py is described as thin and yours to edit. That means the execution path is something you finish. If your loop needs retry semantics, parallel branches, or integration with an existing orchestrator, Looper gives you a spec and a starting script rather than a runtime. The second limitation is the judge. Cross-model review is the project's main argument, and it depends on a second model being available and reachable from your session. The README does not describe what happens when the judge model is unavailable or returns malformed verdicts, and it does not document fallback behaviour at a gate. Design-time coaching cannot cover that runtime gap.

How this differs from /goal and /loop in practice

The nearest alternatives are the Claude Code primitives themselves, and the difference is layer, not feature. /goal sets a persistent objective and keeps working until the current state satisfies it. It takes whatever goal you type, however vague, and it will not tell you the goal is unfalsifiable or that done was never defined. /loop takes an interval and a task and re-fires the prompt or skill on that cadence, with self-pacing if you omit the interval; /schedule moves the same firing to the cloud so it continues when your machine is off. Both are execution primitives. Neither coaches the goal, defines success criteria, or brings in a reviewer. Looper's answer is to produce a coached goal, typed verification and a cross-model gate, then let /goal provide persistence, /loop or /schedule provide the trigger, or Python run the thing later. The README is explicit that Looper does not replace them. If your problem is that a loop is not firing often enough, Looper is the wrong tool; /loop already solves that. If your problem is that the loop fires and produces work nobody can defend, that is the case Looper is built for.

Version history, licence and what to check before adopting

The release trail is short and recent: v0.2.1 as an installer hotfix, v0.3.0 adding the loop pattern library, and v0.4.0 adding looper lint plus the runner contract. An installer hotfix two releases back is a reasonable signal that the install path had rough edges, and the addition of a runner contract in v0.4.0 suggests the boundary between design and execution was still being drawn as of that release. The project is MIT licensed, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and if you redistribute a modified run-loop.py you should read the MIT terms yourself. Looper is a Claude Code skill, so it inherits that tool's availability and terms as a dependency, and the README names no homepage, so the repository is the only distribution channel documented here. Before adopting, generate one loop from the bundled example, read loop.resolved.json end to end, and confirm the judge model you intend to use is one you can actually call from your session. The value of the project is concentrated in that resolved file, because it is the artifact a routine would repeat unattended.

Editorial conclusion

Adopt Looper if you already run agent loops in Claude Code and keep rewriting the same ad-hoc goal prompt, or if you need a versionable artifact for audit. Do not adopt it if you want something that executes the loop for you: the README states the emitted run-loop.py is thin and you own it, and the design layer assumes you will drive execution through /goal, /loop or /schedule. Verify first that the cross-model judge you intend to wire in is actually reachable from your session, and read the generated loop.resolved.json before trusting it, since that is the file a routine would repeat.

Official sources

1. Issues
2. ksimback/looper on GitHub
3. License: MIT
4. README
5. Releases