/auto-loop Key Feature

Auto-Loop

TDD-based autonomous development loop. Define your acceptance criteria, and let Claude iterate until everything passes.

How It Works

Define Acceptance Criteria

Use - [ ] checkboxes to define what "done" looks like

Auto-Loop Iterates

Each iteration runs Red-Green-Refactor for one AC

Stop Hook Re-injects

Uses Claude Code's Stop hook to continue automatically

✓

Complete When All Pass

Exits when all ACs are checked or max iterations reached

The TDD Cycle

Each Auto-Loop iteration follows the classic TDD cycle:

Phase	Action	Tool Used
RED	Write a failing test for next AC	test-runner skill
GREEN	Write minimal code to pass	test-runner skill
REFACTOR	Improve code quality	code-reviewer agent
VALIDATE	Run full test suite + lint	test-runner skill
COMMIT	Save progress	/smart-commit
DECIDE	Check if done, continue or exit	checkpoint.json

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 15

Resume from Checkpoint

# After interruption or restart
/auto-loop --resume

Check 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 tests

Checkpoint 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 allows you to resume after interruptions, track progress, and review what was changed.

Stop & Control

Stop the Loop

# In another terminal
touch .auto-loop/stop

Loop stops gracefully after current iteration completes.

Resume the Loop

# Remove stop signal
rm -f .auto-loop/stop

# Resume
/auto-loop --resume

Continues from where it left off.

How Stop Hook Works

Auto-Loop uses Claude Code's Stop hook mechanism. Similar to the official Ralph Wiggum plugin.

# .claude/hooks.json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/auto-loop-stop.sh"
      }]
    }]
  }
}

When Claude tries to stop, the hook checks if there's more work to do. If yes, it returns {"decision": "block", "prompt": "..."} to continue. If complete, it returns {"decision": "allow"} to exit normally.

Ready to Try?

Install Director Mode Lite and start your first Auto-Loop.

Installation Guide →