convez.ai
SkillAutomaçãoAvançado
aarcher4

Goal Loop

aarcher4/goal-loop

Loop autônomo com verificação objetiva até conclusão genuína

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-loop

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Re-ground — read GOAL.md + the tail of PROGRESS.md.
  2. Stuck check — if the last few entries are the same failure, write a BLOCKED note and stop honestly.
  3. Pick ONE thing — the single most important unchecked acceptance item.
  4. Implement it (searching first to avoid duplicating existing code).
  5. Run the gate — execute the verify command, capture the exit code.
  6. Journal — append a GATE: PASS|FAIL <signature> entry to PROGRESS.md.
  7. Checkpoint — one git commit per iteration (clean rollback + audit trail).
  8. Decide — emit the completion promise only if every box is checked and the gate exited 0. Otherwise, loop.

Two interchangeable engines

EngineTriggerInstallSpeed
stop-hook (default)A Claude Code Stop hook blocks the session from ending and re-feeds the goalOne-time install into ~/.claude/settings.json; activates next sessionZero gaps, runs for hours
loop (fallback)The agent re-wakes itself with ScheduleWakeup every ~60–270sNone — works in the current session immediatelyTiny 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 (the name: in SKILL.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

FlagMeaning
--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 NHard cap on iterations (default 50).
--deadline 4hWall-clock ceiling.
--engine stop-hook|loopForce 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-iters and --deadline.
  • Session-bound laptop primitive — for scheduled/unattended cloud runs, use Claude Code's /schedule instead.
  • 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.

Ver o original no GitHub

Bom para

Relacionados