Skip to content

docs(adapters): codex adapter docs reflect the tiered install #407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Steve-too wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(adapters): codex adapter docs reflect the tiered install #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
905930d
docs(adapters): codex adapter docs reflect the tiered install
Steve-too Jul 6, 2026
13853fd
docs(codex): clarify AGENTS fence rerun behavior
Steve-too Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion adapters/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
37 changes: 33 additions & 4 deletions adapters/codex/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 an
existing `AGENTS.md` fence is preserved 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]
Expand All @@ -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 `<project>/.codex/config.toml`. The project-local form is
preferred because it doesn't touch home-directory state.

## Notes

Expand Down
22 changes: 15 additions & 7 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down