CodexPotter

💡 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       │
            └──────────────────────────┘

✨ What's New

• May 01, 2026: We now have a V2 version for Codex Desktop users! Checkout v2 branch (experimental) 🎉

⚡️ 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.

⚠️ Note: CodexPotter is not a replacement for codex, because CodexPotter is a loop executor — it executes tasks instead of chatting with you. See below for details.

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, use codex instead:

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

Howto

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

Simpliy queue two tasks in CodexPotter, one is plan, one is implement, CodexPotter will execute one by one, for example:

Task prompt 1 (CodexPotter):

Analyze the codebase, research and design a solution for introducing subscription system.
Output plan to docs/subscription_design.md.

Your solution should meet the following requirements: ...

Do not implement the plan, just design a good and simple solution.

↑ Your existing facility to write good plans will be utilized, including skills, plan doc principles in AGENTS.md, etc. Writing plan to a file is CRITICAL so that the plan can be iterated multiple rounds and task 2 can pick it up.

Task prompt 2 (CodexPotter):

Implement according to docs/subscription_design.md

Make sure all user journeys are properly covered by e2e tests and pass.

If you even don't know what you are designing for, just discuss with codex to carry out a basic plan first, then use CodexPotter to continously polish and implement it.

Configuration

• Config File
• Hooks

Other Features

• --xmodel (experimental): Use gpt-5.2 first, then use gpt-5.5 to cross review gpt-5.2's work in later rounds. In clear coding tasks this may produce better results than only using gpt-5.2 or gpt-5.5.

• /yolo: Toggle whether YOLO (no sandbox) is enabled by default for all sessions.

• /list or ctrl+l: View all projects (tasks) and their results.

Roadmap

• [x] Skill popup
• [x] Resume (history replay + continue iterating)
• [x] Better handling of stream disconnect / similar network issues
• [x] Agent-call friendly (non-interactive exec and resume)
• [x] 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

Community & License

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