Ralph Wiggum Architecture

Version: 1.0.0 Status: Active Audience: Contributors

Overview
Architecture Philosophy
Component Architecture
Module Layout
Key Types & Enums
Data Flow
State Persistence
Termination Criteria
Handoff Protocol
Governing ADRs
Related Components
References

Overview

The Ralph Wiggum pattern is an autonomous agent execution strategy that replaces single long-running contexts with fresh-context iterations, maintaining quality and avoiding context window degradation.

Core Insight

"Single-context loops degrade; fresh-context iterations maintain quality."

— Geoffrey Huntley's Ralph Explanation

Named after The Simpsons character, Ralph Wiggum embodies persistence through iteration — the agent continues indefinitely until the goal is achieved or budget/health limits are reached.

Key Characteristics

Fresh context per iteration: Each iteration spawns a new agent with clean context window
Explicit state persistence: State stored externally in database (not in context)
Structured handoff protocol: Checkpoints enable seamless continuation across iterations
Health monitoring: Graduated intervention (nudge → escalate → terminate)
Token economics: Budget enforcement with 15x multi-agent multiplier awareness
Self-healing: Automatic recovery from checkpoints on failure

Architecture Philosophy

Why Ralph Wiggum Works

Traditional autonomous loops suffer from:

Context degradation: Long-running contexts accumulate noise and lose focus
Implicit state: Critical state buried in context, lost on crash
No recovery: Failures require manual intervention
Unpredictable costs: No budget enforcement, surprise overruns

Ralph Wiggum solves these by:

Fresh context quality: Each iteration starts clean, maintains clarity
Explicit checkpoints: State persisted to database with ACID guarantees
Automatic recovery: Resume from last valid checkpoint without human intervention
Cost control: Token economics service enforces budgets, throttles on approach

CODITECT Advantage

CODITECT's database-backed event-driven architecture is architecturally superior to git-file-based state management used by other Ralph implementations:

Aspect	CODITECT (Database)	Git-File Approach
Consistency	ACID guarantees	Eventual consistency
Concurrency	Row-level locking	File locks, conflicts
Multi-tenant	PostgreSQL RLS	Manual isolation
Recovery	Transaction rollback	Git history traversal
Performance	< 100ms checkpoint writes	Seconds for git commit
Compliance	PostgreSQL audit trail	Git log (incomplete)

Component Architecture

The Ralph Wiggum system consists of five core services orchestrated by the LoopOrchestrator:

┌────────────────────────────────────────────────────────────────┐
│                      LoopOrchestrator                          │
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐│
│  │  Checkpoint      │  │  Health          │  │  Token       ││
│  │  Service         │  │  Monitoring      │  │  Economics   ││
│  │  (ADR-108)       │  │  Service         │  │  Service     ││
│  │                  │  │  (ADR-110)       │  │  (ADR-111)   ││
│  │  • Create        │  │  • Heartbeat     │  │  • Budget    ││
│  │  • Read          │  │  • State machine │  │  • Throttle  ││
│  │  • Handoff       │  │  • Intervention  │  │  • Forecast  ││
│  │  • Recovery      │  │  • Circuit break │  │  • Alert     ││
│  └────────┬─────────┘  └────────┬─────────┘  └──────┬───────┘│
│           │                     │                    │        │
│  ┌────────┴─────────────────────┴────────────────────┴──────┐ │
│  │              Termination Criteria                        │ │
│  │  budget | iterations | health | duration | progress     │ │
│  └──────────────────────────────────────────────────────────┘ │
└────────────────────────────┬───────────────────────────────────┘
                             │
                    ┌────────┴────────┐
                    │  Agent Spawns   │
                    │ (fresh context) │
                    └─────────────────┘

Service Responsibilities

