💡 Why CodexPotter

CodexPotter continuously reconciles code base toward your instructed state (Ralph Wiggum pattern):

• 🤖 Codex-first — Codex subscription is all you need; no extra LLM needed.
• 🧭 Auto-review / reconcile — Review and polish multi rounds until fully aligned with your instruction.
• 💦 Clean-room — Use clean context in each round, avoid context poisoning, maximize IQ.
• 🎯 Attention is all you need — Keep you focused on crafting tasks, instead of cleaning up unfinished work.
• 🚀 Never worse than Codex — Drive Codex, nothing more; no business prompts which may not suit you.
• 🧩 Seamless integration — AGENTS.md, skills & MCPs just work™ ; opt in to improve plan / review.
• 🧠 File system as memory — Store instructions in files to resist compaction and preserve all details.
• 🪶 Tiny footprint — Use <1k tokens, ensuring LLM context fully serves your business logic.
• 📚 Built-in knowledge base — Keep a local KB as index so Codex learns project fast in clean contexts.

 

How does it work

                                                  𝒀𝑶𝑼𝑹 𝑷𝑹𝑶𝑴𝑷𝑻:
                                                  𝘚𝘪𝘮𝘱𝘭𝘪𝘧𝘺 𝘵𝘩𝘦 𝘲𝘶𝘦𝘳𝘺 𝘦𝘯𝘨𝘪𝘯𝘦 𝘣𝘺 𝘧𝘰𝘭𝘭𝘰𝘸𝘪𝘯𝘨 ...
                                                                 │
                                                                 │
     codex: Work or review according to MAIN.md                  │
            ┌──────────────────────────┐                         │
            │                          │                         ▼
  ┌─────────┴─────────┐     ┌──────────▼────────┐       ┌───────────────────┐
  │    CodexPotter    │     │       codex       │◄─────►│      MAIN.md      │
  └─────────▲─────────┘     └──────────┬────────┘       └───────────────────┘
            │                          │
            │      Work finished       │
            └──────────────────────────┘

 

⚡️ Getting started

1. Prerequisites: ensure you have codex CLI locally. CodexPotter drives your local codex to perform tasks.

2. Install CodexPotter via npm or bun:

# Install via npm
npm install -g codex-potter

# Install via bun
bun install -g codex-potter

3. Run: Start CodexPotter in your project directory, just like Codex:

# --yolo is recommended to be fully autonomous
codex-potter --yolo

⚠️ Note: Unlike Codex, every follow up prompt turns into a new task, not sharing previous contexts. Assign tasks to CodexPotter, instead of chat with it.

 

Tips

Prompt Examples

✅ tasks with clear goals or scopes:

• "port upstream codex's /resume into this project, keep code aligned"

✅ persist results to review in later rounds:

• "create a design doc for ... in DESIGN.md"

❌ interactive tasks with human feedback loops:

CodexPotter is not suitable for such tasks:

• Front-end development with human UI feedback
• Question-answering
• Brainstorming sessions

Polish Enhancement Rounds

GPT5.2 or GPT5.4 like introducing more fallback checks, which may not be what you want and may be amplified in CodexPotter's review process. To avoid that, try add instructions to AGENTS.md like:

- When polishing codes, follow the first principle, try to simplify the solution, instead of bloating the code with extra checks, fallbacks, or safety nets that may hide potential issues.
  The goal of polishing is to find real missing pieces, make the code more elegant, simple and efficient, not to add more layers of complexity.

 

Howto: Ask followup questions in codex

Just pass the project file to codex, like:

based on .codexpotter/projects/2026/03/18/1/MAIN.md,
please explain more about the root cause of the issue

 

Roadmap

• Skill popup
• Resume (history replay + continue iterating)
• Better handling of stream disconnect / similar network issues
• Agent-call friendly (non-interactive exec and resume)
• Interoperability with codex CLI sessions (for follow-up prompts)
• Better plan / user selection support
• Better sandbox support

 

Development

# Formatting
cargo fmt

# Lints
cargo clippy

# Tests
cargo nextest run

# Build
cargo build

 

License

This project is community-driven fork of openai/codex repository, licensed under the same Apache-2.0 License.