Goal Loop
aarcher4/goal-loop
Loop autônomo com verificação objetiva até conclusão genuína
Ver no GitHubSkill para Claude Code que executa tarefas autonomamente até um objetivo ser verificado, com journal de progresso persistente e circuit breakers de segurança. Implementa loops relentless contra gates de verificação (testes, build, lint), evitando que o agente se declare vitorioso prematuramente e protegendo contra reward hacking.
Instalação
npx convez-ai aarcher4/goal-loop1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar testes até todos passarem automaticamente
- Build e deploy com retry inteligente e validação contínua
- Refatoração de código com verificação de integridade a cada passo
Veredito

Ferramenta robusta para automação confiável em Claude Code, eliminando dependência de autoavaliação do agente com gates verificáveis e guardrails contra trapaças. Ideal para pipelines que exigem conclusão garantida, mas requer setup cuidadoso e compreensão profunda de seus mecanismos internos.
README
A tradução para o português deste README ainda está na fila.
goal-loop
A Claude Code skill that runs a task relentlessly and autonomously until it's genuinely complete — not until the agent thinks it's done. The loop iterates against an objective verification gate (your tests/build/typecheck/lint), keeps a progress journal that survives context compaction, and trips safety circuit breakers so it never runs away.
Inspired by the "Ralph" technique and OpenAI-Codex-style goal-mode loops, hardened with anti-reward-hacking guardrails and bounded-relentless rails.
TL;DR — Tell Claude "keep going until the tests pass" and walk away. It loops one reviewable unit of work at a time, commits each pass, runs the gate, and stops only when the gate is green and every acceptance box is checked — or honestly reports that it's blocked.
Why this exists
"Run an agent until it's done" sounds simple, but every real-world failure comes from the harness around the loop, not the loop itself:
- Agents are unreliable judges of their own work. They have a strong incentive to declare victory to end the task. → Completion is decided by a runnable command that exits 0, never by self-assessment.
- Given a gate, agents learn to beat the gate (delete failing tests, hardcode outputs, stub the verify command). → Inoculation guardrails enumerating the forbidden shortcuts are pasted into the goal spec and re-fed every iteration (~75–90% reduction in cheating).
- Long runs blow past the context window and auto-compaction silently drops early instructions. → State is externalized to
GOAL.md(frozen spec) +PROGRESS.md(append-only journal) that the agent re-reads every pass. - "Relentless" without bounds is how you get a multi-day runaway loop. → Three independent circuit breakers: max-iters, wall-clock deadline, and a stuck backstop that stops when the same failure repeats N times.
See references/harness-rationale.md for the full reasoning behind each guardrail, and references/engine-design.md for engine internals.
How it works
Each iteration runs the same tight contract:
- Re-ground — read
GOAL.md+ the tail ofPROGRESS.md. - Stuck check — if the last few entries are the same failure, write a
BLOCKEDnote and stop honestly. - Pick ONE thing — the single most important unchecked acceptance item.
- Implement it (searching first to avoid duplicating existing code).
- Run the gate — execute the verify command, capture the exit code.
- Journal — append a
GATE: PASS|FAIL <signature>entry toPROGRESS.md. - Checkpoint — one git commit per iteration (clean rollback + audit trail).
- Decide — emit the completion promise only if every box is checked and the gate exited 0. Otherwise, loop.
Two interchangeable engines
| Engine | Trigger | Install | Speed |
|---|---|---|---|
| stop-hook (default) | A Claude Code Stop hook blocks the session from ending and re-feeds the goal | One-time install into ~/.claude/settings.json; activates next session | Zero gaps, runs for hours |
| loop (fallback) | The agent re-wakes itself with ScheduleWakeup every ~60–270s | None — works in the current session immediately | Tiny gaps, cache-friendly, trivially interruptible |
Both run the identical per-iteration contract; they differ only in how the next iteration is triggered. The engine is pure Node (ships with Claude Code) — no jq/perl dependency, identical behavior on Windows, macOS, and Linux.
Install
Copy the goal-loop skill into your Claude Code skills directory:
# user-level (available in every project)
git clone https://github.com/aarcher4/goal-loop.git
cp -r goal-loop ~/.claude/skills/goal-loop
# — or project-level —
cp -r goal-loop /path/to/your/project/.claude/skills/goal-loop
Make sure the skill folder is named
goal-loop(thename:inSKILL.md). Restart Claude Code so it picks up the new skill.
Verify the engine on your machine (17 checks):
node ~/.claude/skills/goal-loop/scripts/_selftest.js
Usage
In Claude Code, just describe the task and ask it to keep going. Claude will invoke the skill automatically on phrases like "run until done", "don't stop until it's complete", "loop on this autonomously", or "keep going until the tests pass".
Or invoke it explicitly:
/goal-loop Make the whole test suite pass --verify "npm run verify:full" --max-iters 40 --deadline 4h
Flags
| Flag | Meaning |
|---|---|
--verify '<cmd>' | The objective gate — a command that exits non-zero on failure. Inferred from the project if omitted (confirmed with you first). |
--max-iters N | Hard cap on iterations (default 50). |
--deadline 4h | Wall-clock ceiling. |
--engine stop-hook|loop | Force an engine (default: auto-detect). |
--promise 'PHRASE' | Custom completion sentinel. |
The verify gate is required
This skill needs an objective definition of done — a runnable command. For subjective goals (design/UX "feel") with no gate, it will tell you so rather than pretend. Define acceptance tests first.
Run artifacts
A run creates a .goal-loop/ directory in your project:
GOAL.md— the frozen spec: behavioral outcomes, acceptance checklist, exact verify command, guardrails. Never edited mid-run.PROGRESS.md— append-only journal; the run record and the substrate for stuck-detection.loop-prompt.md— the compact per-iteration prompt the engine re-feeds.loop.local.md— engine state (gitignored).
Stopping a run
- Natural stop: completion, an honest
BLOCKED, or a tripped rail (max-iters / deadline / stuck). - Manual kill switch:
node scripts/stop.js(or delete.goal-loop/loop.local.md). - The run record (
GOAL.md,PROGRESS.md, git history) is left intact for review.
Limits (honest about these)
- No token-budget rail — a Stop hook can't see token counts. Bound runs with
--max-itersand--deadline. - Session-bound laptop primitive — for scheduled/unattended cloud runs, use Claude Code's
/scheduleinstead. - Honesty dependency — the agent must actually run the gate and journal the true result. The guardrails make that the path of least resistance, but the gate's integrity rests on not circumventing it.
License
MIT — see LICENSE.