CodexPotter banner

CodexPotter screenshot

Platform npm CI License LinuxDo

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 workTM ; 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.

 YOUR PROMPT:
 Simplify the query engine by following ...
 │
 │
 codex: Work or review according to MAIN.md │
 ┌──────────────────────────┐ │
 │ │ ▼
 ┌─────────┴─────────┐ ┌──────────▼────────┐ ┌───────────────────┐
 │ CodexPotter │ │ codex │◄─────►│ MAIN.md │
 └─────────▲さんかく─────────┘ └──────────┬────────┘ └───────────────────┘
 │ │
 │ Work finished │
 └──────────────────────────┘

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.

✅ 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

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.

• 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

# Formatting
cargo fmt
# Lints
cargo clippy
# Tests
cargo nextest run
# Build
cargo build

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