Summary

CodexPotter automates the continuous reconciliation of a codebase towards a user-defined instructed state, acting as a "Ralph loop" executor. It targets developers using the codex CLI, offering an autonomous workflow that handles multi-round code reviews and polishing, freeing users to focus on task definition rather than iterative cleanup. The primary benefit is ensuring code consistency and adherence to instructions through automated, iterative refinement.

How It Works

This project implements a "Ralph loop" pattern, driving the codex CLI to continuously review and reconcile code. Its "Codex-first" philosophy relies solely on the codex subscription, eliminating the need for additional LLMs. Core to its design are auto-review and multi-round reconciliation processes within isolated "clean-room" contexts to prevent context poisoning and maximize model intelligence. Instructions and project state are persisted using the file system as memory, resisting compaction. A built-in local knowledge base allows codex to rapidly learn project specifics in these clean contexts.

Quick Start & Requirements

• Prerequisites: codex CLI must be installed locally.
• Installation: Install via npm (npm install -g codex-potter) or bun (bun install -g codex-potter).
• Execution: Run codex-potter --yolo in your project directory for fully autonomous operation.
• Note: CodexPotter executes discrete tasks; it is not a chat interface and does not share context between prompts by default.

Highlighted Details

• --xmodel (experimental): Leverages GPT-5.2 followed by GPT-5.4 for cross-review, potentially enhancing output quality.
• --yolo flag: Enables fully autonomous execution, bypassing sandbox limitations.
• File System as Memory: Persists instructions and details across sessions, preventing loss due to context window limitations.
• Built-in Knowledge Base: Indexes local project files for faster, context-aware learning by codex.

Maintenance & Community

This project is a community-driven fork of the openai/codex repository. The roadmap includes features such as skill popups, history replay and iteration continuation, agent-call friendliness, and improved interoperability with codex CLI sessions.

Licensing & Compatibility

Licensed under the Apache-2.0 License, consistent with its origin from the openai/codex repository. This license is generally permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

CodexPotter is designed for executing defined tasks and is unsuitable for interactive workflows like human UI feedback, question-answering, or brainstorming sessions, for which the base codex tool should be used. Each prompt initiates a new, isolated task; maintaining context across multiple rounds requires explicit file-based persistence. The codex CLI is a mandatory prerequisite.