Skip to main content
skill CX Codex

loop · sethgammon — skill for Claude Code and Codex: retry until pass

loop — a skill for Claude Code and Codex that runs an action repeatedly and checks the result each time, stopping when verification passes or attempts run out. Useful for fixing lint errors or test failures in an active session.

MIT ★ 937 updated 2026-11-05

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What loop does

Loop creates a repetition contract with an explicit attempt limit and success check. Each attempt is recorded in .planning/loops/ with the action, result, and stop reason. It works on Claude Code and Codex.

To start a loop, you must provide an explicit verifier—a command that confirms success, such as npm run lint or npm run test. Without one, the skill asks you to specify it and does not execute the action. The attempt limit is declared explicitly: --max 3 means exactly three attempts, no more.

The loop stops when the verifier passes, attempts are exhausted, the action fails, or human review is needed. Every run saves evidence: the contract with action, verifier, results, and the stop reason.

What it helps with

  • retry a code check multiple times until lint passes
  • repeat tests up to a limit without manual intervention
  • fix errors in a cycle during one session
  • track and record each attempt for inspection

Example prompts for the agent

  • Retry the check up to 5 times with verifier npm run lint
  • Run loop: action is fix syntax, verifier is npm run test, max 3 attempts
  • /loop run "npm run format" --verify "npm run lint" --max 4

How to install loop

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill loop -a claude-code

3Manually: put the files in place

~/.claude/skills/loop/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/loop/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about loop

How do I install loop in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local and npx skills add SethGammon/Citadel --skill loop -a claude-code. The skill appears in ~/.claude/skills/loop/SKILL.md.

What does loop do?

It runs an action (such as fixing errors) and checks the result with a command you specify. It repeats until the verifier passes or attempts run out. All results are saved to .planning/loops/.

Why does loop require an explicit verifier?

Without a concrete verification command, loop cannot decide when to stop. Words like "until it works" are not commands. Specify exactly: --verify "npm run test" or --verify "npm run lint".

Source text

SKILL.md · MIT
---
name: loop
license: MIT
description: >-
  Bounded foreground repetition for the current session. Creates a loop
  contract, runs or coordinates an action plus verifier up to a declared attempt
  limit, and records evidence under .planning/loops/. Use for repeat-until-pass
  work that is too small for daemon and not time-based scheduling.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - loop
  - repeat until
  - until tests pass
  - until lint passes
  - max attempts
  - retry until
last-updated: 2026-11-04
---

# /loop -- Bounded Foreground Loop

## Orientation

**Use when:** the user wants a visible repeat-until-pass cycle inside the
current session, such as "loop until lint passes" or "try this up to three
times and stop if tests still fail."

**Don't use when:** the work should run unattended across sessions (`/daemon`),
on a clock (`/schedule`), on file changes (`/watch`), or as a metric-driven
optimization experiment (`/experiment`).

In Claude Code, invoke `/citadel:loop` to select this skill explicitly.
The host also has a timer-based `/loop` command with different semantics.

## Commands

| Command | Behavior |
|---|---|
| `/loop status` | Show all known Citadel loops with active/stopped grouping. |
| `/loop inspect {id}` | Show one loop's contract, verifier, budget, runs, and stop reason. |
| `/loop templates` | List built-in loop templates. |
| `/loop plan --template {name}` | Create a loop contract from a template. |
| `/loop run "{action}" --verify "{command}" --max {N}` | Run a bounded foreground loop. |
| `/loop stop {id}` | Mark a loop stopped. |

## Protocol

### Step 1: Classify the loop

Determine which kind of loop the user requested:

| User intent | Route |
|---|---|
| Repeat within this active session | `/loop` |
| Continue campaign across sessions | `/daemon` |
| Run on a schedule | `/schedule` |
| Watch PR checks/reviews | `/pr-watch` |
| Watch files or marker comments | `/watch` |
| Optimize a numeric metric | `/experiment` |

If another route is clearly better, say so and route there.

### Step 2: Require a verifier

A `/loop run` must have an explicit verifier. Explicit means the user supplied
`--verify "<command>"` or an equally concrete verifier command in plain language.
Do not infer a verifier from words like "lint", "test", "until it works", or
"fix until passing." If the verifier is missing, ask for it before executing and
do not run `loop-runner.js`, shell commands, or manual repair steps.

Accept examples like:

```text
--verify "npm run lint"
--verify "npm run test"
--verify "node scripts/operating-proof.js --write"
```

If missing, respond in this shape:

```text
/loop needs an explicit verifier before it can run. Please provide one, for example:
--verify "npm run lint"

I will not run the loop until the verifier is explicit.
```

### Step 3: Create the contract

For status, inspect, templates, and stop commands, run:

```bash
node .citadel/scripts/loops.js <command>
```

For template planning:

```bash
node .citadel/scripts/loops.js plan --template <name> --write
```

For foreground execution:

```bash
node .citadel/scripts/loop-runner.js --action "<action>" --verify "<verifier>" --max-attempts <N> --write
```

If `.citadel/scripts/` is not present and this is the Citadel harness repo
itself, use `node scripts/loops.js` or `node scripts/loop-runner.js` instead.

The runner writes a contract under `.planning/loops/{id}.json`, appends each
attempt, and stops with a shared stop status.

