Skip to content
Back to search

looper

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ksimback-looper/badge.svg)](/listings/ksimback-looper)

HTML

<a href="/listings/ksimback-looper"><img src="/api/listings/ksimback-looper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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:

<details> <summary>Manual install commands</summary>

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://github.com/ksimback/looper "$HOME/.claude/skills/looper"
mkdir -p "$HOME/.claude/commands"
cp "$HOME/.claude/skills/looper/commands/looper.md" "$HOME/.claude/commands/looper.md"

</details>

Then, in Claude Code:

/looper

Looper interviews you, writes the artifacts into a folder called `looper-output`, and shows you an ASCII flow preview to confirm before anything is finalized. The installer also creates a private `.venv` inside the skill directory and installs `PyYAML`, which the helper compiler needs to read `loop.yaml`. It then offers to run the loop right there in the same Claude Code session.

If you want a different folder name, pass it after `/looper`, for example `/looper client-onboarding-loop`.

Start from a pattern template

Instead of a blank interview, start from a named, pre-designed loop:

/looper my-review --template code-review

| Template | Use when | |----------|----------| | `security-scan` | Read-only sweep of a repo for secrets, PII, and vulnerabilities → triaged `SECURITY-FINDINGS.md`. | | `code-review` | Review a branch's diff against its base → typed, severity-rated `REVIEW.md` grounded in the diff. | | `bug-hunt` | Reproduce a reported bug, fix the root cause, prove it with before/after repro evidence. | | `docs-sync` | Find and fix doc/code drift → per-item `DRIFT-REPORT.md`; docs follow code, code untouched. | | `research-synthesis` | Synthesize collected sources into a cited `REPORT.md`; every claim traceable to a file. |

Each template is a complete, compiler-validated `loop.yaml` with a handful of `{{PLACEHOLDER}}` slots; the wizard asks only for those, picks models from what's installed, and still runs its full critique, privacy, and preview flow before emitting. See [`templates/loops/`](templates/loops/) for the catalog and per-template docs — including how to add your own.

Lint any loop.yaml

The design rubrics also exist as a static checker — no wizard, no interview:

python scripts/looper.py lint path/to/loop.yaml

`lint` compiles the spec, then checks it for the anti-patterns the rubrics coach against: all-vibe verification (no programmatic checks), judge criteria a runner would never evaluate, undeclared cross-vendor egress, a judge that shares the host's model family, missing caps, and unresolved `{{PLACEHOLDER}}` tokens. **Errors** mean the spec won't behave the way it reads (exit 1); **warnings** are design coaching (exit 0, or exit 1 with `--strict`). A spec that doesn't compile exits 2 with the compile error on stderr — in that case `--json` emits nothing, so CI wrappers should check the exit code before parsing. Add `--json` for tooling, and wire `lint --strict` into CI to gate loop specs in PRs the same way you lint code.

Easy: run in the same session

The default path is to let Looper continue in the same conversation. It follows the generated `RUN_IN_SESSION.md` handoff, writes `plan.md`, `delivery-N.md`, `review-N.md`, `state.json`, and `run-log.md` into the loop workspace, and stops when the gates pass, a cap is reached, or repeated no-progress is detected.

