@dancingteeth/agent-looper · agent-loop
Agent Looper is an open-source fix-until-green harness: your coding agent writes a frozen goal and a deterministic check, then a fresh worker loops until that check passes — with a budget that actually stops.
You heard looping beats prompting. You install Agent Looper. You tell your agent you just want the feature. It writes the goal, writes a deterministic check, and runs until that check passes. No hallucinated “done.”
the harness that owns the grind.
fail → fresh worker
pass → done
If it hangs, it switches. Wonder if it's alive? There's a skill. When it finishes, you get a report card.
Agent Looper uses the coding agents you already pay for: Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, and Claude. It detects what's installed. You or your agent pick the model and provider. OpenCode and Pi can use OpenRouter, Vercel, Ollama, or another OpenAI-compatible router. How-to and default models: Harnesses.
Named presets: minmax (efficiency — cheap capable worker, strongest included judge), balanced (spend more on the worker, same judge), cursor (stay on Cursor: Composer + Grok — default judge grok-4.7). Or you, your agent, or Looper wires a pair from what's installed. The pair stays for the whole loop. Not Auto. On runtime: cursor, repo defaults that pin OpenCode Go escalateModel are not applied — Composer plus another judge uses reviewRuntime / reviewModel, not escalateModel.
Agent Looper is how indie builders get to handoff or production-ready without burning a frontier model on every loop. Cheap harness subscriptions you already have, a worker/judge pair that minmaxes cost, and a budget that actually stops. The check is the finish line — keep it honest. The judge is residual, not a production gate.
Starts cheap. Same check keeps failing → more thinking, then a stronger model. If the worker hangs or times out, it switches right away — it does not wait for the stuck-check count. Not Auto. A planned ladder.
Forward implements, then checks. Reverse starts from a red check and repairs. Clean-room: rebuild toward the frozen goal from tests and the public API. Don't copy the broken internals.
The IDE job list will lie. Ask your agent to use the check-running-loops skill. It looks at the harness process, not a spinner that stays green after the process died.
A report card, not a chat dump. How often the check sent work back, whether the worker hung, whether the judge bounced it, list and billed spend when they differ, and whether it needed you.
If you see your coding agent's logo on this page — type your idea as a normal prompt, and ask it to implement the feature with Agent Looper. It sets up the loop and keeps grinding until the check is green.
If you like the terminal — run pnpm exec agent-loop-setup: a one-screen setup wizard shows your recap and the current question, not a scrolling pile. Go back to change one answer without losing the rest. Then use pnpm exec agent-loop-prompt to type your idea and start the run. The scaffold judge stops as soon as frozen GOAL.md and verify.sh pass freeze (10-minute wall, not a long grind). The check stays the finish line.
When the check fails because something on your machine is missing or broken — not because the feature is wrong — the loop waits for you instead of sending another worker. Fix the environment, then resume. Real product failures still iterate.
Watch and the report card show two numbers when they differ: list (public API rates, including prompt-cache) and billed (what the runtime invoice says). $0 on a subscription quota is billed $0, not “free.” Budget caps use billed when you are on PAYG and list when the invoice is $0. OpenCode Go and Cline Pass model lists and list prices come from models.dev — sync picks up Grok 4.7, GPT-6 Luna, MiMo V2.6 Flash/Pro, and Space Bunny Free; unknown but well-formed slugs soft-gate — warn at loop start, show $0 until priced. Budget caps still reject unpriced worker or escalate models.
Before you add another line to verify.sh or REVIEWS.md, walk a diverse sample of past runs under .cursor/loop-exports/ so the scoreboard matches real failures — not one lucky green. Procedure: docs/unknowns-preflight.md. Freeze during a run is unchanged.
Your agent writes GOAL.md and a deterministic check that the feature really works.
Optional setup.sh (or setup in loop.json) runs once before the first worker — setup failure does not spawn a worker.
A fresh worker loops until that check passes — optional judge / reviewGate only on serious findings.
After each visit the harness restores frozen specs if a worker edited them — and removes any frozen basename they planted (like setup.sh) so it cannot carry into the next run.
Between runs, label export packs before you tighten the check (unknowns preflight).
Progress lives in git and files, not chat memory.
New session every iteration. Failed turns don't poison the next run, and the frozen goal stays a cached prefix so later rounds cost less. Progress is the repo — not an accumulating thread.
A deterministic check. Green is only as good as the check you froze. The model doesn't get to hallucinate done. If your machine is broken, the loop waits — it doesn't burn another worker on a missing command. Real product failures still iterate.
After the check is green, a review skill looks for real blockers and leftover nits. Blockers come back for the next iteration. Advisory is your call. Subjective taste does not force another loop.
You say what you want. Your agent writes the goal, wires the check, and starts the loop. You pick when to stop and what to spend — the harness owns the grind.
| Agent Looper | What you’re used to |
|---|---|
| Shell verify is the exit | LLM grading itself |
| Fresh context each iteration | Accumulating chat thread |
| One-repo fix harness | Team-ops factory |
You own the finish line — outcome, scoreboard, permission, budget. The harness owns the grind.
MIT. Inspectable. Models stay whoever you already pay — Cursor, OpenCode, OpenRouter, Codex, DSH, Muse, Claude.
What you own is the loop: frozen GOAL.md, measurable verify.sh,
sparse REVIEWS.md / AGENTS.md, and orchestration that keeps workers fresh and spend bounded.
Node 22+, pnpm. Tell your agent to set up Agent Looper for the feature you want.
@dancingteeth/agent-looper and the SDK for your coding agent (Cursor: @cursor/sdk).pnpm exec agent-loop-setup, then pnpm exec agent-loop-prompt --out .cursor/loops/my-task to type your idea and start.Set up Agent Looper in this repo for the feature I want. I don't want to babysit the grind.
Requirements: Node 22+ and pnpm.
1. Add @dancingteeth/agent-looper and the SDK for the coding agent on this machine. Cursor uses @cursor/sdk. If you're not sure, detect what's installed (Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, Claude).
2. Keep @dancingteeth/agent-looper in package.json even if you gitignore `.cursor/loops`. Don't only npx it.
3. Use an API key already on this machine. Don't invent keys.
4. Ask me what I want, then implement it with Agent Looper — set up the loop, write GOAL.md and verify.sh, and keep grinding until the check is green.
Or if I'm in the terminal: pnpm exec agent-loop-setup then pnpm exec agent-loop-prompt --out .cursor/loops/<task>.
Manual fallback: pnpm exec agent-loop-init and edit GOAL.md + verify.sh yourself.
5. Start or resume the loop:
pnpm exec agent-loop run .cursor/loops/<task> --runtime <cursor|cline|opencode|pi|codex|dsh|muse|claude> --review-gate
6. Review skill: blockers come back for the next iteration. Advisory is my call. Don't loop on subjective taste.
Cursor example (swap the SDK, key, and --runtime if this machine isn't Cursor):
pnpm add -D @dancingteeth/agent-looper @cursor/sdk
export CURSOR_API_KEY=…
pnpm exec agent-loop-setup
pnpm exec agent-loop-prompt --out .cursor/loops/my-task
# or manually: pnpm exec agent-loop-init and edit GOAL.md + verify.sh
pnpm exec agent-loop run .cursor/loops/my-task --runtime cursor --review-gatepnpm add -D @dancingteeth/agent-looper @cursor/sdk
# keep @dancingteeth/agent-looper in package.json even if .cursor/loops is gitignored — don't only npx it
export CURSOR_API_KEY=…
pnpm exec agent-loop-setup
pnpm exec agent-loop-prompt --out .cursor/loops/my-task
# or manually: pnpm exec agent-loop-init and edit GOAL.md + verify.sh
pnpm exec agent-loop run .cursor/loops/my-task --runtime cursor --review-gateThis tool is free. We keep building it when the community actually uses it and tells us when it's broken.
@dancingteeth/agent-looper in public package.json even if you gitignore the loop folder. Don't only npx it.AGENT_LOOPER_TELEMETRY=1 so we see real runs, not just npm noise. Off by default. Privacy.Worker and judge are separate — mix what you already pay for. Point the judge elsewhere if you want to save worker quota.
runtime: muse (not minmax)runtime: claude (not minmax; --safe-mode)Harness how-to and default models · OpenCode providers · Pi runtime · DSH plugin · Muse runtime · Claude runtime · Embed API · Security · Changelog · README.md