🪶 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.
⚠️ 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: 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
Howto: Plan and execute
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.
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)