Advanced: run outside the session

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 221 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: looper
  3. description: >
  4. Scaffold a well-designed agent loop with best-practice coaching and a
  5. cross-model review council. Use when the user wants to design, build, or set
  6. up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge
  7. loop, multi-model council, reviewer/judge gate, or /goal-style looping
  8. process. Start from a named pattern template (security-scan, code-review,
  9. bug-hunt, docs-sync, research-synthesis) or from a blank interview. Guide
  10. goal refinement, typed verification criteria, reviewer and judge selection,
  11. privacy boundaries, termination guards, no-progress stops, and lightweight
  12. observability, then emit a RUN_IN_SESSION.md handoff prompt plus portable
  13. loop.yaml, loop.resolved.json, LOOP.md, and run-loop.py.
  14. disable-model-invocation: true
  15. argument-hint: "[target-dir] [--template <name>]"
  16. allowed-tools: Read, Write, Bash
  17. ---
  18. # Looper
  19. Use Looper as a loop design coach and scaffolder. During design, interview,
  20. critique, validate, and write files. After emission, offer to run the loop in
  21. the current session using `RUN_IN_SESSION.md`; keep `run-loop.py` as the
  22. advanced external runner.
  23. ## Workflow
  24. 1. Resolve the target path and optional `--template <name>` from the
  25. `/looper` arguments. If no target is given, use `./looper-output`. If the
  26. target contains an existing `loop.yaml`, treat the task as an edit/resume
  27. instead of a fresh scaffold. If a template was requested, follow Template
  28. Mode below instead of the blank-slate interview in step 3.
  29. 2. Load the relevant rubric only when entering that stage:
  30. - Goal stage: `references/goal-rubric.md`.
  31. - Verification stage: `references/verification-rubric.md`.
  32. - Council stage: `references/council-rubric.md`.
  33. - Control stage: `references/control-rubric.md`.
  34. - Model detection or privacy details: `references/model-detection.md`.
  35. 3. Interview in seven stages: goal, verification, host model, council,
  36. gates/control, confirmation flow preview, emit/run option. In the control
  37. stage, cover execution boundary, isolation, no-progress signals, state, and
  38. run logging.
  39. 4. Critique each stage before accepting it. Prefer concrete alternatives over
  40. vague warnings. Push weak goals toward outcome, scope, context, and done
  41. state. Push weak verification toward programmatic checks first, then judge
  42. rubrics, then human signoff.
  43. 5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge
  44. returns a structured verdict. `revise_until_clean` must name a judge member
  45. or `human` as `verdict_source`.
  46. 6. Require multiple termination guards: `max_iterations`, a revision cap on
  47. each gate, a no-progress stop, and either a budget cap or an explicit human
  48. stop point.
  49. 7. Before any cross-vendor council member is selected, state what context will
  50. leave the user's machine, which CLI receives it, which redaction globs apply,
  51. and that both execution paths require first-send consent.
  52. 8. Show an ASCII flow preview of the planned loop and ask for confirmation
  53. before final emission. Optimize for Claude Code CLI readability.
  54. 9. Emit these files into the target:
  55. - `loop.yaml`
  56. - `loop.resolved.json`
  57. - `LOOP.md`
  58. - `RUN_IN_SESSION.md`
  59. - `run-loop.py`
  60. - `loop-workspace/`
  61. - `README.md`
  62. 10. After writing `loop.yaml`, resolve the helper Python (see Helper Python
  63. below) and run:
  64. `"$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`
  65. Then run
  66. `"$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml`
  67. and relay the findings: fix any `error[...]` before continuing (the spec
  68. would not behave as written), and surface `warning[...]` lines to the user
  69. as design coaching they may accept or address.
  70. 11. Ask whether the user wants to run the loop now in this session. If yes,
  71. follow `RUN_IN_SESSION.md` directly as the active task. If no, explain that
  72. the same file is the easy restart path and `run-loop.py` is available for
  73. advanced external execution.
  74. ## Template Mode
  75. The pattern library lives at `${CLAUDE_SKILL_DIR}/templates/loops/` — one
  76. directory per template containing a complete, compilable `loop.yaml` (with
  77. `{{PLACEHOLDER}}` tokens marking project-specific slots), a `README.md`
  78. (use-when, placeholder table, customization notes), and optionally
  79. `scripts/` with helper checkers. The catalog index is
  80. `templates/loops/README.md`.
  81. A template is a pre-answered interview, not a bypass of design review:
  82. 0. If the target directory already contains a `loop.yaml`, the edit/resume
  83. rule in step 1 wins: do **not** overwrite it with a template. Say the
  84. directory already has a loop and ask the user to pick an empty target or
  85. confirm they want it replaced before continuing.
  86. 1. If `--template` has no name, an unknown name, or the user asks what is
  87. available, show the catalog table (template + use-when) and let them pick.
  88. 2. Read the template's `loop.yaml` and `README.md`. Use the template as the
  89. seed instead of a blank spec.
  90. 3. Run a compressed interview in place of the seven blank-slate stages:
  91. ask for each `{{PLACEHOLDER}}` slot named in the template README, run
  92. the host-model stage against detected CLIs (`detect-models`) and swap
  93. `host` / `council` invocations to what is actually installed and authed,
  94. then confirm target and workspace paths.
  95. 4. Everything after the interview still applies unchanged: critique each
  96. pre-filled stage against its rubric (step 4), the structural rules
  97. (steps 5–8) including the cross-vendor egress statement, the ASCII flow
  98. preview, confirmation, emission, and compile.
  99. 5. Never emit while any `{{` token remains in `loop.yaml`. The compiler
  100. prints `looper: warning: unresolved template placeholders remain ...`
  101. for this case — treat that warning as a blocker, not advice.
  102. 6. At emission, copy the template's `scripts/` directory (when present)
  103. into `<target>/scripts/` alongside the standard emitted files, before
  104. running compile.
  105. ## File Rules
  106. - Write argv arrays, never shell command strings, for all model and check
  107. invocations.
  108. - Do not write API keys, access tokens, passwords, or CLI auth material into
  109. `loop.yaml`, `loop.resolved.json`, or model registries.
  110. - Default redaction globs are `.env`, `.env.*`, `secrets/**`, and `**/*.key`.
  111. - Keep `loop.yaml` human-readable and commented where useful. The emitted
  112. runner reads only `loop.resolved.json`.
  113. - Keep `RUN_IN_SESSION.md` as the default/easy execution handoff. It is meant
  114. for the current LLM session or a future pasted prompt.
  115. - Copy `templates/run-loop.py` exactly unless the user explicitly asks to edit
  116. the external runner contract.
  117. ## Helper Python
  118. The installer creates a private venv inside the skill directory. Its Python
  119. lives at `.venv/bin/python` on macOS/Linux and `.venv/Scripts/python.exe` on
  120. Windows. Shell state does not persist between commands, so prefix every helper
  121. invocation below with this resolution (works in POSIX shells and Git Bash on
  122. Windows):
  123. ```bash
  124. 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; }
  125. ```
  126. The final fallback executes the candidate rather than just locating it: on
  127. Windows, `python3` on PATH is often the Microsoft Store alias stub, which
  128. exists but cannot run scripts. If no candidate can execute `-c ""`, tell the
  129. user to rerun the Looper installer (it creates the venv).
  130. ## Helper Scripts
  131. Each command below assumes the Helper Python resolution is prefixed in the
  132. same shell invocation:
  133. - Detect model CLIs:
  134. `"$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py detect-models --write`
  135. - Register a custom CLI (quote the whole invocation if it contains flags):
  136. `"$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py register-model <id> --invoke "<cmd> [args...]"`
  137. - Compile and render:
  138. `"$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`
  139. - Lint against the design-rubric anti-patterns (add `--strict` to fail on warnings, `--json` for tooling):
  140. `"$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml`
  141. - Render only the in-session handoff:
  142. `"$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py session-prompt <target>/loop.resolved.json --out <target>/RUN_IN_SESSION.md`
  143. ## Confirmation Flow Preview
  144. Use this shape and customize labels:
  145. ```text
  146. +--------------------------------+
  147. | 1. Goal + context |
  148. | read sources |
  149. +--------------------------------+
  150. |
  151. v
  152. +--------------------------------+
  153. | 2. Draft plan.md |
  154. | state -> state.json |
  155. +--------------------------------+
  156. |
  157. v
  158. +--------------------------------+
  159. | 3. Plan gate |
  160. | verdict: reviewer-1 |
  161. +--------------------------------+
  162. | needs work -> revise <= 3 -> step 2
  163. | pass
  164. v
  165. +--------------------------------+
  166. | 4. Write delivery-N.md |
  167. | log -> run-log.md |
  168. +--------------------------------+
  169. |
  170. v
  171. +--------------------------------+
  172. | 5. Delivery gate |
  173. | verdict: reviewer-1 |
  174. +--------------------------------+
  175. | needs work -> revise <= 3 -> step 4
  176. | pass
  177. v
  178. +--------------------------------+
  179. | 6. Final output |
  180. | all gates clean |
  181. +--------------------------------+
  182. Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens
  183. ```
  184. ## Emit Checklist
  185. - The goal has a clear outcome, scope boundary, context sources, and done state.
  186. - Verification criteria are typed as `programmatic`, `judge`, or `human`.
  187. - At least one criterion is not purely vibe-based unless the user explicitly
  188. accepts that risk.
  189. - Each `revise_until_clean` gate has a valid `verdict_source`.
  190. - Every external invocation is an argv array with a timeout.
  191. - Cross-vendor egress is scoped, redacted, and consent-gated.
  192. - `loop_control` has iteration, revision, no-progress, and wall-clock or budget
  193. caps.
  194. - Execution boundary and isolation are explicit, even when the choice is the
  195. current workspace.
  196. - Observability names a `run-log.md` and `state.json` path.
  197. - `loop.resolved.json`, `LOOP.md`, and `RUN_IN_SESSION.md` compile
  198. successfully before handoff.