Service	Responsibility	Key Operations
CheckpointService	State persistence, handoff protocol	`create_checkpoint()`, `get_latest_checkpoint()`, `generate_continuation_prompt()`
HealthMonitoringService	Stuck detection, intervention	`check_health()`, `nudge_agent()`, `circuit_breaker.trip()`
TokenEconomicsService	Budget enforcement, cost tracking	`record_consumption()`, `check_budget()`, `forecast_cost()`
TerminationCriteria	Loop termination evaluation	`evaluate()` → 7 criteria in priority order
LoopOrchestrator	Lifecycle coordination, iteration management	`initialize()`, `plan_iteration()`, `record_iteration()`, `complete()`

Module Layout

scripts/core/ralph_wiggum/
├── __init__.py                # Package exports (v1.1.0)
│
├── checkpoint_protocol.py     # ADR-108: Checkpoint and Handoff Protocol
│   ├── Checkpoint            # Full checkpoint schema
│   ├── CheckpointMetadata    # ID, task, agent, iteration
│   ├── ExecutionState        # Phase, completed/pending/blocked items
│   ├── ExecutionPhase        # PLANNING, IMPLEMENTING, TESTING, REVIEWING, HANDOFF, COMPLETE
│   ├── ContextSummary        # Decisions, assumptions, constraints
│   ├── CheckpointMetrics     # Token counts, tool calls, test results
│   ├── RecoveryInfo          # Rollback instructions, continuation prompt
│   ├── CheckpointService     # Create, read, update checkpoints
│   ├── HandoffTrigger        # CONTEXT_THRESHOLD, PHASE_COMPLETE, ERROR_THRESHOLD, etc.
│   └── HandoffProtocol       # should_handoff(), generate_continuation_prompt()
│
├── health_monitoring.py       # ADR-110: Health Monitoring Layer
│   ├── HealthState           # HEALTHY, DEGRADED, STUCK, FAILING, TERMINATED
│   ├── HeartbeatPayload      # Heartbeat message schema
│   ├── AgentHealth           # Per-agent health tracking
│   ├── CircuitBreakerState   # CLOSED, OPEN, HALF_OPEN
│   ├── CircuitBreaker        # Failure circuit breaker
│   ├── HealthMonitoringService # Health checks, nudges, escalation
│   ├── InterventionLevel     # NUDGE, ESCALATE, TERMINATE
│   └── RecoveryService       # Checkpoint-based recovery
│
├── token_economics.py         # ADR-111: Token Economics Instrumentation
│   ├── TokenRecord           # Single token consumption record
│   ├── TokenConsumption      # Input, output, cache tokens
│   ├── CostBreakdown         # Per-token-type costs
│   ├── Budget                # Budget configuration
│   ├── BudgetContext         # Organization/project/task budget hierarchy
│   ├── BudgetCheckResult     # Pre-call budget check result
│   ├── BudgetAction          # ALLOW, THROTTLE, DENY, ALERT_ONLY
│   ├── EfficiencyMetrics     # Tokens per tool call, cache hit rate
│   └── TokenEconomicsService # Record, check, forecast
│
├── browser_automation.py      # ADR-109: QA Agent Browser Automation
│   ├── FlowStep              # User flow step definition
│   ├── FlowStepAction        # NAVIGATE, CLICK, TYPE, WAIT, VERIFY
│   ├── PageVerificationResult # Visual regression check result
│   ├── FlowVerificationResult # Full flow verification
│   ├── VisualCompareResult   # Screenshot diff result
│   ├── BrowserAutomationConfig # Playwright configuration
│   └── QAAgentBrowserTools   # Browser automation methods
│
├── loop_orchestrator.py       # H.8.6: Loop Orchestration
│   ├── LoopState             # INITIALIZING, RUNNING, PAUSED, HANDOFF, COMPLETING, COMPLETED, FAILED, TERMINATED
│   ├── IterationResult       # Result from single iteration
│   ├── LoopConfig            # Max iterations, cost, duration, thresholds
│   ├── LoopStatus            # Current loop status (persisted to status.json)
│   ├── LoopOrchestrator      # Main orchestrator class
│   └── run_loop()            # Convenience function
│
└── termination_criteria.py    # H.8.6.5: Termination Criteria
    ├── TerminationReason     # GOAL_ACHIEVED, MAX_ITERATIONS, BUDGET_EXHAUSTED, etc.
    ├── TerminationResult     # Evaluation result
    └── TerminationCriteria   # evaluate() with 7 criteria

