CodexPotter skill
CodexPotter loops Codex with a clean context each round until the code matches the goal, as a replacement for the built-in /goal.
- 636 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The skill edits project code over many rounds unattended, so a separate branch and a clean git tree are needed.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/codexpotterDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The skill edits project code over many rounds unattended, so a separate branch and a clean git tree are needed.
This is third-party code. Review the repository files before installing.
What it does
CodexPotter runs the `$loop` skill in Codex: it repeatedly reconciles the codebase with a stated goal using the Ralph Wiggum pattern. Each round starts with a clean context, so mistakes of earlier passes do not pollute reasoning. Instructions live in files rather than chat history and survive context compaction. A second skill, `$compact-kb`, compacts the local project knowledge base so Codex gets up to speed fast. A Codex subscription is enough, no extra model is needed. AGENTS.md, skills and MCP work as usual.
Who it is for. Codex CLI and Codex Desktop users who hand the agent a big task and walk away rather than babysit unfinished work.
Good fit when
- Implementing an endpoint from a ready design doc goes to a background run.
- Several tasks are queued overnight and run one by one.
- The built-in `/goal` loses the thread on long work because the context grows.
- After the first pass, code must be reviewed and fixed several more times on its own.
- Project knowledge accumulates in a local base for later rounds.
Not a fit when
- Tokens are limited: every clean-context round spends more than one long session.
- An interactive dialog with edits at every step is needed.
- Work happens in another agent rather than Codex.
Example request
$loop Implement the /ps endpoint per docs/ps_design.md, run the checks and bring the result in line with the document.Limitations
Every round starts from scratch, so token use is higher than a single session, as the README says. The skill runs unattended: it edits code and restarts itself, so launch it on a separate git branch with a clean tree. The setup wizard changes the global gitignore and installs skills through `npx skills add`, listing every step before it runs. Installation comes from the `v2` branch and the `next` tag, which makes it a prerelease build.
How to disable. Delete the `loop` and `compact-kb` skills from the Codex skills directory. Remove the `/.codexpotter` entry from the global gitignore by hand if it is no longer needed.
FAQ
How is it better than `/goal`?
Each round uses a clean context and automatic review, so quality does not decay from accumulated noise. The price is higher token use.
Is a separate model needed?
No. A Codex subscription is enough, CodexPotter only drives Codex and adds no business prompts of its own.
Which skills are installed?
Two: `$loop` runs the reconciliation cycle, `$compact-kb` compacts the local knowledge base.
Can tasks be queued?
Yes. The README describes several `$loop` tasks that run one after another unattended.
Where is progress stored?
In files such as `HANDOFF.md`: each round reads them anew, so details survive context compaction.
Discussion
No questions or reviews yet.
Related
SkillsA skill that links two to four open Codex CLI windows: one splits the work while the others execute, cross-check and deliver.
A Codex skill collection: phased planning, parallel subagents, documentation access, a browser, 51 hooks and ready agent roles.
Skill setting up Markdown file memory for Codex via AGENTS.md: profile, rules, lessons, errors and capability requests.
A Claude Code skill that hands implementation-heavy work to Codex CLI while Claude keeps planning, review and acceptance.
oh-my-codex
oh-my-codex (OMX)
A layer on top of Codex CLI: one flow from clarifying a task to verification, agent teams, hooks, a HUD and state in .omx/
A meta-skill for Codex: a vague task becomes a ready "/goal" command with verification, boundaries and pause conditions.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| CodexPotter (this card) | no | 636 | |
| Ralph Wiggum | no | 313 | a Ralph loop for Claude Code; CodexPotter works with Codex and refreshes context every round |
| Goal Workflow | no | 300 | a goal workflow; CodexPotter reruns review on its own until the code matches the goal |
README in short
The `$loop` skill brings a codebase to a stated state over rounds of self-review, with HANDOFF files instead of chat history.