loop-engine — AI Loop Engineering for Claude Code
A Claude Code plugin that turns Claude into a verification-gated autonomous loop: give it a
goal and a way to check success, and it works act → verify → repeat until the check passes —
bounded by an iteration cap and no-progress detection so it always terminates.
Marketplace + plugin. The plugin lives in plugins/loop-engine.
What is AI loop engineering?
Loop engineering is the practice of designing AI work as iterative cycles —
act → observe → decide → repeat — that continue until a verifiable goal is met, rather than a
single one-shot response. It is the successor discipline to prompt engineering and context
engineering.
The problem it solves. Single-shot prompting hits a ceiling on real tasks. A one-shot agent
can't catch runtime errors, can't adapt to environment-specific issues, and can't confirm its
output actually works. A loop closes that feedback gap. For agentic coding, quality "usually
isn't the base model — it's the loop design": how the agent handles errors, manages context
across iterations, scopes the work, and verifies the result.
Anatomy of a good loop: a clear, testable goal; tool access (shell, tests, filesystem);
context management (keep the goal + latest feedback in front of the model, read state from disk);
termination logic (success / max-iterations / no-progress / human escalation); and error
recovery (never retry an identical failed approach).
Guardrails — failure modes are routine, not edge cases: infinite loops, goal drift, context
overflow, and token-cost blowups. Mitigate with hard iteration caps, no-progress detection,
deterministic verification (tests/type-checks beat LLM self-assessment), and human
checkpoints before irreversible actions.
This plugin builds on the Stop-hook loop pattern from Anthropic's official
ralph-wiggum
plugin and hardens it with planning, a deterministic verify gate, persisted state, and
no-progress detection.
Research sources
How the loop works
A Stop hook drives the loop. Each time Claude finishes a turn, the hook:
- Loads loop state; if there is no active loop, it allows the stop.
- Runs the configured verify command and captures its exit code + output.
- Success = verify exits 0 (and the completion-promise was emitted, if one is set) →
mark
completed and allow the stop.
- Else increment the iteration; if
iteration ≥ max_iterations → mark failed, allow stop.
- No-progress — if the result signature (verify output +
git diff --stat) is identical
for N consecutive iterations → mark failed, allow stop.
- Otherwise block the stop and re-inject the goal + success criteria + latest verify output
as Claude's next turn — closing the feedback gap with real failure output.
State is stored at .claude/loop-engine/state.json in your project (gitignored), one active
loop per project.
Install
Try it locally (no install):
claude --plugin-dir ./plugins/loop-engine
Install from this repo as a marketplace:
/plugin marketplace add juliosaraiva/claude-code-loop-pluging
/plugin install loop-engine
Requirements: bash, jq, and git on your PATH. (jq drives the state file; the
SessionStart hook warns if it's missing.)
Usage
| Command | What it does |
|---|
/loop-engine:plan "<goal>" | Design a loop (plan + verifiable criteria + verify command) without starting it. |
/loop-engine:start "<goal>" --verify "<cmd>" [--max-iterations N] [--criteria "a||b"] [--completion-promise TEXT] | Start the loop. |
/loop-engine:status | Show status, iteration, and last verify result. |
/loop-engine:stop | Cancel the active loop. |
Example:
/loop-engine:start "make the test suite pass" --verify "npm test" --max-iterations 5
A runnable walkthrough lives in examples/fix-failing-test.
Components