Key Types & Enums

HealthState

Agent operational status:

class HealthState(Enum):
    HEALTHY = "healthy"         # Making progress, no issues
    DEGRADED = "degraded"       # Warning signs (slow, high errors)
    STUCK = "stuck"             # No progress for >30 minutes
    FAILING = "failing"         # Error loop, circuit breaker tripped
    TERMINATED = "terminated"   # Stopped

InterventionLevel

Graduated intervention strategy:

class InterventionLevel(Enum):
    NUDGE = "nudge"           # Soft reminder in context
    ESCALATE = "escalate"     # Alert orchestrator
    TERMINATE = "terminate"   # Force stop, recover from checkpoint

ExecutionPhase

Task execution phases:

class ExecutionPhase(Enum):
    PLANNING = "planning"
    IMPLEMENTING = "implementing"
    TESTING = "testing"
    REVIEWING = "reviewing"
    HANDOFF = "handoff"
    COMPLETE = "complete"

HandoffTrigger

Conditions that trigger handoff between iterations:

class HandoffTrigger(Enum):
    CONTEXT_THRESHOLD = "context_threshold"       # Context > 70%
    PHASE_COMPLETE = "phase_complete"             # Phase boundary
    ERROR_THRESHOLD = "error_threshold"           # 3+ consecutive errors
    EXPLICIT_REQUEST = "explicit_request"         # Agent requested handoff
    TOKEN_BUDGET = "token_budget"                 # Budget > 80%
    TIMEOUT = "timeout"                           # Duration exceeded

BudgetAction

Budget enforcement actions:

class BudgetAction(Enum):
    ALLOW = "allow"           # Proceed normally
    THROTTLE = "throttle"     # Delay calls (exponential backoff)
    DENY = "deny"             # Block call (hard limit)
    ALERT_ONLY = "alert_only" # Warn but proceed

LoopState

Loop execution states:

class LoopState(Enum):
    INITIALIZING = "initializing"
    RUNNING = "running"
    PAUSED = "paused"
    HANDOFF = "handoff"
    COMPLETING = "completing"
    COMPLETED = "completed"
    FAILED = "failed"
    TERMINATED = "terminated"

TerminationReason

Reasons for loop termination (checked in priority order):

class TerminationReason(Enum):
    GOAL_ACHIEVED = "goal_achieved"             # Task complete
    MAX_ITERATIONS = "max_iterations"           # Iteration limit reached
    BUDGET_EXHAUSTED = "budget_exhausted"       # Cost >= max_cost
    MAX_DURATION = "max_duration"               # Time limit exceeded
    HEALTH_FAILURE = "health_failure"           # Agent in FAILING/TERMINATED state
    CONSECUTIVE_ERRORS = "consecutive_errors"   # >= 3 consecutive errors
    CIRCUIT_BREAKER_OPEN = "circuit_breaker_open" # Circuit breaker tripped
    EXPLICIT_STOP = "explicit_stop"             # Manual termination
    NO_PROGRESS = "no_progress"                 # 3+ iterations, no completed items

Data Flow

Loop Lifecycle

1. INITIALIZATION
   ├── LoopOrchestrator.initialize(goal, config)
   ├── Create LoopStatus in ~/PROJECTS/.coditect-data/ralph-loops/{loop_id}/status.json
   ├── Set state = INITIALIZING
   └── Load config (max_iterations, max_cost, model, agent_type)

