{"slug": "how-to-keep-a-project-wiki-with-codex", "title": "How to Keep a Project Wiki with Codex", "summary": "Nimbalyst released a free, MIT-licensed Wiki plugin for OpenAI's Codex that lets the coding agent write plain markdown project pages — a Home page, decisions and their rationale, open questions with owners, and tracking tables — directly into a repository. Developers on the Codex CLI install it via `codex plugin marketplace add nimbalyst/nimbalyst-wiki` and `codex plugin add nimbalyst-wiki@nimbalyst-wiki`, while Codex app and IDE extension users run `npm install -g @nimbalyst/cli` followed by `codex mcp add nimbalyst-wiki -- nim mcp`, which writes to the shared `~/.codex/config.toml`. Both routes require Node.js 22 or later and need no Nimbalyst app or account, and the plugin adds two local MCP servers, `nimbalyst-local` for reading and writing the wiki and `nimbalyst-session` for citing user input when recording decisions.", "body_md": "# How to Keep a Project Wiki with Codex\n\nAdd the free Nimbalyst Wiki to Codex with the Codex CLI plugin or one codex mcp add command for the Codex app and IDE extension. Codex writes a markdown wiki of decisions and open questions in your repo that you read and edit in your browser.\n\nTo keep a project wiki with Codex, install the free [Nimbalyst Wiki plugin for Codex](https://nimbalyst.com/wiki/) in the Codex CLI, or add its MCP server to the Codex app with one `codex mcp add` command, then ask Codex to set up a wiki for your repo. Codex writes plain markdown pages in your project: a Home page, the decisions you made and why, open questions with owners, and tables of what you track. You read and edit the pages in your browser, and you need no app and no account.\n\nBelow are both install routes, the first wiki, how to record decisions from Codex, and how the wiki relates to AGENTS.md and Codex memories.\n\n## Why keep a wiki next to Codex\n\nCodex is fast enough that a few sessions a day leave you with more plans, diffs and decisions than you can read. Each session settles something and raises something else, and a week later you cannot say what was decided about retries, who owns the open question about the mobile SDK, or why the team passed over the simpler option. We wrote about [that feeling of being overwhelmed by your coding agents](https://nimbalyst.com/blog/overwhelmed-working-with-coding-agents/) and why it comes from volume.\n\nThe Nimbalyst Wiki is where Codex distills that work for you. Codex writes the pages as part of the work, and you read them to catch up, think, set priorities and decide what comes next. When you edit a page, the next session works from what you wrote.\n\n## Choose your route\n\n| You work in | Route | What you get | \n|---|---|---|\n| Codex CLI | The Nimbalyst Wiki plugin | Wiki tools plus the setup, capture, recall and team skills | \n| Codex app or Codex IDE extension | `codex mcp add` with the`nim` CLI | Wiki tools; ask for what you want in your own words | \n\nBoth routes need Node.js 22 or later on your `PATH`. Neither needs the Nimbalyst app or a Nimbalyst account, and everything involved is MIT licensed, with the plugin source on [GitHub](https://github.com/nimbalyst/nimbalyst-wiki).\n\n## Route 1: The Codex CLI plugin\n\nAdd the marketplace and install the plugin:\n\n```\ncodex plugin marketplace add nimbalyst/nimbalyst-wiki\ncodex plugin add nimbalyst-wiki@nimbalyst-wiki\n```\n\nStart a new Codex session in your project. `codex mcp list` now shows two local servers: `nimbalyst-local`, which reads and writes the wiki and runs its browser view, and `nimbalyst-session`, which lets the agent cite what you typed when it records a decision. The plugin brings the same wiki tools and skills as in Claude Code. The docs cover [the Codex CLI install](https://nimbalyst.com/docs/wiki/start-in-your-coding-agent/#codex-cli) in more detail.\n\n## Route 2: The Codex app and IDE extension\n\nInstall the `nim` command line, then add the wiki server:\n\n```\nnpm install -g @nimbalyst/cli\ncodex mcp add nimbalyst-wiki -- nim mcp\n```\n\nOpenAI’s [MCP docs](https://developers.openai.com/codex/mcp) say the desktop app, the Codex CLI and the IDE extension share this configuration (`~/.codex/config.toml`), so one command adds the wiki to all of them. Restart the Codex app afterward.\n\nThis route gives Codex the wiki tools but not the plugin’s skills, so you ask for things in your own words: “set up a wiki for this repo”, “record what we decided in the wiki”, “what does the wiki say about auth?”. If the app cannot find `nim`, use the full path that `which nim` prints. The [plugin and nim CLI reference](https://nimbalyst.com/docs/wiki/agents-and-the-wiki/) lists every command.\n\n## Build the first wiki\n\nAsk Codex:\n\n```\nSet up a wiki for this repo.\n```\n\nCodex reads your README and docs, asks who the wiki is for and which sections you want, then writes a Home page, a writing guide (“How we write this wiki”) and starter pages as markdown files in your repo. The default shape is a strategic project wiki, with Home as a dashboard of the big picture and pages for the product and its modules, the initiatives under way, decisions, the team and strategy behind it. Running setup again fills gaps and never overwrites what is already there. See [how setup builds the first wiki](https://nimbalyst.com/docs/wiki/set-up-your-wiki/).\n\n## Record what you decided\n\nClaude Code reminds its agent to capture decisions when a session ends. Codex does not run plugin hooks, so there is no reminder. Make it a habit to finish a session with:\n\n```\nRecord what we decided in the wiki.\n```\n\nCodex writes each decision into the page it affects, as a marked sentence with who decided, when and what was passed over:\n\n```\n[We retry failed charges through the event queue.]{decided by=\"Dana Lee\" [email protected] on=2026-10-14 over=\"retrying inside the payment provider client\"}\n```\n\nOpen questions get the same treatment with an owner. On a local wiki the name and email come from your `git config`. One difference from Claude Code: session citations read Claude Code transcripts only, so decisions recorded from Codex carry your name but no quote from the session. The [capture docs](https://nimbalyst.com/docs/wiki/capture-decisions/) show what the agent writes, and [decision records written by your coding agent](https://nimbalyst.com/blog/architecture-decision-records-written-by-your-coding-agent/) covers how this replaces a separate ADR folder.\n\n## Ask the wiki before you change something\n\nAsk “why did we put retries in the event queue?” or “what is still open about the mobile SDK?” and Codex answers from the wiki, with each decision’s owner, date and the option it was chosen over, and the pages it read. Pages can list the code they cover in a `paths` field, so Codex can find the pages that explain a file before it changes it. More in [asking the wiki what was decided](https://nimbalyst.com/docs/wiki/recall-decisions/).\n\n## Read and edit it in your browser\n\nAsk Codex to “open the wiki in my browser.” You get the page tree and a page editor for text pages, drawings, mind maps, spreadsheets and mockups. Edits save straight to the markdown files, and what Codex writes shows up live. The view runs on your machine only and is protected by a token. See [reading and editing the wiki in your browser](https://nimbalyst.com/docs/wiki/browser-view/). With the `nim` CLI installed, `nim wiki serve` opens the same view from a shell.\n\n## Track things with typed pages and tables\n\nAsk Codex to track something, and it creates a type with the fields you name:\n\n```\nTrack our competitors in the wiki: category, threat, setup speed and payment recovery for each.\n```\n\nEach item gets its own page with those fields at the top, and the type keeps a table of every item. Types can also store their items as rows of one CSV when a page per item would be too much. The docs explain [pages, types and fields](https://nimbalyst.com/docs/wiki/pages-types-and-fields/). Customers, features, interview notes and decision logs fit the same pattern.\n\n## How it fits with AGENTS.md and Codex memories\n\nCodex already has two places that carry knowledge between sessions, and both are written for the agent.\n\n**AGENTS.md** holds instructions. According to OpenAI’s [AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md), Codex reads a global file in `~/.codex/` and then the `AGENTS.md` files from your Git root down to the current directory, and stops adding files at 32 KiB by default (`project_doc_max_bytes`). Keep it short and imperative: commands, conventions, the rules every task needs.\n\n**Codex memories** are notes Codex generates from past chats. The [memories docs](https://developers.openai.com/codex/memories) say they are off by default, live under `~/.codex/memories/`, and should be treated as “generated state” rather than something you edit by hand. The same page says to “keep required team guidance in `AGENTS.md` or checked-in documentation.”\n\n**The Nimbalyst Wiki** holds pages for you: what was decided and why, what is still open and who owns it, and what you are tracking. Put the one-line rule in AGENTS.md (“retry failed charges through the event queue”) and keep the decision behind it, with its date, its owner and the option you passed over, in the wiki. Our post on [CLAUDE.md, auto memory and a wiki](https://nimbalyst.com/blog/claude-code-memory-vs-a-wiki-your-agents-write/) covers the Claude Code side of the same split.\n\n## Where the files live\n\nThe wiki lives in `nimbalyst-local/wiki` by default, a folder git ignores so it stays private to you. To share it through your repo, choose a checked-in folder such as `docs/wiki` when you start the wiki and commit it like code. Links between pages are relative paths, so they read fine on GitHub, and deleted pages go to a `.trash` folder from where they can be restored. See [local wiki files](https://nimbalyst.com/docs/wiki/local-wiki-files/) for the full layout.\n\n## Keep it up to date\n\nUpdate the plugin with `codex plugin marketplace upgrade nimbalyst-wiki` and start a new session. If you installed the `nim` CLI, `nim update` updates `nim` and the Codex and Claude Code plugins in one step, and `nim doctor` shows which versions are installed. Once a day the plugin checks GitHub for a newer version and sends nothing about you or your wiki; `NIMBALYST_WIKI_NO_UPDATE_CHECK=1` turns the check off.\n\n## Use the same wiki in other agents\n\nBecause the wiki is a folder of files behind a standard MCP server, Claude Code, Cursor, VS Code and Cowork can work on the same pages, so you can switch agents without losing what they wrote. See [How to keep a project wiki with Claude Code](https://nimbalyst.com/blog/how-to-keep-a-project-wiki-with-claude-code/) and [A project wiki in Cursor, VS Code and Cowork](https://nimbalyst.com/blog/project-wiki-in-cursor-vs-code-and-cowork/).\n\nWhen the team needs the wiki, ask Codex to “move this wiki to a team wiki” and it moves the pages to [Wiki Teams](https://nimbalyst.com/wiki/teams/), where teammates edit the same pages in their browser and their agents write into it. The free [Nimbalyst app](https://nimbalyst.com/app/) also opens the same folder if you want the wiki next to your sessions and code.\n\n## FAQ\n\n**How do I add a wiki to Codex?** In the CLI, run `codex plugin marketplace add nimbalyst/nimbalyst-wiki` and `codex plugin add nimbalyst-wiki@nimbalyst-wiki`. For the Codex app and IDE extension, run `npm install -g @nimbalyst/cli` and `codex mcp add nimbalyst-wiki -- nim mcp`. Then ask Codex to set up a wiki for this repo.\n\n**Does Codex have memory?** It reads AGENTS.md for instructions and has opt-in memories, off by default, stored under `~/.codex/memories/`. Both are written for the agent. The wiki is written for you.\n\n**Does the Codex app support it?** Yes, through `codex mcp add`. The app, the CLI and the IDE extension share one configuration.\n\n**Can Codex and Claude Code share a wiki?** Yes. Both work on the same markdown files with the same tools.\n\n**Why no capture reminder in Codex?** Codex does not run plugin hooks. Ask it to record what you decided at the end of a session.\n\nThe Nimbalyst Wiki page linked at the top has the install steps for every agent.\n\n## Related pages\n\n-   ### Nimbalyst WikiA local wiki your coding agents write for you, so you can think, organize and set direction.\n-   ### How to Keep a Project Wiki with Claude CodeInstall, setup, capture and recall with the Claude Code plugin.\n-   ### A Project Wiki in Cursor, VS Code and CoworkThe same wiki through the nim mcp server in any MCP agent.\n-   ### Architecture Decision Records Written by Your Coding AgentDecisions in the page they affect, with who, when and what was rejected.\n-   ### Docs: Ask the Wiki What Was DecidedHow recall answers from decisions and the pages that cover your code.\n\n## Related posts\n\n-   ### Architecture Decision Records Written by Your Coding AgentHow to keep architecture decision records and a decision log when Claude Code and Codex make decisions faster than anyone writes them down: the agent records each decision in the page it affects, with who decided, when, what was rejected and a quote from the session.\n-   ### How to Keep a Project Wiki with Claude CodeInstall the free Nimbalyst Wiki plugin in Claude Code, run setup, and Claude writes a markdown wiki of your decisions, open questions and tracked items in your repo, which you read and edit in your browser.\n-   ### Overwhelmed Working with Coding Agents? Have Them Write You a WikiRunning several Claude Code or Codex sessions produces more decisions and open questions than one person can track. Here is the approach we use: the agents distill their work into a short wiki for you, and you read, think and set direction.", "url": "https://wpnews.pro/news/how-to-keep-a-project-wiki-with-codex", "canonical_source": "https://nimbalyst.com/blog/how-to-keep-a-project-wiki-with-codex/", "published_at": "2026-10-10 00:00:00+00:00", "updated_at": "2026-10-27 14:12:48.082391+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "developer-tools", "ai-products"], "entities": ["Nimbalyst", "Codex", "OpenAI", "Nimbalyst Wiki", "Codex CLI", "nimbalyst-local", "nimbalyst-session"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-keep-a-project-wiki-with-codex", "markdown": "https://wpnews.pro/news/how-to-keep-a-project-wiki-with-codex.md", "text": "https://wpnews.pro/news/how-to-keep-a-project-wiki-with-codex.txt", "jsonld": "https://wpnews.pro/news/how-to-keep-a-project-wiki-with-codex.jsonld"}}