Looper is a Claude Code skill for designing an agent loop before anything runs. Invoked with /looper, it interviews you about the goal, critiques the design against built-in rubrics, helps you add a reviewer or judge model, shows the loop as an ASCII flow preview, and then writes a set of artifacts: RUNINSESSION.md (a handoff prompt for the current session), loop.yaml, a compiled loop.resolved.json, a readable LOOP.md, a thin run-loop.py you own, and an empty workspace.
The design flow follows the loop shape goal, plan, review, deliver, judge, stop. Verification criteria are typed as programmatic (a command returns pass or fail), judge (a model scores a rubric), or human (you sign off). Looper recommends a reviewer from a different model family than the host, including non-Claude models, and refuses to emit a loop without a termination guard: iteration caps, revision caps, no-progress signals, budget limits, and human checkpoints are all made explicit. Wall-clock caps are enforced by the runner, while token and dollar caps are advisory unless you add accounting around the configured CLIs.
Looper positions itself as the design layer in front of Claude Code's execution loops. /goal hands off a stop condition, /loop and /schedule hand off a trigger, and routines hand off a whole prompt. Looper produces the coached, lint-checked spec those mechanisms then run. It does not provide durable orchestration: no cron scheduling, no step-level retries across restarts, no sub-agent lifecycle management, no concurrency control, and no production run history.
Running in-session, the loop follows RUNINSESSION.md and writes plan.md, delivery-N.md, review-N.md, state.json, and run-log.md into the workspace until gates pass, a cap is hit, or repeated no-progress is detected. The Python runner runs the same spec outside the session. loop.resolved.json is an interchange format with a runner contract covering gates, caps, consent, redaction, state, and exit codes, and a ten-scenario conformance suite checks third-party runners without real model CLIs.
A council sends project context to another vendor's model CLI. Looper scopes what is sent, redacts files matching configured globs, warns about any caught leak, and asks for consent before the first cross-vendor send. A model registry file stores only command names and argument arrays, never credentials.
Features
- Goal coaching: critiques vague or unfalsifiable goals and forces a definition of done
- Typed verification: programmatic checks first, judge rubrics second, human sign-off last
- Cross-model council: a reviewer (notes) or judge (verdict) from a different model family than the host
- Review gates: an explicit plan gate and delivery gate with revision caps
- Termination guards: iteration, revision, no-progress, and budget caps plus human checkpoints
- Pattern templates: security-scan, code-review, bug-hunt, docs-sync, and research-synthesis as compiler-validated loop.yaml files with placeholder slots
- Static lint: looper lint flags all-vibe verification, unevaluable judge criteria, undeclared cross-vendor egress, a judge sharing the host's model family, missing caps, and unresolved placeholders, with --strict and --json for CI
- Two execution paths: an in-session handoff prompt or a standalone Python runner
- Runner contract: a normative spec and conformance suite for building runners in other languages or agent stacks
- Consent and redaction: scoped context, glob-based redaction, leak warnings, and explicit consent before cross-vendor sends
- Model registry: detected model CLIs stored as invocation metadata without keys