2. ITERATION PLANNING
   ├── LoopOrchestrator.plan_iteration(iteration)
   ├── Get latest checkpoint (if iteration > 1)
   ├── Generate continuation prompt
   └── Return plan (agent_type, prompt, phase, budget_remaining)

3. AGENT EXECUTION
   ├── Spawn agent (Task tool or /ralph-loop command)
   ├── Agent executes with fresh context window
   ├── HealthMonitoringService monitors heartbeat
   ├── TokenEconomicsService tracks consumption
   └── Agent completes work or encounters error

4. CHECKPOINT CREATION
   ├── CheckpointService.create_checkpoint(task_id, agent_id, execution_state)
   ├── Generate checkpoint_id (UUID v7, time-ordered)
   ├── Persist to database (local SQLite + cloud PostgreSQL sync)
   ├── Calculate SHA-256 hash for integrity
   └── Store checkpoint_id in LoopStatus.last_checkpoint_id

5. ITERATION RECORDING
   ├── LoopOrchestrator.record_iteration(result)
   ├── Update LoopStatus (current_iteration, total_tokens, total_cost)
   ├── Append IterationResult to status.iterations[]
   ├── TokenEconomicsService.record_consumption()
   └── Persist status.json

6. TERMINATION EVALUATION
   ├── TerminationCriteria.evaluate()
   ├── Check 7 criteria in priority order:
   │   1. Circuit breaker open
   │   2. Health failure (FAILING/TERMINATED)
   │   3. Consecutive errors >= threshold
   │   4. Budget exhausted
   │   5. Max iterations reached
   │   6. Max duration exceeded
   │   7. No progress (3+ iterations, no completed items)
   └── Return TerminationResult (should_terminate, reason, details)

7. HANDOFF CHECK
   ├── LoopOrchestrator.check_handoff()
   ├── Calculate context_utilization, budget_used
   ├── HandoffProtocol.should_handoff()
   └── Return HandoffTrigger or None

8. COMPLETION
   ├── If should_terminate: LoopOrchestrator.complete(reason)
   ├── Set state = COMPLETED/FAILED
   ├── Create final checkpoint (phase = COMPLETE)
   ├── Persist status.json
   ├── Save report.json
   └── Log completion

Handoff Trigger Thresholds

Trigger	Threshold	Action
`CONTEXT_THRESHOLD`	Context > 70%	Initiate handoff to fresh agent
`ERROR_THRESHOLD`	3 consecutive errors	Handoff with error context
`TOKEN_BUDGET_THRESHOLD`	Budget used > 80%	Handoff with budget warning
`PHASE_COMPLETE`	Phase boundary crossed	Handoff to next phase agent
`EXPLICIT_REQUEST`	Agent requests handoff	Immediate handoff

Intervention Sequence

LEVEL 1: NUDGE (soft)
├── Trigger: HealthState = STUCK (no checkpoint update > 30 min)
├── Action: Inject reminder into agent context
│   "REMINDER: You have been working for {duration} without checkpoint update.
│    Please either update progress, request handoff, or report blockers."
├── Wait: 10 minutes
└── Escalate if no response

LEVEL 2: ESCALATE (orchestrator)
├── Trigger: 3 nudges unsuccessful
├── Action:
│   ├── Alert orchestrator
│   ├── Log escalation event
│   └── Prepare recovery options
├── Orchestrator decision:
│   ├── Allow more time
│   ├── Force handoff
│   └── Terminate and recover
└── Wait: Orchestrator response or 15 min timeout

LEVEL 3: TERMINATE (forced)
├── Trigger: Escalation timeout or orchestrator decision
├── Action:
│   ├── Force agent termination
│   ├── Save partial state to checkpoint
│   ├── Clean up resources
│   └── Initiate recovery from last valid checkpoint
└── Post-action: RecoveryService or human escalation

State Persistence

Storage Location

All loop state persists to:

