# loop-forge
**Turn a one-line description of a repetitive task into a reusable, self-guarding Claude Code slash command.**
[](LICENSE)
[](https://github.com/sangrokjung/loop-forge)
[](https://github.com/sangrokjung/loop-forge/pulls)
---
## The problem
If you don't code, you can only write **one-shot prompts**. You type the same
instruction again every time, by hand. You can't author a reusable `/command` that
makes an AI repeat a task reliably — and even if you could, you wouldn't know to add
the guardrails that keep an automated loop from quietly breaking. So the repetitive
work stays manual.
## What it does
loop-forge takes a vague one-liner and stamps it into a **reusable slash command** —
and automatically attaches the two safety devices a non-developer doesn't even know
to ask for: an **independent verifier** and a **hardstop**.
It runs a 6-stage flow: receive your one line → **diagnose** it into one of 5 loop
shapes → **interview** you for the blanks → **auto-inject** the verifier, the
hardstop, and (for outbound actions) an external-action gate → **preview** how it
will run → and only after you approve, **stamp** it as a `/command` you can run
forever.
```
You: "I want to summarize 100 shop reviews into 3 lines each"
│
loop-forge:
1. Diagnoses → Batch loop
2. Interviews → where are the items? per-item task? where does output land? a cap?
3. Auto-injects → verifier (count in == count out + independent spot re-check)
+ hardstop (max-items budget + per-item fail cap + abort at 20% failure)
4. Previews → "here's how it will run" (+ optional 1-item sample)
5. Stamps → /review-summary (reusable forever; safety baked in)
```
It works in **any language**: it detects the language of your one-liner, runs the
whole interview in it, and writes the stamped command's prose in it — while keeping
the structural tokens canonical so any teammate's harness can still parse it. Every
file in the repo is English; there is no per-language copy.
## The 5 loop archetypes
Non-developer work reduces to five shapes. There is no sixth — loop-forge never
invents one. If a request doesn't fit, it diagnoses the nearest shape or asks one
branch question.
| Archetype | When to use it | Example one-liner |
|---|---|---|
| **Batch** | Same task across N items, none skipped | "Summarize all 100 reviews into 3 lines each" |
| **Pipeline** | Pass through ordered stages A → B → C | "Take a transcript through outline → draft → polish" |
| **Refine** | Make → evaluate → fix, repeated | "Draft a headline, score it, improve it until it's good" |
| **Watch** ⚠️ | Watch a target, act when a condition fires | "Every time an email arrives, draft a reply" |
| **Explore** | Diverge into N candidates → converge to best K | "Generate a few options and pick the best one" |
## Why your loops won't silently break
A loop that grades its own homework — or one that keeps going cluelessly while it
burns tokens (the Ralph Wiggum loop) — is how automation fails quietly. loop-forge
won't stamp a loop without two guards, and a deterministic check (`check_safety.py`)
blocks any spec that's missing one. It's **non-bypassable**.
- **Verifier (maker ≠ checker)** — the loop's output is re-checked in a pass that is
*separate* from the pass that produced it, so the loop can't approve its own
mistakes.
- **Hardstop** — a budget / count / cooldown ceiling, so a loop can't quietly run
away. (Batch caps max items and aborts past a failure rate; Refine caps iterations
and stops on score stagnation; Watch caps daily actions with a cooldown and an
idempotency key; and so on.)
- **External-action gate (Watch)** — the most dangerous shape. Any loop whose action
is outbound (sending, posting, hitting a webhook) is born requiring a **dry-run
preview or human approval first** — the same principle as drafting an email and
letting a person send it. The gate is enforced on a structured enum, so it holds in
any language.
loop-forge also never schedules unattended runs (no `launchd` / `cron`) and never
publishes externally on its own. It stamps the reusable command and stops there.
## Install
loop-forge is a Claude Code plugin (`.claude-plugin/plugin.json`, name `loop-forge`).
**Marketplace (recommended)** — in a Claude Code session:
```
/plugin marketplace add sangrokjung/loop-forge
/plugin install loop-forge@loop-forge
```
**Manual** — clone and add the local path, or copy the assets into `~/.claude`:
```
git clone https://github.com/sangrokjung/loop-forge
# then, in a Claude Code session:
/plugin marketplace add ./loop-forge
# …or copy manually:
cp -r loop-forge/skills/loop-forge ~/.claude/skills/
cp loop-forge/commands/loop-forge.md ~/.claude/commands/
```
## Usage
Hand loop-forge the task you keep doing by hand:
```
/loop "summarize 100 reviews"
```
It diagnoses the shape, asks a few plain-language questions, shows you a preview, and
— once you approve — stamps a reusable command (e.g. `/review-summary`) with the
verifier and hardstop already baked in. Run that command any time; nothing about it
re-prompts you for the loop's design again.
You can also just describe the situation in plain language ("automate this", "make
this repeatable", "do this for every item", "alert me when a condition is met") and
the skill activates on intent.
## Claude Code (native) & Codex (paste-fallback)
Both outputs are rendered from **one** loop spec, so the body — skeleton, verifier,
hardstop, and done-signal — is byte-identical. The only difference is how you invoke
it.
- **Claude Code (native)** — the primary output is a slash command saved to
`.claude/commands/<name>.md` (project) or `~/.claude/commands/<name>.md` (global).
Invoke it with `/<name> <input>`.
- **Codex / other agents (paste-fallback)** — loop-forge can also render the same
loop as a harness-agnostic **Portable Prompt**: a paste-able block you drop into the
session of any agent (Codex, Cursor, ChatGPT, …). It's an opt-in bonus, not
required.
## License
MIT — see [LICENSE](LICENSE).