Loop commands run in a shell, so each exact action and verifier command must
be approved for the project first. If the runner fails with
`LOOP_COMMAND_NOT_APPROVED`, nothing ran. Stop and show the user the
`approve-command.js approve loop ...` lines from the error; they must run those
themselves in an interactive terminal. Do not retry, rewrite the command to
dodge the check, or try to approve it yourself.

### Step 4: Stop on the first terminal condition

Stop when any of these are true:

- verifier passes
- attempt limit is reached
- the action fails in a way that needs human review
- the requested action would cross a safety or approval boundary
- the user asks to stop

Never silently continue beyond the declared attempt limit.

### Step 5: Report the outcome

Summarize:

- loop id
- status
- attempts used
- verifier
- runner command, including `--verify` and `--max-attempts`
- state path
- next action if stopped before success

## Fringe Cases

**If `.planning/` does not exist:** create `.planning/loops/` before writing
loop state. If writing fails, output the contract inline and tell the user
setup is needed.

**No verifier:** ask for one. Do not infer a destructive or expensive verifier.

**Action is an agent command, not a shell command:** run the action manually as
the agent for each attempt, then record the loop with `node scripts/loops.js
register` or use the loop contract as the state artifact. Do not pass slash
commands to the shell runner.

**Verifier keeps failing with the same cause:** stop at the attempt limit and
report `attempt-limit` with the latest evidence.

**User asks for unattended looping:** route to `/daemon` or `/schedule`, not
`/loop`.

## Contextual Gates

**Disclosure:** "Running foreground loop: action `{action}`, verifier
`{verifier}`, max attempts `{N}`."

**Reversibility:** amber -- the loop may run user-provided shell commands and
modify files; inspect the diff or loop-owned artifacts to revert.

**Trust gates:**
- Any: require verifier and attempt cap.
- Familiar: may execute shell action/verifier after disclosing the contract.
- Risky commands: require normal tool approval boundaries before running.

## Quality Gates

- A loop contract exists under `.planning/loops/` unless the filesystem blocks it.
- The verifier is explicit.
- The attempt limit is explicit and >= 1.
- The final status uses the shared loop vocabulary from `docs/LOOP_CONTRACT.md`.
- The final answer includes the loop id and state path.

## Exit Protocol

```
---HANDOFF---
- Loop: {id}
- Status: {status}
- Attempts: {used}/{max}
- Verifier: {command}
- Runner: node .citadel/scripts/loop-runner.js --action "{action}" --verify "{command}" --max-attempts {max} --write
- State: .planning/loops/{id}.json
- Next: {next action or "none"}
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

loop by other authors comes first.

loop Alireza Rezvani Starts a recurring autoresearch experiment loop on a schedule you pick. Intervals go from 10 minutes to monthly, and each iteration reads config, edits code, commits, and evaluates. CX Codex +1 1,557installs loop ZaxbyHub The loop skill takes a task through planning, implementation, review, and improvement while keeping run state on disk. Use it for gated, repeatable work toward a defined objective. CX Codex +1 ★ 539repo stars pua-loop tanweai Loads the pua-loop protocol for cyclic code verification. Invoked with $pua-loop. CX Codex +1 1,800installs install-loop Cobus Greyling install-loop is a Claude Code skill that sets up Loop Engineering in a project through one CLI entry point. It selects a loop pattern for the task and keeps the first week report-only. CX Codex +1 ★ 11,819repo stars ralph-loop official Anthropic ralph-loop runs an iterative task loop in Claude Code, returning the original prompt to the agent whenever it attempts to exit. CX Codex +1 ★ 47,914repo stars loop-verifier Cobus Greyling loop-verifier — a checker skill for the fix loop: it runs the project's tests, confirms the diff matches the task, and returns APPROVE, REJECT or ESCALATE_HUMAN. CX Codex +1 ★ 11,819repo stars codex-autoresearch-loop reason-machines codex-autoresearch-loop runs an autonomous edit-test-revert loop against measurable repository metrics. It stacks working changes in git and rolls back regressions without manual supervision. CX Codex +1 1,200installs the-loop oxbshw the-loop records how your UI, animation or game actually behaves, judges the recording against plain-language criteria, and iterates until it passes. CX Codex +1 737installs

From the same set55

The whole set →
policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars systematic-debugging systematic-debugging stops trial-and-error edits by enforcing a four-phase root cause protocol and freezing code changes until hypotheses are tested. CX Codex +1 ★ 937repo stars decision-map Turn an unresolved idea into a Git-tracked decision map, then pick up the investigation in later sessions. Useful before work is ready to build. CX Codex +1 ★ 937repo stars archon archon — a subagent that carries a big task through phases: splits a direction into steps, hands them to other agents and keeps campaign state between runs. CX Codex ★ 937repo stars marshal The marshal skill for Claude Code parses a task, gathers context from code and project memory, and chains skills. It runs in one session and asks only if it cannot continue. CX Codex +1 ★ 937repo stars test-gen test-gen is a Claude Code skill that generates and runs unit tests matching a project's existing framework, covering happy paths, edge cases, and failures. CX Codex +1 ★ 937repo stars design This skill builds a design manifest from a project’s styles or your preferences. A post-edit hook flags mismatches in edited files. CX Codex +1 ★ 937repo stars live-preview live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open