/ralph-loop - Autonomous Agent Loop Management
Start, monitor, and manage autonomous agent execution loops using the Ralph Wiggum pattern: fresh-context iterations with checkpoint handoffs, health monitoring, and budget enforcement.
Usage
# Start an autonomous loop
/ralph-loop start --task H.8.6.4 --goal "Implement X with tests" --agent senior-architect
# Start with configuration
/ralph-loop start --task H.8.6.4 \
--goal "Implement feature X" \
--agent senior-architect \
--max-iterations 10 \
--max-cost 50 \
--model claude-opus-4-6
# Check loop status
/ralph-loop status <loop-id>
/ralph-loop status --active
# List all loops
/ralph-loop list
/ralph-loop list --task H.8
# Pause/resume a loop
/ralph-loop pause <loop-id>
/ralph-loop resume <loop-id>
# Stop a loop
/ralph-loop stop <loop-id> --reason "Manual stop"
# Get loop report
/ralph-loop report <loop-id>
/ralph-loop report <loop-id> --json
System Prompt
When /ralph-loop is invoked, execute the following:
1. Parse Command
import sys, json, os
from pathlib import Path
CORE_DIR = Path(os.environ.get('CODITECT_CORE', os.path.expanduser('~/.coditect')))
sys.path.insert(0, str(CORE_DIR))
sys.path.insert(0, str(CORE_DIR / 'scripts' / 'core'))
from ralph_wiggum.loop_orchestrator import LoopOrchestrator, LoopConfig, run_loop
from ralph_wiggum.termination_criteria import TerminationReason
2. Handle Subcommands
start
Initialize a new autonomous loop:
orchestrator = LoopOrchestrator(task_id=TASK_ID, project_id=PROJECT_ID)
config = LoopConfig(
max_iterations=MAX_ITERATIONS,
max_cost=MAX_COST,
agent_type=AGENT_TYPE,
model=MODEL,
)
status = orchestrator.initialize(goal=GOAL, config=config)
Then begin the iteration loop:
For each iteration:
1. plan = orchestrator.plan_iteration(iteration)
2. Spawn agent with plan["prompt"] using Task tool
3. Collect result (completed items, errors, tokens)
4. orchestrator.record_iteration(result)
5. orchestrator.create_iteration_checkpoint(...)
6. termination = orchestrator.evaluate_termination()
7. If termination.should_terminate: orchestrator.complete(reason)
8. handoff = orchestrator.check_handoff(context_utilization)
9. If handoff: continue to next iteration with fresh context
status
Display current loop status:
╔══════════════════════════════════════════════════════════════╗
║ RALPH LOOP STATUS ║
╠══════════════════════════════════════════════════════════════╣
║ Loop ID: abc-def-123 ║
║ Task: H.8.6.4 ║
║ State: RUNNING ║
║ Iteration: 3 / 10 ║
║ Cost: $4.50 / $50.00 (9%) ║
║ Duration: 12 min / 120 min ║
╠══════════════════════════════════════════════════════════════╣
║ Health: HEALTHY ║
║ Last Checkpoint: abc123 ║
║ Completed Items: 8 ║
║ Errors: 0 ║
╚══════════════════════════════════════════════════════════════╝
list
Show all loops:
╔══════════════════════════════════════════════════════════════╗
║ ACTIVE LOOPS ║
╠══════════════════════════════════════════════════════════════╣
║ ID Task State Iter Cost Started ║
║ abc-def-1 H.8.6.4 RUNNING 3/10 $4.50 10 min ago ║
║ xyz-789-2 J.4.2.1 PAUSED 5/15 $8.20 45 min ago ║
╚══════════════════════════════════════════════════════════════╝
report
Generate execution report:
╔══════════════════════════════════════════════════════════════╗
║ RALPH LOOP REPORT ║
╠══════════════════════════════════════════════════════════════╣
║ Loop: abc-def-123 ║
║ Task: H.8.6.4 ║
║ Goal: Implement feature X with tests ║
║ Result: COMPLETED (goal_achieved) ║
╠══════════════════════════════════════════════════════════════╣
║ Iterations: 7 / 10 ║
║ Total Cost: $12.45 ║
║ Duration: 34 min ║
║ Tokens: 245K input / 38K output ║
╠══════════════════════════════════════════════════════════════╣
║ Completed Items: ║
║ 1. Created database schema ║
║ 2. Implemented API endpoints ║
║ 3. Added unit tests (24/24 passing) ║
║ 4. Updated documentation ║
╠══════════════════════════════════════════════════════════════╣
║ Cost Efficiency: ║
║ Cost per item: $3.11 ║
║ Tokens per item: ~70K ║
║ Budget utilization: 25% ║
╚══════════════════════════════════════════════════════════════╝
3. Handle Options
| Option | Description | Default |
|---|---|---|
--task ID | Task ID for the loop | Required |
--goal TEXT | Goal description | Required for start |
--agent TYPE | Agent type to spawn | senior-architect |
--model MODEL | LLM model | claude-opus-4-6 |
--max-iterations N | Maximum iterations | 10 |
--max-cost N | Maximum cost in USD | 50.0 |
--max-duration N | Maximum duration in minutes | 120 |
--project ID | Project ID | Auto-detected |
--resume CHECKPOINT | Resume from checkpoint ID | - |
--reason TEXT | Reason for stop/pause | - |
--json | JSON output | false |
Architecture
The Ralph Loop uses three integrated services:
┌─────────────────────────────────────────────────┐
│ LoopOrchestrator │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │Checkpoint│ │ Health │ │ Token │ │
│ │ Service │ │ Monitor │ │ Economics │ │
│ │(ADR-108) │ │(ADR-110) │ │ (ADR-111) │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌────┴──────────────┴───────────────┴───────┐ │
│ │ Termination Criteria │ │
│ │ budget | iterations | health | duration │ │
│ └───────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────┘
│
┌────────┴────────┐
│ Agent Spawns │
│ (fresh context) │
└─────────────────┘
Termination Criteria
| Criterion | Threshold | Priority |
|---|---|---|
| Circuit breaker open | 3+ failures | 1 (highest) |
| Health failure | FAILING/TERMINATED | 2 |
| Consecutive errors | 3+ (configurable) | 3 |
| Budget exhausted | >= max_cost | 4 |
| Max iterations | >= max_iterations | 5 |
| Max duration | >= max_duration | 6 |
| No progress | 3+ iters, 0 items | 7 |
Files
| File | Purpose |
|---|---|
scripts/core/ralph_wiggum/loop_orchestrator.py | Core orchestrator |
scripts/core/ralph_wiggum/termination_criteria.py | Termination logic |
agents/ralph-loop-monitor.md | Monitoring agent |
~/PROJECTS/.coditect-data/ralph-loops/ | Loop state storage |
Examples
Basic Feature Development Loop
/ralph-loop start --task A.10.1.1 \
--goal "Implement container session API with CRUD endpoints and tests" \
--agent senior-architect \
--max-iterations 8 \
--max-cost 25
Resume After Context Exhaustion
# Get last checkpoint
/checkpoint list --task A.10.1.1
# Resume loop from checkpoint
/ralph-loop start --task A.10.1.1 \
--goal "Continue container session API" \
--resume abc123-checkpoint-id
Monitor Active Loops
/ralph-loop status --active
/ralph-loop report abc-def-123
Related
- ADR-108: Agent Checkpoint and Handoff Protocol
- ADR-110: Agent Health Monitoring Layer
- ADR-111: Token Economics Instrumentation
- /checkpoint - Checkpoint management
- /health-status - Agent health monitoring
- /token-status - Token usage and budgets
- /cost-report - Cost attribution
- ralph-loop-monitor agent
Track: H (Framework) Task: H.8.6.2 Version: 1.0.0 Created: 2026-02-16