Looper: design agent loops before running them
Looper
A Claude Code skill and /looper command that interviews you and builds an agent loop with checks, an independent reviewer and stop rules before it runs
- 713 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The installer runs from the internet through curl and bash and creates an environment in the skill folder
- The review council sends project context to the CLIs of other vendors' models, and the second-layer secret scrubbing does not cover every format
- A generated loop edits files and runs commands in your project until a gate or a cap stops it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/looperDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The installer runs from the internet through curl and bash and creates an environment in the skill folder
- The review council sends project context to the CLIs of other vendors' models, and the second-layer secret scrubbing does not cover every format
- A generated loop edits files and runs commands in your project until a gate or a cap stops it
This is third-party code. Review the repository files before installing.
What it does
Looper designs an agent loop before the agent starts changing files. The `/looper` command runs a seven-step interview: goal, verification, host model, review council, gates and limits, an ASCII flow preview, and file emission. At each step the skill critiques the answer: it pulls a weak goal toward outcome, scope and a done state, and asks for verification to be programmatic first, then judge-scored, and human sign-off last. A reviewer writes notes, a judge returns a structured verdict, and Looper by default recommends a different model family for them than the host uses. The skill will not emit a loop without stop rules: you need an iteration cap, a revision cap on each gate, a no-progress stop, and either a budget or an explicit human stop point. It writes `RUN_IN_SESSION.md`, `loop.yaml`, `loop.resolved.json`, `LOOP.md` and a `run-loop.py` script into a `looper-output` folder, plus an empty workspace and a README for the loop. The loop can start right away in the current session from `RUN_IN_SESSION.md`, or later from outside with `python3 ./looper-output/run-loop.py`. Instead of a blank interview you can start from five templates: `security-scan`, `code-review`, `bug-hunt`, `docs-sync` and `research-synthesis`.
Who it is for. For developers who run repeating loops in Claude Code such as /goal or /loop and want to agree up front on how to check the result and when to stop.
Good fit when
- You are about to start a long autonomous loop and want it to have a result check, iteration limits and a budget
- You want a second opinion from a model of another family on the plan and on the finished work, for example Codex or Gemini
- You need a reproducible loop in a `loop.yaml` file that you can keep in the repository and run later
- A team wants to check loop specs in CI the same way it checks code, with `python scripts/looper.py lint loop.yaml`
- You want a ready start for secret scanning, branch review, bug hunting, docs-versus-code drift or source synthesis
Not a fit when
- You just need one command repeated on a schedule: the built-in `/loop` and `/schedule` are enough
- You need a one-off script with no goal and verification review: Looper first runs a seven-step interview, which is extra ceremony for a short job
- Project context must not go to another model vendor: the review council hands it to another model's CLI, and a fully local setup is only possible with a local model such as ollama
- The goal is a one-off edit of a single file where a gated loop is overkill
Example request
/looper review-loop --template code-reviewLimitations
Looper stays a design layer. It does not schedule cron jobs, persist step retries across process restarts, manage sub-agent lifecycles, limit concurrency or keep a production run log. If you need those guarantees, hand the spec to an orchestrator built for long runs.
Only an external launch through `run-loop.py` can enforce a wall-clock cap, and a Claude Code session has nothing to hold it with. Secret hiding works in two layers: files matching redaction globs are never read into prompts, and content from them that surfaces elsewhere is scrubbed before every send. The second layer is best-effort: reformatted text and very short values can survive, so for sensitive paths the author recommends a local model.
The installer creates a virtual environment with PyYAML inside the skill folder, and without it `loop.yaml` cannot be read. The skill is marked as not invokable by the model on its own, so you start it with the `/looper` command.
How to disable. Delete the `~/.claude/skills/looper` folder and the `~/.claude/commands/looper.md` file. Loops created earlier live in the folders you named at launch and stay where they are.
FAQ
How do I install Looper in Claude Code?
On macOS and Linux run `curl -fsSL https://raw.githubusercontent.com/ksimback/looper/main/install.sh | bash`; Windows has `install.ps1`. The script clones the repository into `~/.claude/skills/looper` and copies the command to `~/.claude/commands`. The manual route is two steps with `git clone` and `cp`.
How is Looper different from the built-in /goal and /loop?
They run work: `/goal` keeps a session goal, `/loop` repeats a task on a schedule. Looper sits in front of them and designs the loop: it checks the goal wording, the kinds of verification and the stop rules, then emits a spec that either of them can run.
How do I use the ready templates?
Name one after `--template`, for example `/looper my-review --template code-review`. A template leaves a few `{{PLACEHOLDER}}` fields, the wizard asks only about them and still runs the full critique, privacy check and flow preview.
What does another model receive when I use the review council?
Project context goes to the chosen model's CLI. Looper shows what will leave, which redaction globs apply, and asks for consent before the first send. If nothing may leave your machine, use a local model through ollama.
Can I check the loop.yaml file in CI?
Yes, `python scripts/looper.py lint path/to/loop.yaml` checks it for anti-patterns: loops with no programmatic check, a judge from the host's own model family, undeclared data sent to a vendor and missing caps. Errors return exit code 1, and with `--strict` warnings do too.
Discussion
No questions or reviews yet.
Related
SkillsLoopy
Loopy (Loop Library)
A skill and library of ready agent loops: find, audit, repair, craft and run a repeatable workflow
Anthropic skill for Claude Code that audits a multi-agent system and, by measurement, folds subagents into one loop with skills.
A local-first control plane for long-running agents: goals, decisions and status persist across Codex and Claude Code sessions
33 battle-tested skills and a minimal .claude harness for any agent. Installation by script, npx skills or cloning
Skills for cross-provider work between Claude Code and Codex: one agent drafts the plan, the other reviews it, then a build and an independent code inspection f
One agent launches others in the background: Claude Code, Codex, Copilot CLI, Grok Build and Pi, with a model chosen per stage.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Looper: design agent loops before running them (this card) | no | 713 | ||
| Ralph Orchestrator | no | not required | 3,194 | runs agents in a loop until the task is done, and you write the loop scheme yourself |
| Zeroshot | no | 2,110 | runs a graph of an implementer and independent verifiers that you describe yourself |
README in short
A comparison table shows where Looper sits next to the built-in `/goal`, `/loop` and `/schedule`: they execute, it designs. The healthy-loop section lists goal, context, actions, feedback, state and stop conditions. The example diagram walks through the plan, plan gate, delivery and delivery gate.
README badge
Original SKILL.md
--- name: looper description: > Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council. Use when the user wants to design, build, or set up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge loop, multi-model council, reviewer/judge gate, or /goal-style looping process. Start from a named pattern template (security-scan, code-review, bug-hunt, docs-sync, research-synthesis) or from a blank interview. Guide goal refinement, typed verification criteria, reviewer and judge selection, privacy boundaries, termination guards, no-progress stops, and lightweight observability, then emit a RUN_IN_SESSION.md handoff prompt plus portable loop.yaml, loop.resolved.json, LOOP.md, and run-loop.py. disable-model-invocation: true argument-hint: "[target-dir] [--template <name>]" allowed-tools: Read, Write, Bash --- # Looper Use Looper as a loop design coach and scaffolder. During design, interview, critique, validate, and write files. After emission, offer to run the loop in the current session using `RUN_IN_SESSION.md`; keep `run-loop.py` as the advanced external runner. ## Workflow 1. Resolve the target path and optional `--template <name>` from the `/looper` arguments. If no target is given, use `./looper-output`. If the target contains an existing `loop.yaml`, treat the task as an edit/resume instead of a fresh scaffold. If a template was requested, follow Template Mode below instead of the blank-slate interview in step 3. 2. Load the relevant rubric only when entering that stage: - Goal stage: `references/goal-rubric.md`. - Verification stage: `references/verification-rubric.md`. - Council stage: `references/council-rubric.md`. - Control stage: `references/control-rubric.md`. - Model detection or privacy details: `references/model-detection.md`. 3. Interview in seven stages: goal, verification, host model, council, gates/control, confirmation flow preview, emit/run option. In the control stage, cover execution boundary, isolation, no-progress signals, state, and run logging. 4. Critique each stage before accepting it. Prefer concrete alternatives over vague warnings. Push weak goals toward outcome, scope, context, and done state. Push weak verification toward programmatic checks first, then judge rubrics, then human signoff. 5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge returns a structured verdict. `revise_until_clean` must name a judge member or `human` as `verdict_source`. 6. Require multiple termination guards: `max_iterations`, a revision cap on each gate, a no-progress stop, and either a budget cap or an explicit human stop point. 7. Before any cross-vendor council member is selected, state what context will leave the user's machine, which CLI receives it, which redaction globs apply, and that both execution paths require first-send consent.