ksimback/looper: a design layer for Claude Code agent loops

The problem Looper targets: loops that run confidently in the wrong direction

Most agent-loop tooling in Claude Code answers the question of how to keep something running. `/goal` holds a persistent objective so the session does not stop after every step. `/loop` and `/schedule` re-fire a prompt on a cadence, locally or in the cloud. None of them asks whether the objective was worth pursuing, or whether the thing you called done is checkable.

The README makes this critique directly. `/goal` "takes whatever goal you type, however vague," and the stop condition is checked by an evaluator from the same vendor inside the same pipeline, with no typed rubric behind the verdict. That is the failure mode Looper is built around: an unfalsifiable goal plus a self-assessing evaluator produces a loop that terminates cleanly on work nobody wanted.

Looper's audience is narrow and specific. It is for people who already write agent loops and have felt this, not for someone who wants their first automation. The README frames it as "a design layer first": it writes files and hands the current session an execution prompt rather than running anything itself.

Goal, plan gate, delivery gate: the loop shape Looper compiles

The worked example in `examples/ai-workflow-mapping/loop.yaml` shows the shape. A goal and context feed a drafting step hosted on a named model. That draft hits a plan gate judged by a reviewer. If the judge says revise, control returns to the draft, capped at three revisions. On pass, a delivery step writes output, which hits a second gate combining a programmatic check with a judge. Pass both and the loop reaches final output.

Two side structures run alongside. A state and log channel records into `state.json` and `run-log.md`. Stop guards watch both gates: a maximum of twelve iterations, a no-progress check that trips after two stalled rounds, and budget caps.

The verification block is typed, and the README gives the ordering: programmatic first, judge rubric second, human signoff last. That ordering is the design opinion worth noticing. A programmatic check cannot be talked out of a verdict, so it belongs before a model gets an opinion.

The reviewer is a different model family by default. That is the mechanism behind the blind-spot argument, and it is also the main operational cost, since it means a second provider in the loop.

Installing Looper and running a first design pass

The repository ships `install.sh` and `install.ps1` at the top level, alongside a `pyproject.toml` for the `looper-skill` package. The package declares `requires-python = ">=3.9"` and one dependency, `PyYAML>=6.0`.

Because Looper is a skill rather than a standalone binary, the README's entry point is the slash command. Invoke it inside a Claude Code session:

/looper

The skill interviews you about the loop you have in mind, critiques the design against its rubrics, and then writes a set of artifacts. According to the README those are `RUN_IN_SESSION.md`, `loop.yaml`, a compiled `loop.resolved.json`, a human-readable `LOOP.md`, a thin `run-loop.py` you own and edit, an empty `loop-workspace/`, and a README for the loop itself.

The `pyproject.toml` also carries a `[tool.looper]` table pointing at the skill root and the runner template:

[tool.looper]
skill_root = "."
runner_template = "templates/run-loop.py"

Before running anything, the design can be checked statically. The v0.4.0 release is titled "looper lint + runner contract," and the README describes `looper lint` as CI-friendly static design checking:

looper lint loop.yaml

Run that against a loop you already have. If the linter rejects it, the disagreement is the useful output, and it costs nothing to resolve before a model starts editing files.

What Looper does not do, and where the documentation goes quiet

Looper does not schedule, poll, or persist across sessions on its own. The README states plainly that `/loop` and `/schedule` are schedulers and that Looper "doesn't replace them; it gives them something good to run." If your actual problem is "run this every five minutes until I say stop," Looper is the wrong layer and adds a design step you will skip.

The runner is another boundary. `run-loop.py` is described as thin and as something you own and edit, which means the execution semantics are yours to maintain. The repository has a `RUNNER-CONTRACT.md` at the top level, so a contract exists, but the README table truncates mid-cell on the question of who runs the loop, and the README does not document rollback behavior for a loop that has already written files when a gate fails. That is a real gap for anyone pointing a loop at a working tree.

There is also a coupling cost the README does not address. The default design puts a second model family in the review seat. That is the point, but it means credentials, latency, and a failure mode where the judge is unreachable and the gate cannot resolve. Nothing in the README describes what happens then.

Finally, the project is young. Releases run v0.2.1, v0.3.0, v0.4.0 across early July 2026, with the last push on 2026-08-09. The `loop.yaml` schema is the kind of thing that moves in that window.

Looper against /goal and /loop: design layer versus execution layer

The honest comparison is not Looper against a competitor product. It is Looper against the primitives already in Claude Code, and the README draws the line itself: `/goal` and `/loop` are execution, Looper is pre-flight design.

The difference in approach is what gets handed off. With `/goal` you hand off the stop condition and the session enforces it. With `/loop` or `/schedule` you hand off the trigger and the cadence re-fires your prompt. With Looper you hand off the design, checked before anything runs, and you get back an artifact: `loop.yaml` plus a compiled `loop.resolved.json` that can be versioned and audited later.

The second difference is who judges. `/goal` uses a built-in evaluator from the same vendor in the same pipeline. Looper defaults to a different model family against a typed rubric, with explicit plan and delivery gates and termination guards layered around them. Whether that is worth a second provider is a judgment call, but it is a genuine architectural difference rather than a feature-list one.

The third difference is inspectability. `/goal` lives in the session. A Looper spec is a file, which means a reviewer can read it, and `looper lint` can reject it in CI before a human ever looks.

Maintenance, licence, and what upgrading actually costs

Looper is MIT licensed, with the licence held in a `LICENSE` file referenced from `pyproject.toml`. MIT is permissive: you can modify and redistribute, including in closed products, provided the copyright notice and licence text travel with the code. That is a summary of the licence identifier, not legal advice; read the file if the distinction matters to your organization.

The maintenance signal is mixed but readable. The repository is not archived, and the last push was on 2026-08-09, roughly six weeks before this writing. The release cadence in early July 2026 was fast: v0.2.1 was an installer hotfix, v0.3.0 added a loop pattern library, and v0.4.0 added `looper lint` and the runner contract. That is three releases in three days, which suggests active work at that moment and also that the surface was still settling.

Upgrade cost concentrates in two places. The generated `run-loop.py` is yours, so a template change in `templates/run-loop.py` does not propagate automatically; you will be diffing by hand. And `loop.resolved.json` is compiled output, so a schema change in a new version may invalidate specs you have already committed. Re-running `looper lint` after an upgrade is the cheapest way to find that out.

Editorial conclusion

Adopt Looper if you already run agent loops in Claude Code and keep hitting the same failure: a goal nobody can falsify, a stop condition judged by the same model that did the work, and no artifact to review afterwards. It is the wrong tool if you want a scheduler or a daemon; the README is explicit that /loop and /schedule fire tasks, and Looper only designs what they fire. Before committing, read RUNNER-CONTRACT.md because the README truncates the runner table, run looper lint against one of your existing loops to see whether the rubric agrees with your instincts, and confirm that the reviewer model you intend to wire in is one you can actually reach from the session. The repository's last push was on 2026-08-09, so the design surface is recent but the runner contract is the part most likely to move under you.

Frequently asked questions

Official sources

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