ralphex: The Extended Ralph Loop for Claude Code and codex

My notes

Summary

ralphex is an open-source (MIT) orchestrator that drives coding agents (Claude Code, codex, Copilot CLI, Cursor CLI) through a structured plan rather than writing code itself. It executes plan tasks one at a time in fresh agent sessions, commits after each, then runs a multi-phase, multi-agent code review. It is an “extended” version of Geoffrey Huntley’s ralph loop, adding plans, per-task session resets, and cross-model validation.

Key Insight

• Fresh session per task is the core trick - each plan task runs in a brand-new agent session to avoid context degradation over long features. This directly counters the quality decay that hits single long-running agent sessions.
• 5 parallel review agents with fixed specializations: quality (bugs/security), implementation correctness, testing, simplification (over-engineering), documentation. Spawned via Claude Code’s Task tool or codex’s native multi-agent spawn.
• Cross-model validation: an optional GPT-5 review phase (through codex) gives an independent second perspective. ralphex deliberately skips the external review when running --codex mode, because codex-reviewing-codex is same-model self-review with weak signal - a sharp observation about review quality.
• Four phases: execute (run tasks + validation commands like tests/linters, tick checkboxes, commit) -> 5-agent review -> optional GPT-5 external review (Claude evaluates findings, fixes, iterates until codex reports clean) -> final 2-agent pass on critical/major issues only, then plan moves to completed/.
• Review-only mode: ralphex --review runs the full review pipeline on existing branch changes regardless of how they were made (plan mode, manual edits, another agent). --external-only runs just the codex cross-validation pass.
• Config is layered and text-file based: global at ~/.config/ralphex/ (INI config + prompts/*.txt + agents/*.txt), overridable per-repo via .ralphex/. You can reference Claude Code agents you already have installed by name (e.g. qa-expert, go-test-expert) without duplicating them.
• Provider flexibility: --codex runs the entire pipeline natively on codex CLI as a first-class executor (path for teams on an OpenAI plan vs a Claude subscription); --pass-claude-md makes codex pick up CLAUDE.md as AGENTS.md. The codex-as-claude wrapper translates non-Claude agent output into ralphex’s stream-json protocol for any compatible streaming agent.
• Notifications on completion/failure via Telegram, Email, Slack, Webhook, or custom script. Optional containerized execution scopes the agent to the project only, not the whole system.