Auto-Loop
A Stop-hook-assisted TDD loop. Define acceptance criteria and an iteration cap; Claude is asked to continue while checkpoint state remains active.
How It Works
Define Acceptance Criteria
Use - [ ] checkboxes as working completion state, then verify each criterion
Auto-Loop Iterates
Each iteration asks Claude to apply Red-Green-Refactor to an incomplete AC
Stop Hook Re-injects
While state is active, the Stop hook blocks exit with a reason for the next iteration
Exit on Recorded Completion or Cap
Exits when state is marked completed, a stop is requested, or max iterations are reached
Verify the result: acceptance-criteria checkboxes and checkpoint status are model-maintained state, not independent proof. Inspect the diff and run the project's real tests, lint, and build before treating the task as complete.
The TDD Cycle
The bundled instructions ask each Auto-Loop iteration to follow this TDD cycle:
| Phase | Action | Suggested Support |
|---|---|---|
| RED | Write a failing test for next AC | /test-first guidance |
| GREEN | Write minimal code to pass | Project test command |
| REFACTOR | Improve code quality | Optional code-reviewer agent |
| VALIDATE | Run full test suite + lint | test-runner + project commands |
| COMMIT | Save progress | /smart-commit when authorized |
| DECIDE | Check if done, continue or exit | Checkpoint state + verification |
Usage Examples
Basic Usage
/auto-loop "Create a calculator module
Acceptance Criteria:
- [ ] add(a, b) function
- [ ] subtract(a, b) function
- [ ] multiply(a, b) function
- [ ] divide(a, b) with zero check
- [ ] Unit tests for all functions"With Iteration Limit
/auto-loop "Implement user auth" --max-iterations 15Resume from Checkpoint
# After interruption or restart
/auto-loop --resumeCheck Status
/auto-loop --status
# Output:
Iteration: 5/20
Status: in_progress
Acceptance Criteria:
[x] add(a, b) function
[x] subtract(a, b) function
[ ] multiply(a, b) function
[ ] divide(a, b) with zero check
[ ] Unit testsCheckpoint System
Auto-Loop maintains state in .auto-loop/checkpoint.json:
{
"request": "Create a calculator module",
"current_iteration": 5,
"max_iterations": 20,
"status": "in_progress",
"acceptance_criteria": [
{ "id": 1, "description": "add(a, b) function", "done": true },
{ "id": 2, "description": "subtract(a, b) function", "done": true },
{ "id": 3, "description": "multiply(a, b) function", "done": false }
],
"files_changed": ["calculator.js", "calculator.test.js"]
}This can resume an interrupted run when the checkpoint remains present and valid. Treat the recorded files and status as a review aid, not proof that the changes or tests are correct.
Stop & Control
Stop the Loop
# In another terminal
touch .auto-loop/stopLoop stops gracefully after current iteration completes.
Resume the Loop
# Resume from the retained checkpoint
/auto-loop --resume
The hook consumes the stop signal; the checkpoint remains available for --resume.
How Stop Hook Works
Auto-Loop uses Claude Code's Stop hook mechanism. The installer merges this entry into the project's local settings.
# .claude/settings.local.json (merged by install.sh)
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-loop-stop.sh"
}]
}]
}
}
When Claude tries to stop, the hook checks the local checkpoint. While the loop is active and below its cap,
it prints {"decision": "block", "reason": "..."} to request another iteration.
When completed, stopped, capped, or no valid active checkpoint exists, it exits successfully without a decision payload.