{"id":45858074,"url":"https://github.com/breezewish/codexpotter","last_synced_at":"2026-04-27T05:06:17.900Z","repository":{"id":335419566,"uuid":"1144422934","full_name":"breezewish/CodexPotter","owner":"breezewish","description":"Ralph loop for codex — continuously reconciles codebase toward your instructed state","archived":false,"fork":false,"pushed_at":"2026-03-07T14:48:25.000Z","size":1395,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T14:58:23.055Z","etag":null,"topics":["codex","codex-cli","gpt","openai","ralph","ralph-loop","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/breezewish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-28T17:13:14.000Z","updated_at":"2026-03-07T14:47:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/breezewish/CodexPotter","commit_stats":null,"previous_names":["breezewish/codex-potter","breezewish/codexpotter"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/breezewish/CodexPotter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezewish%2FCodexPotter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezewish%2FCodexPotter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezewish%2FCodexPotter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezewish%2FCodexPotter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/breezewish","download_url":"https://codeload.github.com/breezewish/CodexPotter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezewish%2FCodexPotter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30246874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T05:41:50.788Z","status":"ssl_error","status_checked_at":"2026-03-08T05:41:39.075Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex","codex-cli","gpt","openai","ralph","ralph-loop","ralph-wiggum"],"created_at":"2026-02-27T05:06:35.078Z","updated_at":"2026-04-27T05:06:17.893Z","avatar_url":"https://github.com/breezewish.png","language":"Rust","readme":"\u003c!--\n\nFor agents: This file is carefully maintained and polished for better readability. Don't edit this file.\n\n--\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./etc/banner.svg\" alt=\"CodexPotter banner\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./etc/screenshot.png\" alt=\"CodexPotter screenshot\" width=\"80%\" /\u003e\n\u003c/p\u003e\n\n\u0026ensp;\n\n## 💡 Why CodexPotter\n\n[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)](#)\n[![npm](https://img.shields.io/npm/v/codex-potter?label=Release\u0026style=flat-square)](https://www.npmjs.com/package/codex-potter)\n[![CI](https://img.shields.io/github/actions/workflow/status/breezewish/CodexPotter/ci.yml?branch=main\u0026label=CI\u0026style=flat-square)](https://github.com/breezewish/CodexPotter/actions/workflows/ci.yml)\n[![License](https://img.shields.io/github/license/breezewish/CodexPotter?label=License\u0026style=flat-square)](./LICENSE)\n[![LinuxDo](https://img.shields.io/badge/Community-LINUX%20DO-blue?style=flat-square)](https://linux.do)\n\n**CodexPotter** continuously **reconciles** code base toward your instructed state ([Ralph Wiggum pattern](https://ghuntley.com/ralph/)):\n\n- 🤖 **Codex-first** — Codex subscription is all you need; no extra LLM needed.\n- 🧭 **Auto-review / reconcile** — Review and polish multi rounds until fully aligned with your instruction.\n- 💦 **Clean-room** — Use clean context in each round, avoid context poisoning, maximize IQ.\n- 🎯 **Attention is all you need** — Keep you focused on _crafting_ tasks, instead of _cleaning up_ unfinished work.\n- 🚀 **Never worse than Codex** — Drive Codex, nothing more; no business prompts which may not suit you.\n- 🧩 **Seamless integration** — AGENTS.md, skills \u0026 MCPs just work™ ; opt in to improve plan / review.\n- 🧠 **File system as memory** — Store instructions in files to resist compaction and preserve all details.\n- 🪶 **Tiny footprint** — Use [\u003c1k tokens](./cli/prompts/developer_prompt.md), ensuring LLM context fully serves your business logic.\n- 📚 **Built-in knowledge base** — Keep a local KB as index so Codex learns project fast in clean contexts.\n\n\u0026ensp;\n\n## 👀 How does it work\n\n```plain\n\n                                                  𝒀𝑶𝑼𝑹 𝑷𝑹𝑶𝑴𝑷𝑻:\n                                                  𝘚𝘪𝘮𝘱𝘭𝘪𝘧𝘺 𝘵𝘩𝘦 𝘲𝘶𝘦𝘳𝘺 𝘦𝘯𝘨𝘪𝘯𝘦 𝘣𝘺 𝘧𝘰𝘭𝘭𝘰𝘸𝘪𝘯𝘨 ...\n                                                                 │\n                                                                 │\n     codex: Work or review according to MAIN.md                  │\n            ┌──────────────────────────┐                         │\n            │                          │                         ▼\n  ┌─────────┴─────────┐     ┌──────────▼────────┐       ┌───────────────────┐\n  │    CodexPotter    │     │       codex       │◄─────►│      MAIN.md      │\n  └─────────▲─────────┘     └──────────┬────────┘       └───────────────────┘\n            │                          │\n            │      Work finished       │\n            └──────────────────────────┘\n\n```\n\n\u0026ensp;\n\n## ⚡️ Getting started\n\n**1. Prerequisites:** ensure you have [codex CLI](https://developers.openai.com/codex/quickstart?setup=cli) locally. CodexPotter drives your local codex to perform tasks.\n\n**2. Install CodexPotter via npm or bun:**\n\n```shell\n# Install via npm\nnpm install -g codex-potter\n```\n\n```shell\n# Install via bun\nbun install -g codex-potter\n```\n\n**3. Run:** Start CodexPotter in your project directory, just like Codex:\n\n```sh\n# --yolo is recommended to be fully autonomous\ncodex-potter --yolo\n```\n\n⚠️ **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.\n\n⚠️ **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.\n\n\u0026ensp;\n\n## Tips\n\n### Prompt Examples\n\n**✅ tasks with clear goals or scopes:**\n\n- \"port upstream codex's /resume into this project, keep code aligned\"\n\n**✅ persist results to review in later rounds:**\n\n- \"create a design doc for ... **in DESIGN.md**\"\n\n**❌ interactive tasks with human feedback loops:**\n\nCodexPotter is not suitable for such tasks, use codex instead:\n\n- Front-end development with human UI feedback\n- Question-answering\n- Brainstorming sessions\n\n### Howto\n\n\u003cdetails\u003e\n\u003csummary\u003eAsk followup questions in codex\u003c/summary\u003e\n\nJust pass the project file to codex, like:\n\n```plain\nbased on .codexpotter/projects/2026/03/18/1/MAIN.md,\nplease explain more about the root cause of the issue\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePlan and execute\u003c/summary\u003e\n\nSimpliy queue two tasks in CodexPotter, one is plan, one is implement, CodexPotter will execute one by one, for example:\n\nTask prompt 1 (CodexPotter):\n\n```plain\nAnalyze the codebase, research and design a solution for introducing subscription system.\nOutput plan to docs/subscription_design.md.\n\nYour solution should meet the following requirements: ...\n\nDo not implement the plan, just design a good and simple solution.\n```\n\n↑ Your existing facility to write good plans will be utilized, including skills, plan doc principles\nin 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.\n\nTask prompt 2 (CodexPotter):\n\n```plain\nImplement according to docs/subscription_design.md\n\nMake sure all user journeys are properly covered by e2e tests and pass.\n```\n\nIf 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.\n\n\u003c/details\u003e\n\n\u0026ensp;\n\n## Configuration\n\n- [Config File](./docs/config.md)\n- [Hooks](./docs/hooks.md)\n\n\u0026ensp;\n\n## Other Features\n\n- `--xmodel` (experimental): Use gpt-5.2 first, then use gpt-5.5 to cross review gpt-5.2's work in later rounds. In clear coding tasks this may produce better results than only using gpt-5.2 or gpt-5.5.\n\n- `/yolo`: Toggle whether YOLO (no sandbox) is enabled by default for all sessions.\n\n- `/list` or `ctrl+l`: View all projects (tasks) and their results.\n\n\u0026ensp;\n\n## Roadmap\n\n- [x] Skill popup\n- [x] Resume (history replay + continue iterating)\n- [x] Better handling of stream disconnect / similar network issues\n- [x] Agent-call friendly (non-interactive exec and resume)\n- [x] Interoperability with codex CLI sessions (for follow-up prompts)\n- [ ] Better plan / user selection support\n- [ ] Better sandbox support\n\n\u0026ensp;\n\n## Development\n\n```sh\n# Formatting\ncargo fmt\n\n# Lints\ncargo clippy\n\n# Tests\ncargo nextest run\n\n# Build\ncargo build\n```\n\n\u0026ensp;\n\n## Community \u0026 License\n\n- This project is community-driven fork of [openai/codex](https://github.com/openai/codex) repository, licensed under the same Apache-2.0 License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezewish%2Fcodexpotter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreezewish%2Fcodexpotter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezewish%2Fcodexpotter/lists"}