Ralph for Codex: Adding a Structured Delivery Loop to OpenAI Codex

As a powerful AI programming assistant, OpenAI Codex has limitations in its one-time interaction mode when handling large-scale tasks (such as complete feature implementation, multi-file modifications, PRD-driven iterative tasks). Ralph is an enhanced autonomous agent framework designed for Codex. It provides Codex with a better orchestration structure through a PRD-driven structured development workflow (including task graph planning, context budget execution, validation gates, and state persistence). Its core philosophy is "Codex does execution, Ralph does orchestration", with the goal of improving the completion rate and predictability of complex tasks.

OpenAI Codex excels at real-time code editing and quick answers, but its linear one-time process struggles with feature-level development, PRD tasks spanning multiple iterations, and high-risk work requiring explicit validation or state recovery. Ralph was created to address these issues. It retains the core ideas of the original Ralph (persistent state, bounded work, fresh execution, completion pressure) but has been restructured around Codex to become a product-grade tool.

Ralph's key features include: 1. Project-level state persistence (files like state.json, tasks.json, progress.md under the .ralph/ directory record state and task graphs); 2. Context budget management (prevents task scope creep, blocks overly broad tasks and pushes them back to the planning phase); 3. Validation as a hard gate (executes validation commands, stores evidence, and handles results with branching logic: continue on success, retry, or block); 4. Intelligent routing (routes prompts to commands like plan/run/verify/status based on intent and state).

Ralph is suitable for feature-level/PRD-driven development, iterative tasks, important work requiring validation, high-risk tasks needing state recovery, and bounded tasks that can be split. Usage methods include: global installation (npm install -g @openai/codex openai-ralph-codex), daily use (hooks automatically route relevant prompts like "plan this feature" or "continue blocked work"), project initialization (ralph init generates the .ralph directory, ralph plan generates the task graph). It supports starting from scratch for new projects or integrating into existing projects midway.

Ralph converts PRDs into task graphs (tasks.json) containing metadata such as retry counts, dependency information, context files, estimated load, and split suggestions. The scheduler selects tasks suitable for the current context budget. Example workflows: 1. New project: User prompts to create a PRD → guides generation of the .ralph directory → generates PRD and task graph → executes; 2. Resume blocked work: Load state → check blocking reason → choose to resume or re-plan.

Ralph for Codex is a Codex-native improved version of the original Ralph model. It retains core advantages while optimizing the structure (project local state, PRD→task graph, disk-persisted evidence, explicit retry/block/resume behaviors, etc.). It demonstrates a practical evolution direction for AI programming assistance: not to replace Codex, but to add structure when needed. As AI tools evolve toward feature delivery, orchestration layers like Ralph may become part of the standard toolchain. Project GitHub link: JungyuOO/openai-ralph-codex.