feat(ralph-loop): add persistent iterative AI development loops for Codex

[Andersonlimahw]

Summary

This Pull Request introduces the Ralph Loop plugin for Codex. Adapted from the "Ralph Wiggum" technique, this plugin enables persistent, bounded, and self-improving AI development loops within both the Codex CLI and Codex App.

It provides a robust runtime for long-running tasks, allowing Codex to execute iterative cycles with state management, progress tracking, and automated summaries.

Core Features

• Persistent State: Stores loop history, prompts, and events in local .codex/ralph-loop/ storage.
• Iteration Control: Configurable bounded loops to prevent runaway token usage.
• Codex Integration: Native support via .codex-plugin/plugin.json and shell adapters.
• Claude Code Compatibility: Maintains full compatibility with Claude Code hooks and skills.
• Doctor Command: Integrated diagnostic tool to verify environment setup.

Architecture

The following diagram illustrates the interaction between the Codex CLI, the Ralph Loop runtime, and the local filesystem:

graph TD
    A[Codex CLI/App] -->|Exec Command| B(Ralph Codex Script)
    B -->|Check State| C{Active Loop?}
    C -->|No| D[Initialize Local DB]
    C -->|Yes| E[Resume Iteration]
    D --> F[Execute Codex Exec]
    E --> F
    F -->|Capture Output| G[State Manager]
    G -->|Update JSON| H[(.codex/ralph-loop/)]
    G -->|Detect Goal| I{Task Finished?}
    I -->|No| B
    I -->|Yes| J[Generate Summary]
    J --> A

Loading

Changes

• New Plugin Structure: Added plugins/ralph-loop/ with dedicated commands, hooks, and skills.
• Plugin Manifests: Implemented .codex-plugin/plugin.json for Codex App integration and .claude-plugin/plugin.json for Claude Code.
• Core Library: Developed scripts/lib/ including state.mjs, codex-exec.mjs, and doctor.mjs.
• Marketplace Integration: Updated .agents/plugins/marketplace.json to include Ralph Loop.
• Documentation: Added detailed README.md and adaptation plans in docs/ai/plans/.

Testing

Comprehensive test suite implemented using Node.js test runner:

• args.test.mjs: CLI argument parsing.
• state.test.mjs: Local state persistence and JSON DB integrity.
• runner.test.mjs: E2E execution flow with mocked Codex binary.
• promise.test.mjs: Completion detection logic.

Impact

This is a feature addition. It does not break existing functionality but introduces a new set of commands (ralph-loop, ralph-status, ralph-doctor, cancel-ralph) available to the Codex environment.

[Keesan12]

Try martinloop its a governed runtime budget and control harness for loops and autonomous agents that solves a lot of the ralph loops probems with consistency and drift

https://github.com/Keesan12/martin-loop/