CodexPotter

💡 Why CodexPotter ($loop)

CodexPotter is a better /goal replacement —— it continuously reconciles code base toward your instructed goal or 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.

CodexPotter ($loop) vs /goal

CodexPotter always use fresh contexts for new rounds, thus:

• It avoids context rotting, producing better results by auto reviewing and fixing in later rounds
• It consumes more tokens
• More unattended: queue multiple $loop tasks and go to sleep, they will execute one by one

👀 How does it work

                                                𝒀𝑶𝑼𝑹 𝑷𝑹𝑶𝑴𝑷𝑻:
                                                𝘚𝘪𝘮𝘱𝘭𝘪𝘧𝘺 𝘵𝘩𝘦 𝘲𝘶𝘦𝘳𝘺 𝘦𝘯𝘨𝘪𝘯𝘦 𝘣𝘺 𝘧𝘰𝘭𝘭𝘰𝘸𝘪𝘯𝘨 ...
                                                                │
                                                                │
     codex: Continue working toward HANDOFF.md                  │
            ┌─────────────────────────┐                         │
            │                         │                         ▼
  ┌─────────┴─────────┐     ┌─────────▼────────┐       ┌───────────────────┐
  │    main agent     │     │     subagent     │◄─────►│      HANDOFF.md      │
  └─────────▲─────────┘     └─────────┬────────┘       └───────────────────┘
            │                         │
            │      Work finished      │
            └─────────────────────────┘

To learn more, see $loop Skill File.

⚡️ Getting started

1. Use the all-in-one wizard, it helps you set up necessary global gitignore and install skills via npx skills:

   npx codex-potter@next setup
   

   You will be prompted about what will be done, just confirm to continue:

   ➜  ~ npx codex-potter@next setup
   CodexPotter setup
   
   ✓ Skip: Ignore /.codexpotter in global gitignore
   ✓ Skip: Remove legacy subagent profile ~/.codex/agents/potter_worker.toml
   □ Todo: Install / update skill: npx --yes skills add --yes -g https://github.com/breezewish/CodexPotter/tree/v2 -a codex
   
   Continue? ● Yes / ○ No
   

2. Use $loop to trigger the workflow in Codex CLI or Codex Desktop:

   $loop Implement /ps endpoint according to docs/ps_design.md
   

All skills:

• $loop: run the reconciliation workflow

• $compact-kb: reorganize the local KB, make it more compact and efficient for later runs

Recommended Skills

See this repo to install. Use these skills to make CodexPotter more powerful and unattended.

• $codex-review: review code changes using fresh context, the same as Codex's /review, but you can use it with $loop. Example:

  $loop Use $codex-review to review code change in recent 2 days and fix all
  

• $simplify: review and simplify the code, the same as Claude Code's /simplify, but you can use it with $loop. Example:

  $loop Use $simplify for code change in recent 2 days
  

👀 Tips

Prompt Examples

✅ tasks with clear goals or scopes:

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

✅ persist results to review in later rounds:

• $loop 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

Simpliy queue two tasks via $loop, one is plan, one is implement, for example:

Task prompt 1:

$loop 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:

$loop Implement according to docs/subscription_design.md

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

Run this again to update skills and prompts to the latest version:

npx codex-potter@next setup

Roadmap

• Resume
• Interoperability with codex CLI sessions (for follow-up prompts)
• Better sandbox support
• Handling steer

License

• Apache-2.0 License