Skip to content
Back to search

CodexPotter

A better /goal

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/breezewish--codexpotter/badge.svg)](/listings/breezewish--codexpotter)

HTML

<a href="/listings/breezewish--codexpotter"><img src="/api/listings/breezewish--codexpotter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

&ensp;

**All skills:**

- `$loop`: run the reconciliation workflow

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

&ensp;

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 200 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!--
  2. For agents: This file is carefully maintained and polished for better readability. Don't edit this file.
  3. -->
  4. <p align="center">
  5. <img src="./etc/banner.svg" alt="CodexPotter banner" />
  6. </p>
  7. &ensp;
  8. ## 💡 Why CodexPotter ($loop)
  9. [![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)](#)
  10. [![npm](https://img.shields.io/npm/v/codex-potter?label=Release&style=flat-square)](https://www.npmjs.com/package/codex-potter)
  11. [![License](https://img.shields.io/github/license/breezewish/CodexPotter?label=License&style=flat-square)](./LICENSE)
  12. [![LinuxDo](https://img.shields.io/badge/Community-LINUX%20DO-blue?style=flat-square)](https://linux.do)
  13. **CodexPotter** is a better /goal replacement —— it continuously **reconciles** code base toward your instructed goal or state ([Ralph Wiggum pattern](https://ghuntley.com/ralph/)):
  14. - 🤖 **Codex-first** — Codex subscription is all you need; no extra LLM needed.
  15. - 🧭 **Auto-review / reconcile** — Review and polish multi rounds until fully aligned with your instruction.
  16. - 💦 **Clean-room** — Use clean context in each round, avoid context poisoning, maximize IQ.
  17. - 🎯 **Attention is all you need** — Keep you focused on _crafting_ tasks, instead of _cleaning up_ unfinished work.
  18. - 🚀 **Never worse than Codex** — Drive Codex, nothing more; no business prompts which may not suit you.
  19. - 🧩 **Seamless integration** — AGENTS.md, skills & MCPs just work™ ; opt in to improve plan / review.
  20. - 🧠 **File system as memory** — Store instructions in files to resist compaction and preserve all details.
  21. - 🪶 **Tiny footprint** — Use [<1k tokens](./npm/resources/potter_worker.toml), ensuring LLM context fully serves your business logic.
  22. - 📚 **Built-in knowledge base** — Keep a local KB as index so Codex learns project fast in clean contexts.
  23. &ensp;
  24. ## CodexPotter ($loop) vs /goal
  25. CodexPotter always use fresh contexts for new rounds, thus:
  26. - It avoids context rotting, producing better results by auto reviewing and fixing in later rounds
  27. - It consumes more tokens
  28. - More unattended: queue multiple $loop tasks and go to sleep, they will execute one by one
  29. &ensp;
  30. ## 👀 How does it work
  31. ```plain
  32. 𝒀𝑶𝑼𝑹 𝑷𝑹𝑶𝑴𝑷𝑻:
  33. 𝘚𝘪𝘮𝘱𝘭𝘪𝘧𝘺 𝘵𝘩𝘦 𝘲𝘶𝘦𝘳𝘺 𝘦𝘯𝘨𝘪𝘯𝘦 𝘣𝘺 𝘧𝘰𝘭𝘭𝘰𝘸𝘪𝘯𝘨 ...
  34. │
  35. │
  36. codex: Continue working toward HANDOFF.md │
  37. ┌─────────────────────────┐ │
  38. │ │ ▼
  39. ┌─────────┴─────────┐ ┌─────────▼────────┐ ┌───────────────────┐
  40. │ main agent │ │ subagent │◄─────►│ HANDOFF.md │
  41. └─────────▲─────────┘ └─────────┬────────┘ └───────────────────┘
  42. │ │
  43. │ Work finished │
  44. └─────────────────────────┘
  45. ```
  46. &ensp;
  47. To learn more, see [$loop Skill File](./skills/loop/SKILL.md).
  48. &ensp;
  49. ## ⚡️ Getting started
  50. 1. Use the all-in-one wizard, it helps you set up necessary global gitignore and install skills via `npx skills`:
  51. ```bash
  52. npx codex-potter@next setup
  53. ```
  54. You will be prompted about what will be done, just confirm to continue:
  55. ```bash
  56. ➜ ~ npx codex-potter@next setup
  57. CodexPotter setup
  58. ✓ Skip: Ignore /.codexpotter in global gitignore
  59. ✓ Skip: Remove legacy subagent profile ~/.codex/agents/potter_worker.toml
  60. □ Todo: Install / update skill: npx --yes skills add --yes -g https://github.com/breezewish/CodexPotter/tree/v2 -a codex
  61. Continue? ● Yes / ○ No
  62. ```
  63. 2. Use `$loop` to trigger the workflow in Codex CLI or Codex Desktop:
  64. ```plain
  65. $loop Implement /ps endpoint according to docs/ps_design.md
  66. ```
  67. &ensp;
  68. **All skills:**
  69. - `$loop`: run the reconciliation workflow
  70. - `$compact-kb`: reorganize the local KB, make it more compact and efficient for later runs
  71. &ensp;
  72. ## Recommended Skills
  73. See [this repo](https://github.com/breezewish/skills) to install. Use these skills to make CodexPotter more powerful and unattended.
  74. - `$codex-review`: review code changes using fresh context, the same as Codex's /review, but you can use it with $loop. Example:
  75. ```plain
  76. $loop Use $codex-review to review code change in recent 2 days and fix all
  77. ```
  78. - `$simplify`: review and simplify the code, the same as Claude Code's /simplify, but you can use it with $loop. Example:
  79. ```plain
  80. $loop Use $simplify for code change in recent 2 days
  81. ```
  82. &ensp;
  83. ## 👀 Tips
  84. ### Prompt Examples
  85. **✅ tasks with clear goals or scopes:**
  86. - $loop port upstream codex's /resume into this project, keep code aligned
  87. **✅ persist results to review in later rounds:**
  88. - $loop create a design doc for ... **in DESIGN.md**
  89. **❌ interactive tasks with human feedback loops:**
  90. CodexPotter is not suitable for such tasks, use codex instead:
  91. - Front-end development with human UI feedback
  92. - Question-answering
  93. - Brainstorming sessions
  94. ### Howto
  95. <details>
  96. <summary>Plan and execute</summary>
  97. Simpliy queue two tasks via $loop, one is plan, one is implement, for example:
  98. Task prompt 1:
  99. ```plain
  100. $loop Analyze the codebase, research and design a solution for introducing subscription system.
  101. Output plan to docs/subscription_design.md.
  102. Your solution should meet the following requirements: ...
  103. Do not implement the plan, just design a good and simple solution.
  104. ```
  105. ↑ Your existing facility to write good plans will be utilized, including skills, plan doc principles
  106. 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.
  107. Task prompt 2:
  108. ```plain
  109. $loop Implement according to docs/subscription_design.md
  110. Make sure all user journeys are properly covered by e2e tests and pass.
  111. ```
  112. </details>
  113. <details>
  114. <summary>Update CodexPotter</summary>
  115. Run this again to update skills and prompts to the latest version:
  116. ```bash
  117. npx codex-potter@next setup
  118. ```
  119. </details>
  120. &ensp;
  121. ## Roadmap
  122. - [x] Resume
  123. - [x] Interoperability with codex CLI sessions (for follow-up prompts)
  124. - [x] Better sandbox support
  125. - [x] Handling steer
  126. &ensp;
  127. ## License
  128. - Apache-2.0 License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.