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 ]" 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.
8. Show an ASCII flow preview of the planned loop and ask for confirmation before final emission. Optimize for Claude Code CLI readability.
9. Emit these files into the target:
   • loop.yaml
   • loop.resolved.json
   • LOOP.md
   • RUN_IN_SESSION.md
   • run-loop.py
   • loop-workspace/
   • README.md
10. After writing loop.yaml, resolve the helper Python (see Helper Python below) and run: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md Then run "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml and relay the findings: fix any error[...] before continuing (the spec would not behave as written), and surface warning[...] lines to the user as design coaching they may accept or address.
11. Ask whether the user wants to run the loop now in this session. If yes, follow RUN_IN_SESSION.md directly as the active task. If no, explain that the same file is the easy restart path and run-loop.py is available for advanced external execution.

Template Mode

The pattern library lives at ${CLAUDE_SKILL_DIR}/templates/loops/ — one directory per template containing a complete, compilable loop.yaml (with {{PLACEHOLDER}} tokens marking project-specific slots), a README.md (use-when, placeholder table, customization notes), and optionally scripts/ with helper checkers. The catalog index is templates/loops/README.md.

A template is a pre-answered interview, not a bypass of design review:

0. If the target directory already contains a loop.yaml, the edit/resume rule in step 1 wins: do not overwrite it with a template. Say the directory already has a loop and ask the user to pick an empty target or confirm they want it replaced before continuing.
1. If --template has no name, an unknown name, or the user asks what is available, show the catalog table (template + use-when) and let them pick.
2. Read the template's loop.yaml and README.md. Use the template as the seed instead of a blank spec.
3. Run a compressed interview in place of the seven blank-slate stages: ask for each {{PLACEHOLDER}} slot named in the template README, run the host-model stage against detected CLIs (detect-models) and swap host / council invocations to what is actually installed and authed, then confirm target and workspace paths.
4. Everything after the interview still applies unchanged: critique each pre-filled stage against its rubric (step 4), the structural rules (steps 5–8) including the cross-vendor egress statement, the ASCII flow preview, confirmation, emission, and compile.
5. Never emit while any {{ token remains in loop.yaml. The compiler prints looper: warning: unresolved template placeholders remain ... for this case — treat that warning as a blocker, not advice.
6. At emission, copy the template's scripts/ directory (when present) into <target>/scripts/ alongside the standard emitted files, before running compile.

File Rules

• Write argv arrays, never shell command strings, for all model and check invocations.
• Do not write API keys, access tokens, passwords, or CLI auth material into loop.yaml, loop.resolved.json, or model registries.
• Default redaction globs are .env, .env.*, secrets/**, and **/*.key.
• Keep loop.yaml human-readable and commented where useful. The emitted runner reads only loop.resolved.json.
• Keep RUN_IN_SESSION.md as the default/easy execution handoff. It is meant for the current LLM session or a future pasted prompt.
• Copy templates/run-loop.py exactly unless the user explicitly asks to edit the external runner contract.

Helper Python

The installer creates a private venv inside the skill directory. Its Python lives at .venv/bin/python on macOS/Linux and .venv/Scripts/python.exe on Windows. Shell state does not persist between commands, so prefix every helper invocation below with this resolution (works in POSIX shells and Git Bash on Windows):

LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/bin/python"; [ -x "$LOOPER_PYTHON" ] || LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/Scripts/python.exe"; [ -x "$LOOPER_PYTHON" ] || { LOOPER_PYTHON=python3; "$LOOPER_PYTHON" -c "" >/dev/null 2>&1 || LOOPER_PYTHON=python; }

The final fallback executes the candidate rather than just locating it: on Windows, python3 on PATH is often the Microsoft Store alias stub, which exists but cannot run scripts. If no candidate can execute -c "", tell the user to rerun the Looper installer (it creates the venv).

Helper Scripts

Each command below assumes the Helper Python resolution is prefixed in the same shell invocation:

• Detect model CLIs: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py detect-models --write
• Register a custom CLI (quote the whole invocation if it contains flags): "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py register-model <id> --invoke "<cmd> [args...]"
• Compile and render: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md
• Lint against the design-rubric anti-patterns (add --strict to fail on warnings, --json for tooling): "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml
• Render only the in-session handoff: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py session-prompt <target>/loop.resolved.json --out <target>/RUN_IN_SESSION.md

Confirmation Flow Preview

Use this shape and customize labels:

+--------------------------------+
| 1. Goal + context              |
| read sources                   |
+--------------------------------+
               |
               v
+--------------------------------+
| 2. Draft plan.md               |
| state -> state.json            |
+--------------------------------+
               |
               v
+--------------------------------+
| 3. Plan gate                   |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 2
               | pass
               v
+--------------------------------+
| 4. Write delivery-N.md         |
| log -> run-log.md              |
+--------------------------------+
               |
               v
+--------------------------------+
| 5. Delivery gate               |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 4
               | pass
               v
+--------------------------------+
| 6. Final output                |
| all gates clean                |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens

Emit Checklist

• The goal has a clear outcome, scope boundary, context sources, and done state.
• Verification criteria are typed as programmatic, judge, or human.
• At least one criterion is not purely vibe-based unless the user explicitly accepts that risk.
• Each revise_until_clean gate has a valid verdict_source.
• Every external invocation is an argv array with a timeout.
• Cross-vendor egress is scoped, redacted, and consent-gated.
• loop_control has iteration, revision, no-progress, and wall-clock or budget caps.
• Execution boundary and isolation are explicit, even when the choice is the current workspace.
• Observability names a run-log.md and state.json path.
• loop.resolved.json, LOOP.md, and RUN_IN_SESSION.md compile successfully before handoff.

Example loop diagram

Looper turns a fuzzy automation idea into a reviewable loop shape before any runner starts changing files. This example comes from examples/ai-workflow-mapping.

flowchart TD
    G["Goal + context<br/>process notes + definition of done"] --> P["Draft plan.md<br/>host: codex / gpt-5"]
    P --> PG{"Plan gate<br/>judge: reviewer-1"}
    PG -- "revise <= 3" --> P
    PG -- "pass" --> D["Write delivery-N.md<br/>map the workflow"]
    D --> DG{"Delivery gate<br/>programmatic check + judge"}
    DG -- "revise <= 3" --> D
    DG -- "pass" --> F["Final output<br/>all gates clean"]

    S["State + log<br/>state.json + run-log.md"] -. "records" .-> P
    S -. "records" .-> D
    Stop["Stop guards<br/>max 12 iterations<br/>no progress x2<br/>budget caps"] -. "watch" .-> PG
    Stop -. "watch" .-> DG

A loop design coach for Claude Code. Looper is a skill that helps you design a good agent loop — a sharp goal, checkable verification, and a second model in the review seat — then lets you run it in the same session or save it as a portable spec. It is a design layer first: it writes files and hands the current session a clear execution prompt.

Invoke it with /looper. It interviews you, critiques your design against built-in best-practice rubrics, lets you wire in a cross-model reviewer or judge (including non-Claude models), shows you the loop as a terminal-friendly ASCII flow preview, and writes out 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, plus an empty loop-workspace/ and a README for the loop.

Maintainer: Kevin Simback · GitHub @ksimback · X @ksimback License: MIT

Where Looper fits among Claude Code's loops

The Claude Code team's own taxonomy ("Getting started with loops") sorts loops by what you hand off: turn-based loops hand off the check (verification skills), goal-based loops hand off the stop condition (/goal), time-based loops hand off the trigger (/loop, /schedule), and proactive loops hand off the whole prompt (routines composing all of the above). Every one of those primitives runs a loop. Looper is the layer in front of them: it helps you design a loop that's worth running, then emits a spec any of the four can execute.

Concretely, what each loop type asks you to hand off is exactly what Looper coaches and hardens:

• Turn-based — the check you'd encode as a verification skill is Looper's typed verification block: programmatic first, judge rubric second, human signoff last.
• Goal-based — /goal's stop condition is Looper's definition_of_done plus gates; the difference is who judges it (a model family you chose, against a typed rubric) and what surrounds it (revision caps, no-progress stalls, budget guards).
• Time-based — /loop and /schedule re-fire whatever you give them; give them a loop that already passed compile and lint, and each firing follows RUN_IN_SESSION.md or run-loop.py instead of an ad-hoc prompt.
• Proactive — a routine is only as good as the prompt it repeats; the compiled loop.resolved.json is a versionable, reviewable artifact you can hand to a routine and audit later.

What /goal actually does

/goal sets a persistent objective for the session. Once set, Claude keeps it as a reference point, checks after each significant action whether the current state satisfies the goal, and keeps working until it does — so it doesn't stop and ask after every step.

That's genuinely useful for persistence. But three things are missing for serious work:

• No coaching. /goal takes whatever goal you type, however vague. It won't tell you the goal is unfalsifiable or that "done" was never defined. Garbage goal in, confidently-wrong loop out.
• Single-vendor evaluation. The stop condition is checked by an evaluator model, but it's the same vendor in the same pipeline — not a model family you chose for blind-spot coverage, and there's no typed rubric behind the verdict. A review council exists precisely to put a different set of eyes, with explicit criteria, on the work.
• No structure to inspect or reuse. The goal lives in the session, not as a portable, versionable artifact. There's no typed verification, no explicit gates, no second model.

What /loop and /schedule actually do

/loop is a scheduler. You give it an interval and a task; it re-fires the prompt or skill on that cadence — polling CI, watching a deploy, monitoring a background job. (Omit the interval and it self-paces.) /schedule is the same hand-off moved to the cloud: a routine that keeps firing when your machine is off.

They're the right tool for "run this thing every five minutes until I say stop." Neither is a loop designer: they don't help you decide what runs, define success criteria, or bring in a reviewer. They schedule; they don't critique.

Side by side

Looper is the design layer that sits in front of all of them. It produces a well-specified loop — coached goal, typed verification, a cross-model gate — then gives you a default in-session handoff prompt plus a portable spec. The same design can be run immediately in the conversation, driven by /goal for persistence, fired on a schedule by /loop or /schedule, or run later with Python. Looper doesn't replace them; it gives them something good to run.

The honest summary: if you already know your loop is well-designed and you just need it to persist or to fire on a schedule, /goal, /loop, and /schedule are the right reach. Looper exists for the part those don't touch — making sure the loop is worth persisting before you hand it off, and making sure something other than the author is checking the work.

Sources for the behavior described above: the Claude Code team's "Getting started with loops" guide and the skills/commands documentation at code.claude.com/docs. Behavior and version gates change frequently; verify against upstream before shipping.

What Looper provides

Looper provides loop design discipline: a clear goal, context sources, checkable verification, reviewer/judge gates, termination guards, a portable spec, a same-session execution handoff, and lightweight run state/log files.

Looper does not provide durable orchestration. It does not schedule cron jobs for you, persist step-level retries across process restarts, manage sub-agent lifecycles, enforce concurrency controls, or store a production run history. If you need those guarantees, use Looper to design the loop and hand the resulting spec to an orchestrator built for durable execution.

Healthy loop checklist

Before running a loop, Looper pushes you to make these explicit:

• Goal: what outcome the loop is trying to produce.
• Context: which files, commands, issues, or external sources the loop may inspect.
• Actions: which model, tools, commands, or human handoffs may change state.
• Feedback: which programmatic checks, judges, reviewers, or humans decide whether work is good enough.
• State: where the loop records status, decisions, blockers, and outputs.
• Stop conditions: success, max iterations, revision caps, no-progress signals, and budget caps. The external runner enforces wall-clock caps; token/USD caps are operator-visible advisory limits unless you add accounting around the configured CLIs.
• Execution boundary: current workspace, branch/worktree, external runner, or a separate durable orchestrator.

Quick start

Install as a global personal skill and slash command.

On Windows PowerShell:

irm https://raw.githubusercontent.com/ksimback/looper/main/install.ps1 | iex

On macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/ksimback/looper/main/install.sh | bash

If you prefer to inspect each step, use the manual install:

Windows PowerShell:

git clone https://github.com/ksimback/looper "$env:USERPROFILE\.claude\skills\looper"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands" | Out-Null
Copy-Item "$env:USERPROFILE\.claude\skills\looper\commands\looper.md" "$env:USERPROFILE\.claude\commands\looper.md" -Force

macOS/Linux:

git clone https://