From 905930de270d3c988333bbdb05fd43a5cf6aafcc Mon Sep 17 00:00:00 2001 From: Steve-too Date: Mon, 6 Jul 2026 20:42:09 +0000 Subject: [PATCH 1/2] docs(adapters): codex adapter docs reflect the tiered install Three doc surfaces went stale after the codex T2 work landed: - adapters/README.md table still described codex as a single-file config.toml snippet - adapters/codex/README.md documented only the manual ~/.codex/config.toml edit, not the installer-first flow - docs/getting-started.md mentioned codex only as a comment in the claude-code mcp add one-liner Closes vouchdev/vouch#390 --- adapters/README.md | 2 +- adapters/codex/README.md | 37 +++++++++++++++++++++++++++++++++---- docs/getting-started.md | 22 +++++++++++++++------- 3 files changed, 49 insertions(+), 12 deletions(-) diff --git a/adapters/README.md b/adapters/README.md index f4edce8c..08ba5338 100644 --- a/adapters/README.md +++ b/adapters/README.md @@ -10,7 +10,7 @@ file you need into your project and edit it. |---|---|---| | [claude-code/](claude-code/) | Anthropic's Claude Code CLI | `.mcp.json` snippet, `CLAUDE.md` excerpt | | [cursor/](cursor/) | Cursor IDE | `mcp.json` snippet | -| [codex/](codex/) | OpenAI's Codex CLI | `config.toml` snippet | +| [codex/](codex/) | OpenAI's Codex CLI | `.codex/config.toml`, `AGENTS.md` snippet | | [continue/](continue/) | Continue.dev | `config.json` snippet | | [openclaw/](openclaw/) | OpenClaw plugin host | `.openclaw/plugins.json`, `AGENTS.md` excerpt | | [generic-mcp/](generic-mcp/) | Any MCP-speaking host | annotated reference | diff --git a/adapters/codex/README.md b/adapters/codex/README.md index cfb324a4..7dc3187c 100644 --- a/adapters/codex/README.md +++ b/adapters/codex/README.md @@ -4,10 +4,37 @@ Wires `vouch serve` into [OpenAI's Codex CLI][codex] as an MCP server. [codex]: https://github.com/openai/codex -## Setup +## Quick start -Codex reads MCP server config from `~/.codex/config.toml`. Add a -`vouch` entry: +```bash +vouch install-mcp codex +``` + +This writes a project-local `.codex/config.toml` (T1) and, at T2, +appends a fenced snippet to `AGENTS.md` so Codex knows how to use the +KB tools. Restart any running Codex session. + +## Tiers + +| Tier | What it adds | File | +|---|---|---| +| T1 | MCP wire — `vouch serve` as an MCP server | `.codex/config.toml` | +| T2 | AGENTS.md snippet — standing instructions for recall, propose-don't-write, and the human review gate | `AGENTS.md` (fenced) | + +Install a specific tier: + +```bash +vouch install-mcp codex --tier T1 # MCP config only +vouch install-mcp codex --tier T2 # MCP config + AGENTS.md snippet +``` + +Re-running is idempotent: existing files are left alone, and the +`AGENTS.md` fence is replaced in-place without duplicating the block. + +## Manual setup + +If you prefer to edit the config by hand, add a `vouch` entry to +`~/.codex/config.toml`: ```toml [mcp_servers.vouch] @@ -18,7 +45,9 @@ args = ["serve"] VOUCH_AGENT = "codex" ``` -Restart any running `codex` session. +Or use the project-local form (what `vouch install-mcp codex --tier T1` +writes) at `/.codex/config.toml`. The project-local form is +preferred because it doesn't touch home-directory state. ## Notes diff --git a/docs/getting-started.md b/docs/getting-started.md index bb9ac038..cd28caa5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -111,16 +111,24 @@ git add .vouch && git commit -m "kb: approve auth-uses-jwt" you need: ```bash -claude mcp add vouch -- vouch serve # or: codex mcp add vouch -- vouch serve +claude mcp add vouch -- vouch serve # Claude Code +codex mcp add vouch -- vouch serve # OpenAI Codex CLI ``` -Add `-e VOUCH_AGENT=claude-code` to attribute the agent's proposals to it -rather than your shell user. Confirm with `claude mcp list` (look for -`vouch … ✓ Connected`). +Add `-e VOUCH_AGENT=claude-code` (or `VOUCH_AGENT=codex`) to attribute the +agent's proposals to it rather than your shell user. Confirm with +`claude mcp list` or `codex mcp list` (look for `vouch … ✓ Connected`). -Prefer a config file, or want the brain-first `CLAUDE.md`, slash commands, and -hooks too? Run `vouch install-mcp claude-code` — or drop this into `.mcp.json` -at the project root by hand: +Prefer a config file, or want the brain-first `CLAUDE.md`/`AGENTS.md`, +slash commands, and hooks too? Run the installer for your host: + +```bash +vouch install-mcp claude-code # Claude Code +vouch install-mcp codex # OpenAI Codex CLI +``` + +Or drop the config in by hand — for Claude Code, put this into `.mcp.json` +at the project root: ```json { From 13853fd1e7767b26a2e0a8a07848c118241261b8 Mon Sep 17 00:00:00 2001 From: Steve-too Date: Tue, 7 Jul 2026 08:12:25 +0000 Subject: [PATCH 2/2] docs(codex): clarify AGENTS fence rerun behavior --- adapters/codex/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adapters/codex/README.md b/adapters/codex/README.md index 7dc3187c..cbe80424 100644 --- a/adapters/codex/README.md +++ b/adapters/codex/README.md @@ -28,8 +28,8 @@ vouch install-mcp codex --tier T1 # MCP config only vouch install-mcp codex --tier T2 # MCP config + AGENTS.md snippet ``` -Re-running is idempotent: existing files are left alone, and the -`AGENTS.md` fence is replaced in-place without duplicating the block. +Re-running is idempotent: existing files are left alone, and an +existing `AGENTS.md` fence is preserved without duplicating the block. ## Manual setup