Ralph Supervisor Pattern

Ralph implements an autonomous coding loop where Claude acts as supervisor and Codex executes implementation work. Named after the pattern from openclaw-codex-ralph.

Core Philosophy

Traditional AI sessions accumulate context and drift. Ralph uses:

Fresh context per iteration - Each Codex session starts clean
Git-backed persistence - Completed work lives in commits
Validation gates - Tests must pass before progression
Progress carryover - Learnings flow forward (last 2000 chars)

Architecture

┌──────────────────────────────────────────────────────────┐
│                    RALPH ARCHITECTURE                     │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │   Claude    │ spawns  │   Codex     │                 │
│  │ (Supervisor)│ ──────► │ (Executor)  │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │ plans/reviews         │ implements              │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │  prd.json   │         │   Code +    │                 │
│  │  (stories)  │         │   Tests     │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │                       │ validates               │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │progress.txt │◄────────│  npm test   │                 │
│  │ (learnings) │ logs    │ typecheck   │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │                       │ on success              │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │  Hivemind   │         │ Git Commit  │                 │
│  │ (semantic)  │         │ (persist)   │                 │
│  └─────────────┘         └─────────────┘                 │
│                                                          │
└──────────────────────────────────────────────────────────┘

Iteration Lifecycle

1. Read PRD → Find next pending story (by priority)
2. Load progress.txt + AGENTS.md for context
3. Build iteration prompt for Codex
4. Spawn Codex (codex exec --full-auto)
5. Run validation command
6. If success:
   - Mark story.status = "passed"
   - Append to progress.txt
   - Git commit
7. If failure:
   - Log failure details
   - Keep story for retry
8. Repeat until all stories pass or limits hit

Story Structure

json

{
  "id": "story-1234567890",
  "title": "Add user authentication",
  "description": "Implement login/logout with JWT...",
  "priority": 1,
  "status": "pending",
  "validation_command": "npm test && npm run typecheck",
  "acceptance_criteria": [
    "JWT token generation works",
    "Refresh token flow implemented"
  ],
  "attempts": 0,
  "files_touched": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

PRD Structure

json

{
  "version": "1.0",
  "project_name": "My Feature",
  "description": "Adding OAuth support...",
  "stories": [...],
  "metadata": {
    "created_at": "...",
    "last_iteration": "...",
    "total_iterations": 5,
    "total_stories_completed": 3
  }
}

Supervisor Best Practices

Story Design

Granular scope - Each story should fit in one Codex context
Clear acceptance criteria - Specific, testable requirements
Proper validation - Tests that actually verify the work
Priority ordering - Dependencies first (lower number = higher priority)

Review Process

┌─────────────────────────────────────────────────────────────┐
│                    REVIEW CHECKLIST                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  □ Tests pass (validation_command succeeded)                │
│  □ Acceptance criteria met                                  │
│  □ Code quality acceptable                                  │
│  □ No security issues introduced                            │
│  □ Integration with existing code correct                   │
│                                                             │
│  If YES to all → ralph_review({ approve: true })            │
│  If NO to any  → ralph_review({ approve: false,             │
│                                 feedback: "Specific issue"})│
│                                                             │
└─────────────────────────────────────────────────────────────┘

Knowledge Persistence

After completing a project, store learnings:

typescript

hivemind_store({
  information: "OAuth implementation: Used refresh token rotation pattern with 7-day expiry. Key gotcha: must invalidate old refresh token on use.",
  tags: "oauth,auth,tokens,patterns",
  confidence: 0.9
})

Configuration

Parameter	Default	Description
`model`	`gpt-5.3-codex`	Codex model to use
`sandbox`	`workspace-write`	Sandbox mode
`max_iterations`	`20`	Loop limit
`auto_commit`	`true`	Commit on success
`progress_context_limit`	`2000`	Chars of progress in prompt
`default_validation`	`npm run typecheck; npm test`	Fallback validation

Events Emitted

Event	When
`ralph:init`	Project initialized
`ralph:story:added`	Story added to PRD
`ralph:iteration:start`	Iteration begins
`ralph:iteration:complete`	Iteration ends
`ralph:loop:start`	Loop begins
`ralph:loop:iteration`	Each loop iteration
`ralph:loop:complete`	Loop finishes
`ralph:loop:error`	Loop error
`ralph:review:approved`	Work approved
`ralph:review:rejected`	Work rejected

Error Handling

Error	Recovery
Codex timeout	Retry with longer timeout
Validation fail	Fix in next iteration
No stories left	All complete, exit
Max iterations	Report remaining work

Comparison: Ralph vs Swarm

Aspect	Ralph	Swarm
Executor	Codex	Claude workers
Parallelism	Sequential	Parallel
Context	Fresh per iteration	Shared via hivemind
Review	Supervisor reviews each	Coordinator reviews all
Best for	Complex sequential tasks	Independent parallel tasks

Search AI Tools

ralph-supervisor

Install this agent skill to your Project

SKILL.md