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