~/PROJECTS/.coditect-data/ralph-loops/{loop_id}/
├── status.json          # LoopStatus (iterations, cost, errors)
└── report.json          # Final execution report (on completion)

LoopStatus Schema

{
  "loop_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": "H.8.7.2",
  "project_id": "PILOT",
  "state": "running",
  "goal": "Implement feature X with tests",
  "config": {
    "max_iterations": 10,
    "max_cost": 50.0,
    "max_duration_minutes": 120,
    "context_threshold": 0.70,
    "agent_type": "senior-architect",
    "model": "claude-opus-4-6"
  },
  "current_iteration": 3,
  "iterations": [
    {
      "iteration": 1,
      "agent_id": "ralph-loop-550e8400-iter-1",
      "started_at": "2026-02-16T10:00:00Z",
      "completed_at": "2026-02-16T10:15:00Z",
      "phase": "planning",
      "completed_items": ["Created project structure"],
      "pending_items": ["Implement core logic", "Add tests"],
      "errors": [],
      "checkpoint_id": "01JCKS3M...",
      "input_tokens": 12500,
      "output_tokens": 3400,
      "cost": 2.85,
      "handoff_trigger": "",
      "health_state": "healthy"
    }
  ],
  "total_input_tokens": 35000,
  "total_output_tokens": 9800,
  "total_cost": 8.25,
  "started_at": "2026-02-16T10:00:00Z",
  "completed_at": "",
  "termination_reason": "",
  "last_checkpoint_id": "01JCKS3M...",
  "errors": []
}

Checkpoint Storage

Checkpoints persist to dual-database architecture (ADR-089, ADR-112):

Local: SQLite at ~/.coditect-data/context-storage/org.db (offline operation)
Cloud: PostgreSQL with Row-Level Security (multi-tenant isolation)
Sync: Cursor-based polling (ADR-053)

Termination Criteria

The TerminationCriteria.evaluate() method checks 7 criteria in priority order:

1. Circuit Breaker Open

if circuit_breaker_open:
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.CIRCUIT_BREAKER_OPEN,
        details="Too many failures — circuit breaker tripped"
    )

2. Health Failure

if last_health_state in ("failing", "terminated"):
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.HEALTH_FAILURE,
        details=f"Agent health state: {last_health_state}"
    )

3. Consecutive Errors

if consecutive_errors >= max_consecutive_errors:  # Default: 3
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.CONSECUTIVE_ERRORS,
        details=f"{consecutive_errors} consecutive errors"
    )

4. Budget Exhausted

if total_cost >= max_cost and max_cost > 0:
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.BUDGET_EXHAUSTED,
        details=f"${total_cost:.2f} >= ${max_cost:.2f} budget"
    )

5. Max Iterations

if current_iteration >= max_iterations:
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.MAX_ITERATIONS,
        details=f"Iteration {current_iteration} >= {max_iterations} max"
    )

6. Max Duration

if duration_minutes >= max_duration_minutes and max_duration_minutes > 0:
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.MAX_DURATION,
        details=f"{duration_minutes:.0f} min >= {max_duration_minutes} max"
    )

7. No Progress

if current_iteration >= 3 and not completed_items:
    return TerminationResult(
        should_terminate=True,
        reason=TerminationReason.NO_PROGRESS,
        details=f"No completed items after {current_iteration} iterations"
    )

If none of these criteria are met, the loop continues.

Handoff Protocol

Handoff Decision

HandoffProtocol.should_handoff() returns a HandoffTrigger when:

Condition	Threshold	Trigger
Context utilization	> 70%	`CONTEXT_THRESHOLD`
Consecutive errors	>= 3	`ERROR_THRESHOLD`
Token budget used	> 80%	`TOKEN_BUDGET`
Phase complete flag	True	`PHASE_COMPLETE`

Continuation Prompt Generation

HandoffProtocol.generate_continuation_prompt(checkpoint) creates a structured prompt for the next iteration:

