Jonathon's AI Wiki

Looper — Visual, Review-Gated Agent Loops for Claude Code

3 min read

Source: raw/gh-star-ksimback-looper.md (GitHub-star stub) + ai-research/looper-github-readme-2026-06-25.md (fetched README, 2026-06-25) — ksimback/looper, MIT, Python, 233★, pushed 2026-06-19

Looper is a Claude Code skill that makes you design a review-gated agent loop before you run it. Instead of firing off an automation immediately, it interviews you into a sharp goal, checkable verification criteria, and cross-model review gates, then compiles a portable spec you can run in-session or hand to an external runner. The maintainer positions it as a design layer in front of Claude Code’s built-in /goal (execution) and /loop (scheduling): “Looper is the design layer that sits in front of both.” This is the missing tool the wiki’s verifier-first thesis implies — it operationalizes review gates before the loop runs rather than hoping for them at runtime.

How it works

  1. Invoke /looper in Claude Code.
  2. Answer interview questions: the loop’s goal, verification method, host model, and reviewer model.
  3. Looper critiques the design against best-practice rubrics (flags unfalsifiable criteria, fuzzy goals).
  4. Review an ASCII flow preview of the loop structure.
  5. Accept or iterate.
  6. Receive artifacts: RUN_IN_SESSION.md, loop.yaml, loop.resolved.json, run-loop.py, and workspace files.

Run in-session (Looper follows the RUN_IN_SESSION.md handoff until gates pass or caps hit) or externally via python3 ./looper-output/run-loop.py.

Why it matters

  • Review gates are designed in, not bolted on. A separate reviewer/judge model evaluates work each pass — and Looper defaults to a different model family (another vendor or a local model via Ollama) to avoid self-evaluation bias. This is exactly the verifier-first discipline made concrete.
  • Termination guards by default: iteration caps, revision limits, budget caps, and no-progress detection — the safeguards loop economics argues you need before running anything unattended.
  • Portable, version-controllable spec. loop.yaml + compiled JSON means the loop design is a reviewable artifact, not an ephemeral prompt.
  • Honest scope: Looper does not do durable orchestration, cron, or multi-process retries — it hands a well-specified loop to Claude Code, /loop, or an external orchestrator. It’s the design front-end, not the runtime.

Key Takeaways

  • /looper is a design layer in front of /goal and /loop — you spec the loop (goal, verification, models, guards) and review an ASCII preview before it runs.
  • Cross-model review by default (different vendor or local Ollama model) bakes in the anti-self-evaluation discipline.
  • Ships termination guards (iteration/revision/budget caps + no-progress detection) — designed-in safety, not afterthought.
  • Emits a portable loop.yaml + compiled spec + run-loop.py, runnable in-session or externally.
  • MIT, Python (PyYAML), 233★, actively maintained — low-risk to adopt; one-line install.sh / install.ps1.

Try It

  1. Install: curl -fsSL https://raw.githubusercontent.com/ksimback/looper/main/install.sh | bash (macOS/Linux) — creates a venv + PyYAML.
  2. Design one loop: /looper, then answer the interview for a real task (e.g. “fix all failing tests in this repo”); set the reviewer model to a different family than the host.
  3. Inspect the spec: read the generated loop.yaml and the ASCII preview before accepting — confirm the verification criteria are falsifiable.
  4. Run + compare: run in-session, then version-control loop.yaml so the loop design is reviewable and re-runnable.

Open Questions

  • How do Looper’s termination guards interact with /loop’s own scheduling when handed off — who owns the iteration cap?
  • Maintainer history / single-maintainer risk beyond the recent push date.

Graph View

Backlinks