lodeloop

Autonomous coding agent loop — wraps AI coding CLIs in a verification loop until all tasks pass.

Inspired by the Ralph Wiggum pattern but designed for AI-as-orchestrator workflows (not human terminal use).

What It Does

┌─────────────────────────────────────────────────────┐
│  lodeloop                                           │
│                                                     │
│  for each iteration:                                │
│    1. Build prompt from task.json + progress.md     │
│    2. Run coding agent (Codex CLI / Claude CLI)     │
│    3. Run verification gates (typecheck/lint/test)  │
│    4. If pass → commit, mark story done             │
│    5. If fail → inject error into next iteration    │
│    6. Check circuit breaker (stagnation?)            │
│    7. All stories done? → exit success              │
│                                                     │
└─────────────────────────────────────────────────────┘

Quick Start

# Clone
git clone https://github.com/lodekeeper/lodeloop.git
cd lodeloop

# Create a task file (see templates/task.json.example)
cp templates/task.json.example ~/myproject/task.json
# Edit task.json with your stories and verification commands

# Run
./lodeloop.sh ~/myproject/task.json

# With options
./lodeloop.sh -a claude -n 10 --verbose ~/myproject/task.json

Task File Format

{
  "project": "myapp",
  "feature": "Add user authentication",
  "workdir": "~/myapp",
  "agent": "codex",
  "verify": {
    "commands": ["npm run typecheck", "npm run lint", "npm test"],
    "timeout": 300
  },
  "context_files": ["AGENTS.md"],
  "stories": [
    {
      "id": "S1",
      "title": "Add user model",
      "description": "Create User model with email and password",
      "acceptance": ["User model exists", "Migration runs", "Typecheck passes"],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Key Fields

Field	Description
project	Project name (used in commit messages)
feature	Feature being implemented
workdir	Working directory (supports ~)
agent	codex or claude
verify.commands	Array of commands that must all pass (exit 0)
verify.timeout	Max seconds per verification command
context_files	Files to include in agent prompt (relative to workdir)
stories	Array of stories — each is one unit of work

Story Sizing

Each story must be completable in one agent iteration (one context window). Right-sized:

• "Add a database migration" ✅
• "Add a REST endpoint" ✅
• "Build the entire backend" ❌ (too big — split it)

CLI Options

Usage: lodeloop [OPTIONS] <task.json>

Options:
  -n, --max-iterations N  Maximum iterations (default: 20)
  -a, --agent AGENT       Agent: codex|claude (default: codex)
  -t, --timeout SECS      Per-iteration timeout (default: 600)
  --notify CMD            Command on completion ({status}, {iterations}, {stories} placeholders)
  --dry-run               Print prompt and exit
  --resume                Resume from existing progress
  --reset                 Reset all state
  --status                Show current status
  --verbose               Stream agent output

Circuit Breaker

Detects stagnation and stops the loop before burning tokens:

State	Condition	Behavior
CLOSED	Normal operation	Continue
HALF_OPEN	2 iterations without progress	Continue, monitoring
OPEN	3+ iterations without progress, or same error 5x	Stop

Progress = git commits or file changes. No progress for 3 iterations = the agent is stuck.

State Directory

Everything lives in .lodeloop/ in the working directory:

.lodeloop/
├── circuit.json         # Circuit breaker state
├── progress.md          # Append-only progress log
├── result.json          # Final result (written on exit)
└── logs/
    ├── prompt_1.md      # Prompt sent to agent
    ├── iteration_1.log  # Agent output
    └── ...

Environment Variables

Variable	Default	Description
LODELOOP_AGENT	codex	Default agent
LODELOOP_MAX_ITER	20	Default max iterations
LODELOOP_TIMEOUT	600	Default per-iteration timeout
CB_NO_PROGRESS_THRESHOLD	3	Iterations without progress before circuit opens
CB_SAME_ERROR_THRESHOLD	5	Repeated errors before circuit opens

Requirements

• bash 4+
• jq
• git
• One of: Codex CLI or Claude CLI

Running Tests

bash tests/test_circuit_breaker.sh

License

MIT

Credits

• Geoffrey Huntley — original Ralph Wiggum pattern
• snarktank/ralph — canonical implementation
• frankbria/ralph-claude-code — circuit breaker inspiration