## Handoff from Iteration {n}

**Phase:** {phase}
**Last Agent:** {agent_id}
**Checkpoint:** {checkpoint_id}

### Completed
- {item1}
- {item2}

### Pending
- {item3}
- {item4}

### Blocked
- {item5}: {reason}

### Key Decisions
- {decision1}
- {decision2}

### Next Steps
{continuation_prompt from checkpoint.recovery.continuation_prompt}

This prompt is injected into the next agent's system prompt, giving it full context without carrying over the previous agent's conversation history.

Governing ADRs

ADR	Title	Focus
ADR-108	Agent Checkpoint and Handoff Protocol	Checkpoint schema, handoff triggers, recovery protocol
ADR-109	QA Agent Browser Automation	Browser automation for visual regression testing
ADR-110	Agent Health Monitoring Layer	Health states, intervention levels, circuit breaker
ADR-111	Token Economics Instrumentation	Budget hierarchy, cost tracking, forecasting
ADR-112	Ralph Wiggum Database Architecture	Consolidates database decisions (ADR-002, ADR-089)

Commands

/ralph-loop — Start an autonomous loop from CLI
/checkpoint — Manually create a checkpoint
/health-status — View current agent health
/token-status — View token consumption and budget
/cost-report — Generate cost report for task/project

Agents

ralph-loop-monitor — Monitor agent that watches running loops, performs health checks, sends nudges

Skills

ralph-wiggum-orchestration — End-to-end Ralph loop execution patterns
checkpoint-management — Checkpoint creation and recovery
health-monitoring-patterns — Health check and intervention patterns
token-economics-patterns — Budget enforcement and cost optimization

References

External References

Geoffrey Huntley's Ralph Explanation — Original Ralph Wiggum concept
Anthropic: Effective Harnesses for Long-Running Agents — Multi-agent patterns

Internal References

Ralph Wiggum Analysis — Community analysis
CODITECT Impact Analysis — CODITECT integration
IMPL-REQ-001 — Checkpoint implementation requirements
IMPL-REQ-003 — Health monitoring implementation
IMPL-REQ-004 — Token economics implementation

Package Exports

All Ralph Wiggum components are exported from scripts.core.ralph_wiggum:

from scripts.core.ralph_wiggum import (
    # Loop orchestration
    LoopOrchestrator, LoopConfig, LoopStatus, run_loop,
    # Checkpoint protocol
    CheckpointService, HandoffProtocol, ExecutionPhase,
    # Health monitoring
    HealthMonitoringService, HealthState, CircuitBreaker,
    # Token economics
    TokenEconomicsService, BudgetAction, EfficiencyMetrics,
    # Termination
    TerminationCriteria, TerminationReason, TerminationResult,
)

Version: 1.0.0 Created: February 16, 2026 Last Updated: February 16, 2026 Maintainer: CODITECT Framework Team

Table of Contents​

Overview​

Core Insight​

Key Characteristics​

Architecture Philosophy​

Why Ralph Wiggum Works​

CODITECT Advantage​

Component Architecture​

Service Responsibilities​

Module Layout​

Key Types & Enums​

HealthState​

InterventionLevel​

ExecutionPhase​

HandoffTrigger​

BudgetAction​

LoopState​

TerminationReason​

Data Flow​

Loop Lifecycle​

Handoff Trigger Thresholds​

Intervention Sequence​

State Persistence​

Storage Location​

LoopStatus Schema​

Checkpoint Storage​

Termination Criteria​

1. Circuit Breaker Open​

2. Health Failure​

3. Consecutive Errors​

4. Budget Exhausted​

5. Max Iterations​

6. Max Duration​

7. No Progress​

Handoff Protocol​

Handoff Decision​

Continuation Prompt Generation​

Governing ADRs​

Related Components​

Commands​

Agents​

Skills​

References​

External References​

Internal References​

Package Exports​

Table of Contents