Add Selvedge to Codex

Selvedge gives Codex a local store for project decisions and rejected approaches. Run selvedge setup --agent codex (0.3.12+) to install project MCP configuration and instructions together.

Before you start

pip install selvedge gives you the selvedge CLI (selvedge setup, selvedge blame, and the selvedge prompt helper below):

pip install selvedge

The MCP config below launches the server with uvx instead of a bare selvedge-server, so the package can be fetched on demand — the editor still needs to find uv installed. Prefer the global binary? Swap uvx --from selvedge selvedge-server for selvedge-server.

Add the MCP server

Add this to .codex/config.toml in a trusted project, or ~/.codex/config.toml for user-wide setup:

[mcp_servers.selvedge]
command = "uvx"
args = ["--from", "selvedge", "selvedge-server"]

Prefer not to touch config files? selvedge setup detects Codex and writes this for you (with a .bak first).

Tell your agent when to call it

Selvedge captures decisions when your agent calls it. Install the instruction block into your project’s AGENTS.md:

selvedge prompt --install AGENTS.md

It’s also a copy-paste block on the site: the Selvedge agent prompt block.

Verify

Restart Codex in the trusted project. Enable the Selvedge MCP server in Settings → MCP servers if needed. Ask Codex to record a real rejected approach with log_change, then retrieve it with prior_attempts. Start a new session and query the same entity.

If it doesn’t connect

Codex project configuration loads only for trusted projects. The setup wizard writes .codex/config.toml and installs instructions in AGENTS.md. Custom TOML entries must be reconciled manually. Make sure uvx (manual setup) or selvedge-server (wizard setup) is on the PATH Codex uses. Claude Code lifecycle hooks are not installed for Codex.

Next

• Quickstart → — the three-command setup and what selvedge setup automates.
• MCP tools → — the eight tools Codex will be able to call.
• Codex MCP docs → — the upstream reference.