@dancingteeth/agent-looper · agent-loop
Agent Looper is an open-source fix-until-green harness: your coding agent writes a frozen goal and a determined 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 determined 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, and DSH. 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). Or you, your agent, or Looper wires a pair from what's installed. The pair stays for the whole loop. Not Auto.
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.
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, what it cost, and whether it needed you.
Your agent writes GOAL.md and a determined check that the feature really works.
A fresh worker loops until that check passes — optional judge / reviewGate only on serious findings.
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 determined check. Green means it really works. The model doesn't get to hallucinate done. If something's wrong, the mistake is in the goal or the script.
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.
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-init.GOAL.md and verify.sh until bash verify.sh is an honest determined check.pnpm exec agent-loop run until that check is green.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).
2. Use an API key already on this machine, or run under Doppler. Don't invent keys.
3. Run: pnpm exec agent-loop-init
4. Write GOAL.md for the feature and freeze it. Don't rewrite the goal mid-loop.
5. Write a determined check until `bash verify.sh` is an honest pass/fail that the feature actually works. The model does not get to say done.
6. Start the loop:
pnpm exec agent-loop run .cursor/loops/<task> --runtime <cursor|cline|opencode|pi|codex|dsh> --review-gate
7. 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=… # or: doppler run -- …
pnpm exec agent-loop-init
# edit .cursor/loops/my-task/GOAL.md
# edit verify.sh until `bash .cursor/loops/my-task/verify.sh` is honest
pnpm exec agent-loop run .cursor/loops/my-task --runtime cursor --review-gatepnpm add -D @dancingteeth/agent-looper @cursor/sdk
export CURSOR_API_KEY=… # or: doppler run -- …
pnpm exec agent-loop-init
# edit .cursor/loops/my-task/GOAL.md
# edit verify.sh until `bash .cursor/loops/my-task/verify.sh` is honest
pnpm exec agent-loop run .cursor/loops/my-task --runtime cursor --review-gateWorker and judge are separate — mix what you already pay for. Point the judge elsewhere if you want to save worker quota.
Harness how-to and default models · OpenCode providers · Pi runtime · DSH plugin · README.md