README.md · README · 327 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <pre>
  3. _ ___ ___ ____ _____ ____
  4. | | / _ \ / _ \| _ \| ____| _ \
  5. | | | | | | | | | |_) | _| | |_) |
  6. | |___ | |_| | |_| | __/| |___| _ <
  7. |_____| \___/ \___/|_| |_____|_| \_\
  8. </pre>
  9. <p>
  10. <strong>Design agent loops before you run them.</strong><br>
  11. Goal -> Plan -> Review -> Deliver -> Judge -> Stop clean.
  12. </p>
  13. <p>
  14. <a href="#quick-start">Quick start</a> |
  15. <a href="#example-loop-diagram">Example loop</a> |
  16. <a href="#how-it-works">How it works</a>
  17. </p>
  18. </div>
  19. ## Example loop diagram
  20. Looper turns a fuzzy automation idea into a reviewable loop shape before any
  21. runner starts changing files. This example comes from
  22. [`examples/ai-workflow-mapping`](examples/ai-workflow-mapping/loop.yaml).
  23. ```mermaid
  24. flowchart TD
  25. G["Goal + context<br/>process notes + definition of done"] --> P["Draft plan.md<br/>host: codex / gpt-5"]
  26. P --> PG{"Plan gate<br/>judge: reviewer-1"}
  27. PG -- "revise <= 3" --> P
  28. PG -- "pass" --> D["Write delivery-N.md<br/>map the workflow"]
  29. D --> DG{"Delivery gate<br/>programmatic check + judge"}
  30. DG -- "revise <= 3" --> D
  31. DG -- "pass" --> F["Final output<br/>all gates clean"]
  32. S["State + log<br/>state.json + run-log.md"] -. "records" .-> P
  33. S -. "records" .-> D
  34. Stop["Stop guards<br/>max 12 iterations<br/>no progress x2<br/>budget caps"] -. "watch" .-> PG
  35. Stop -. "watch" .-> DG
  36. ```
  37. **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.
  38. 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.
  39. Maintainer: Kevin Simback · GitHub [@ksimback](https://github.com/ksimback) · X [@ksimback](https://x.com/ksimback)
  40. License: MIT
  41. ---
  42. ## Where Looper fits among Claude Code's loops
  43. 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.
  44. Concretely, what each loop type asks you to hand off is exactly what Looper coaches and hardens:
  45. - **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.
  46. - **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).
  47. - **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.
  48. - **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.
  49. ### What `/goal` actually does
  50. `/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.
  51. That's genuinely useful for persistence. But three things are missing for serious work:
  52. - **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.
  53. - **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.
  54. - **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.
  55. ### What `/loop` and `/schedule` actually do
  56. `/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.
  57. 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.
  58. ### Side by side
  59. 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.
  60. | | `/goal` | `/loop` / `/schedule` | **Looper** |
  61. | :-- | :-- | :-- | :-- |
  62. | Layer | execution (in-session) | execution (scheduling, local / cloud) | **design (pre-flight)** |
  63. | You hand off | the stop condition | the trigger | **the design, checked before anything runs** |
  64. | Coaches your goal | no | no | **yes** |
  65. | Typed, checkable verification | no | no | **yes (programmatic / judge / human)** |
  66. | Reviewer model | built-in evaluator, same vendor | none | **a different model family, by default** |
  67. | Explicit review gates | implicit | none | **plan gate + delivery gate** |
  68. | Termination guards | goal-condition only | interval / until | **iteration + revision + no-progress + budget caps** |
  69. | Portable, versionable artifact | no | the cron job / routine | **`loop.yaml` + resolved spec** |
  70. | Static design checks | no | no | **`looper lint` (CI-friendly)** |
  71. | Runs the loop | **yes** | **yes** | **yes, by handing the current session a runnable prompt; Python runner optional** |
  72. 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.
  73. > 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.
  74. ---
  75. ## What Looper provides
  76. Looper provides loop design discipline: a clear goal, context sources,
  77. checkable verification, reviewer/judge gates, termination guards, a portable
  78. spec, a same-session execution handoff, and lightweight run state/log files.
  79. Looper does **not** provide durable orchestration. It does not schedule cron
  80. jobs for you, persist step-level retries across process restarts, manage
  81. sub-agent lifecycles, enforce concurrency controls, or store a production run
  82. history. If you need those guarantees, use Looper to design the loop and hand
  83. the resulting spec to an orchestrator built for durable execution.
  84. ## Healthy loop checklist
  85. Before running a loop, Looper pushes you to make these explicit:
  86. - **Goal**: what outcome the loop is trying to produce.
  87. - **Context**: which files, commands, issues, or external sources the loop may
  88. inspect.
  89. - **Actions**: which model, tools, commands, or human handoffs may change state.
  90. - **Feedback**: which programmatic checks, judges, reviewers, or humans decide
  91. whether work is good enough.
  92. - **State**: where the loop records status, decisions, blockers, and outputs.
  93. - **Stop conditions**: success, max iterations, revision caps, no-progress
  94. signals, and budget caps. The external runner enforces wall-clock caps;
  95. token/USD caps are operator-visible advisory limits unless you add accounting
  96. around the configured CLIs.
  97. - **Execution boundary**: current workspace, branch/worktree, external runner,
  98. or a separate durable orchestrator.
  99. ---
  100. ## Quick start
  101. Install as a global personal skill and slash command.
  102. On Windows PowerShell:
  103. ```powershell
  104. irm https://raw.githubusercontent.com/ksimback/looper/main/install.ps1 | iex
  105. ```
  106. On macOS/Linux:
  107. ```bash
  108. curl -fsSL https://raw.githubusercontent.com/ksimback/looper/main/install.sh | bash
  109. ```
  110. If you prefer to inspect each step, use the manual install:
  111. <details>
  112. <summary>Manual install commands</summary>
  113. Windows PowerShell:
  114. ```powershell
  115. git clone https://github.com/ksimback/looper "$env:USERPROFILE\.claude\skills\looper"
  116. New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands" | Out-Null
  117. Copy-Item "$env:USERPROFILE\.claude\skills\looper\commands\looper.md" "$env:USERPROFILE\.claude\commands\looper.md" -Force
  118. ```
  119. macOS/Linux:
  120. ```bash
  121. git clone https://github.com/ksimback/looper "$HOME/.claude/skills/looper"
  122. mkdir -p "$HOME/.claude/commands"
  123. cp "$HOME/.claude/skills/looper/commands/looper.md" "$HOME/.claude/commands/looper.md"
  124. ```
  125. </details>
  126. Then, in Claude Code:
  127. ```text
  128. /looper
  129. ```
  130. Looper interviews you, writes the artifacts into a folder called `looper-output`,
  131. and shows you an ASCII flow preview to confirm before anything is finalized. The
  132. installer also creates a private `.venv` inside the skill directory and installs
  133. `PyYAML`, which the helper compiler needs to read `loop.yaml`. It
  134. then offers to run the loop right there in the same Claude Code session.
  135. If you want a different folder name, pass it after `/looper`, for example
  136. `/looper client-onboarding-loop`.
  137. ### Start from a pattern template
  138. Instead of a blank interview, start from a named, pre-designed loop:
  139. ```text
  140. /looper my-review --template code-review
  141. ```
  142. | Template | Use when |
  143. |----------|----------|
  144. | `security-scan` | Read-only sweep of a repo for secrets, PII, and vulnerabilities → triaged `SECURITY-FINDINGS.md`. |
  145. | `code-review` | Review a branch's diff against its base → typed, severity-rated `REVIEW.md` grounded in the diff. |
  146. | `bug-hunt` | Reproduce a reported bug, fix the root cause, prove it with before/after repro evidence. |
  147. | `docs-sync` | Find and fix doc/code drift → per-item `DRIFT-REPORT.md`; docs follow code, code untouched. |
  148. | `research-synthesis` | Synthesize collected sources into a cited `REPORT.md`; every claim traceable to a file. |
  149. Each template is a complete, compiler-validated `loop.yaml` with a handful of
  150. `{{PLACEHOLDER}}` slots; the wizard asks only for those, picks models from
  151. what's installed, and still runs its full critique, privacy, and preview flow
  152. before emitting. See [`templates/loops/`](templates/loops/) for the catalog
  153. and per-template docs — including how to add your own.
  154. ### Lint any loop.yaml
  155. The design rubrics also exist as a static checker — no wizard, no interview:
  156. ```bash
  157. python scripts/looper.py lint path/to/loop.yaml
  158. ```
  159. `lint` compiles the spec, then checks it for the anti-patterns the rubrics
  160. coach against: all-vibe verification (no programmatic checks), judge criteria
  161. a runner would never evaluate, undeclared cross-vendor egress, a judge that
  162. shares the host's model family, missing caps, and unresolved `{{PLACEHOLDER}}`
  163. tokens. **Errors** mean the spec won't behave the way it reads (exit 1);
  164. **warnings** are design coaching (exit 0, or exit 1 with `--strict`). A spec
  165. that doesn't compile exits 2 with the compile error on stderr — in that case
  166. `--json` emits nothing, so CI wrappers should check the exit code before
  167. parsing. Add `--json` for tooling, and wire `lint --strict` into CI to gate
  168. loop specs in PRs the same way you lint code.
  169. ### Easy: run in the same session
  170. The default path is to let Looper continue in the same conversation. It follows
  171. the generated `RUN_IN_SESSION.md` handoff, writes `plan.md`,
  172. `delivery-N.md`, `review-N.md`, `state.json`, and `run-log.md` into the loop
  173. workspace, and stops when the gates pass, a cap is reached, or repeated
  174. no-progress is detected.
  175. ### Advanced: run outside the session
  176. Use the Python runner when you want to run the loop later, repeatably, from
  177. another terminal, or outside the LLM session:
  178. ```bash
  179. python3 ./looper-output/run-loop.py
  180. ```
  181. ### Building your own runner
  182. `loop.resolved.json` is an interchange format, not just this repo's internal
  183. detail — a Looper spec can be executed by runners other than the bundled
  184. `run-loop.py` (other languages, other host platforms, other agent stacks).
  185. [`RUNNER-CONTRACT.md`](RUNNER-CONTRACT.md) is the normative contract: what a
  186. runner MUST do about gates, caps, consent, redaction, state, and exit codes.
  187. Prove a runner honors it with the conformance suite:
  188. ```bash
  189. python conformance/check_runner.py path/to/your-runner
  190. ```
  191. Ten scenarios, deterministic fixtures, no real model CLIs needed. The
  192. reference runner is held to the same suite in CI.
  193. For local development, this repository root is the skill root. Edit and test it
  194. here, then install or update the global skill by cloning or copying the repo to
  195. `$HOME/.claude/skills/looper` and copying `commands/looper.md` to
  196. `$HOME/.claude/commands/looper.md`.
  197. If Claude Code says `Unknown command: /looper`, check both install locations:
  198. - The skill must exist at your real home directory, for example
  199. `C:\Users\<you>\.claude\skills\looper` on Windows.
  200. - The slash command must exist at `C:\Users\<you>\.claude\commands\looper.md`
  201. on Windows.
  202. - If you see a literal folder named `~` inside your project, your shell did not
  203. expand `~`; rerun the installer or manual PowerShell commands above.
  204. ### What Looper writes on your machine
  205. Looper is transparent about its footprint. Outside of the loop folders you ask
  206. it to scaffold, it touches exactly four locations:
  207. - `~/.claude/skills/looper` — the skill itself (a git checkout).
  208. - `~/.claude/commands/looper.md` — the `/looper` slash command.
  209. - `~/.claude/skills/looper/.venv` — a private venv with PyYAML for the helper
  210. compiler.
  211. - `~/.looper/models.json` — the model registry written by `detect-models` /
  212. `register-model`. It stores invocation metadata only (command names and
  213. argv arrays), never API keys or other credentials; auth stays in each CLI's
  214. own config or keychain.
  215. ### Uninstall
  216. Windows PowerShell:
  217. ```powershell
  218. Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\skills\looper"
  219. Remove-Item -Force "$env:USERPROFILE\.claude\commands\looper.md"
  220. Remove-Item -Recurse -Force "$env:USERPROFILE\.looper" # optional: model registry
  221. ```
  222. macOS/Linux:
  223. ```bash
  224. rm -rf "$HOME/.claude/skills/looper"
  225. rm -f "$HOME/.claude/commands/looper.md"
  226. rm -rf "$HOME/.looper" # optional: model registry
  227. ```
  228. ---
  229. ## How it works
  230. 1. **Goal** — you state it; Looper critiques and tightens it.
  231. 2. **Verification** — Looper forces checkable criteria, classified as programmatic (a command returns pass/fail), judge (a model scores a rubric), or human (you sign off).
  232. 3. **Host model** — pick the model that drives the loop.
  233. 4. **Council** — add a reviewer (notes) or judge (verdict); Looper recommends a *different* model family than the host and explains why.
  234. 5. **Gates & control** — confirm where review happens, revision and iteration caps, no-progress signals, budget limits, human checkpoints, and execution boundaries. Looper won't emit a loop with no termination guard.
  235. 6. **Confirm** — review the loop as an ASCII flow preview.
  236. 7. **Run or emit** — Looper writes `RUN_IN_SESSION.md`, `loop.yaml`, `loop.resolved.json`, `run-loop.py`, an empty workspace, and a README. The default is to offer to run the loop in the current session; the Python runner is there for external control.
  237. A council sends your project context to another model's CLI. Looper makes that explicit, lets you scope what's sent, and asks for consent before the first cross-vendor send — with any caught leak warning shown before the consent question. Redaction is two layers: files matching the redaction globs are **never read into prompts** (context sources show a `[redacted]` marker instead), and content from those files that re-surfaces anywhere else — a context command that printed it, an artifact a model copied it into — is scrubbed before **every** send, host included, with the catch logged in `run-log.md` and surfaced in `state.json` warnings. The second layer is best-effort and errs toward over-redaction: reformatted content or very short values can survive, a flagged-file line that legitimately appears elsewhere gets masked too, and a flagged file the scrub cannot read (over 1MB, non-UTF-8) is reported as a blind spot rather than silently skipped. Flagged means flagged for every recipient — if the loop genuinely needs a file's content, don't match it with a redaction glob. When redaction-sensitive paths exist, a local model (e.g. via `ollama`) remains the strongest option.
  238. ## License
  239. MIT © Kevin Simback

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.