Super Ralph
Autonomous agentic loop plugin for Claude Code. Give it a query, choose oneshot or brainstorm, and walk away. It decomposes your request into tasks, writes tests first, implements with fresh sub-agents, self-debugs when stuck, and learns from every run.
Runtime Compatibility (Additive)
Super Ralph remains Claude-first and now includes additive Codex-compatible operating guidance.
| Concept | Claude | Codex |
|---|
| Interactive setup gates | AskUserQuestion | Ask one plain-text question at a time and wait for a reply |
| Sub-agent execution | Agent tool calls | Fresh Codex sessions/agent runs with the same role prompts |
| Parallel work | Multiple foreground Agent calls in one turn | Multiple foreground sessions in parallel (no detached/background jobs) |
| Skill discovery paths | ~/.claude/skills, .claude/skills | ~/.codex/skills, .codex/skills |
How It Works
You: "/super-ralph build me a REST API with auth and rate limiting"
Super Ralph:
0. Mode ── oneshot or brainstorm? (only difference: who decides — Ralph or you)
1. Environment ── detects AI runtime (Claude/Codex) and coding environment (language, framework, tools)
2. Brainstorm ── explore intent, scope, edge cases (user decides in brainstorm, Ralph decides in oneshot)
3. Intent ── priority, audience, lifespan → shapes judge strictness (always runs)
4. Tooling ── scans skills/agents, selects toolset (always runs)
5. Pre-Flight ── workspace scope + retry limit (always runs)
6. Plan ── decomposes query into independent tasks; tags each with complexity + model tier
7. Per Task ── test agent (always lightweight `sonnet`) writes strict tests → worker implements → tests validate
(simple tasks use lightweight `sonnet` agents; complex tasks use standard `opus` agents)
8. Debug ── if stuck at halfway mark, writes debug.md → fresh debugger analyzes cold → retry
9. Learn ── every outcome (pass or fail) logged to learnings.md
10. Merge ── combines all task outputs into one cohesive deliverable
11. Deliver ── summary report + merged output in workspace/final/
Both modes run the identical pipeline — brainstorm, intent, tooling, pre-flight, plan, execute, debug, learn, merge. In oneshot, Ralph makes every decision; in brainstorm, you do. After setup, the execution loop is fully autonomous either way. Failed tasks are auto-skipped and logged. No escalations, no confirmations, no interruptions.
Architecture
The Loop
User Query
-> Mode Selection: oneshot or brainstorm (single question)
-> Brainstorm: interactive Q&A (brainstorm) OR auto-analysis (oneshot)
-> Intent Profile: 3 questions (priority, audience, lifespan) → JUDGE_RUBRIC
-> Tooling: scan skills/agents, recommend toolset, user confirms
-> Pre-Flight: scope workspace + set MAX_RETRIES
-> Decompose: orchestrator breaks query into tasks directly (no separate agent)
-> Per Task (parallel if independent):
-> ralph-tester: write tests -> JUDGE: pass? (retry tester if fail, no limit)
-> ralph-worker: implement -> JUDGE: pass? (retry worker if fail, no limit) -> run tests
-> attempt 1..MAX_RETRIES/2: normal retries with failure context
-> at MAX_RETRIES/2: worker writes debug.md (full reasoning trail)
-> ralph-debugger: write fix plan -> JUDGE: pass? (retry debugger if fail)
-> attempt MAX_RETRIES/2+1..MAX_RETRIES: fresh worker follows fix plan
-> still failing at MAX_RETRIES? auto-skip, log to learnings
-> Pass -> capture learnings, clear debug.md
-> ralph-merger: combine outputs -> JUDGE: pass? (retry merger if fail) -> deliver
Agents
Super Ralph uses 5 specialized sub-agents, each dispatched as a fresh process with no shared context (prevents bias and sunk-cost reasoning). Task decomposition is handled directly by the orchestrator — it already has all the context it needs.
