From d10a336cccc88c41d15d7797a7f83ff5ef20e4d6 Mon Sep 17 00:00:00 2001 From: Aleksei Savin Date: Sun, 5 Apr 2026 18:50:57 +0300 Subject: [PATCH] Add Codex integration docs --- .github/ISSUE_TEMPLATE/bug_report.yml | 1 + README.md | 6 +- docs/CONFIGURATION.md | 16 +++- docs/integrations/codex.md | 132 ++++++++++++++++++++++++++ docs/integrations/cursor.md | 1 + docs/integrations/jetbrains.md | 1 + docs/integrations/vscode.md | 1 + docs/integrations/windsurf.md | 1 + docs/integrations/xcode.md | 1 + 9 files changed, 158 insertions(+), 2 deletions(-) create mode 100644 docs/integrations/codex.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5b45d8a..cc1c176 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -52,6 +52,7 @@ body: attributes: label: IDE / Client options: + - Codex - Claude Code - Claude Desktop - Cursor diff --git a/README.md b/README.md index ed218fc..dc11d96 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,9 @@ sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/ # 2. Connect to Claude Code claude mcp add vestige vestige-mcp -s user +# Or connect to Codex +codex mcp add vestige -- /usr/local/bin/vestige-mcp + # 3. Test it # "Remember that I prefer TypeScript over JavaScript" # ...new session... @@ -89,6 +92,7 @@ Vestige speaks MCP — the universal protocol for AI tools. One brain, every IDE | IDE | Setup | |-----|-------| | **Claude Code** | `claude mcp add vestige vestige-mcp -s user` | +| **Codex** | [Integration guide](docs/integrations/codex.md) | | **Claude Desktop** | [2-min setup](docs/CONFIGURATION.md#claude-desktop-macos) | | **Xcode 26.3** | [Integration guide](docs/integrations/xcode.md) | | **Cursor** | [Integration guide](docs/integrations/cursor.md) | @@ -321,7 +325,7 @@ vestige dashboard # Open 3D dashboard in browser | [Storage Modes](docs/STORAGE.md) | Global, per-project, multi-instance | | [CLAUDE.md Setup](docs/CLAUDE-SETUP.md) | Templates for proactive memory | | [Configuration](docs/CONFIGURATION.md) | CLI commands, environment variables | -| [Integrations](docs/integrations/) | Xcode, Cursor, VS Code, JetBrains, Windsurf | +| [Integrations](docs/integrations/) | Codex, Xcode, Cursor, VS Code, JetBrains, Windsurf | | [Changelog](CHANGELOG.md) | Version history | --- diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index a2ff40a..52c6b08 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -62,7 +62,21 @@ vestige restore # Restore from backup --- -## Claude Configuration +## Client Configuration + +### Codex (One-liner) + +```bash +codex mcp add vestige -- /usr/local/bin/vestige-mcp +``` + +### Codex (Manual) + +Add to `~/.codex/config.toml`: +```toml +[mcp_servers.vestige] +command = "/usr/local/bin/vestige-mcp" +``` ### Claude Code (One-liner) diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md new file mode 100644 index 0000000..71f21bd --- /dev/null +++ b/docs/integrations/codex.md @@ -0,0 +1,132 @@ +# Codex + +> Give Codex a brain that remembers between sessions. + +Codex has native MCP support through the `codex mcp` CLI. Add Vestige once and Codex can carry project preferences, architecture decisions, and past fixes across sessions. + +--- + +## Prerequisites + +- **Codex CLI** installed and authenticated +- **vestige-mcp** binary installed ([Installation guide](../../README.md#quick-start)) + +--- + +## Setup + +### 1. Add Vestige + +```bash +codex mcp add vestige -- /usr/local/bin/vestige-mcp +``` + +> **Use an absolute path.** Run `which vestige-mcp` to find the installed binary. + +### 2. Verify + +```bash +codex mcp list +``` + +You should see a `vestige` entry with `enabled` status. + +### 3. Test it in Codex + +Start Codex and ask: + +> "What MCP tools do you have access to?" + +You should see Vestige's tools listed (`search`, `smart_ingest`, `memory`, and others). + +--- + +## First Use + +In Codex: + +> "Remember that this project uses Rust with Axum and SQLite" + +Start a **new session**, then ask: + +> "What stack does this project use?" + +It remembers. + +--- + +## Manual Configuration + +Codex stores MCP servers in `~/.codex/config.toml`. + +Minimal config: + +```toml +[mcp_servers.vestige] +command = "/usr/local/bin/vestige-mcp" +``` + +After saving, restart Codex or start a new session. + +--- + +## Project-Specific Memory + +Use `--data-dir` to isolate memory per repo or workspace: + +```bash +codex mcp remove vestige +codex mcp add vestige -- /usr/local/bin/vestige-mcp --data-dir /Users/you/projects/my-app/.vestige +``` + +Equivalent manual config: + +```toml +[mcp_servers.vestige] +command = "/usr/local/bin/vestige-mcp" +args = ["--data-dir", "/Users/you/projects/my-app/.vestige"] +``` + +--- + +## Troubleshooting + +
+Vestige tools do not appear in Codex + +1. Verify the server is registered: + ```bash + codex mcp list + ``` +2. Check the binary path: + ```bash + which vestige-mcp + ``` +3. Ensure the config entry exists in `~/.codex/config.toml`. +4. Start a fresh Codex session after adding the server. +
+ +
+Need to remove or re-add the server + +```bash +codex mcp remove vestige +codex mcp add vestige -- /usr/local/bin/vestige-mcp +``` +
+ +--- + +## Also Works With + +| IDE | Guide | +|-----|-------| +| Xcode 26.3 | [Setup](./xcode.md) | +| Cursor | [Setup](./cursor.md) | +| VS Code (Copilot) | [Setup](./vscode.md) | +| JetBrains | [Setup](./jetbrains.md) | +| Windsurf | [Setup](./windsurf.md) | +| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) | +| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) | + +Your AI remembers everything, everywhere. diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md index 1c459ec..1e22943 100644 --- a/docs/integrations/cursor.md +++ b/docs/integrations/cursor.md @@ -133,6 +133,7 @@ Cursor does not surface MCP server errors in the UI. Test by running the command | IDE | Guide | |-----|-------| | Xcode 26.3 | [Setup](./xcode.md) | +| Codex | [Setup](./codex.md) | | VS Code (Copilot) | [Setup](./vscode.md) | | JetBrains | [Setup](./jetbrains.md) | | Windsurf | [Setup](./windsurf.md) | diff --git a/docs/integrations/jetbrains.md b/docs/integrations/jetbrains.md index b3dd0bf..3424539 100644 --- a/docs/integrations/jetbrains.md +++ b/docs/integrations/jetbrains.md @@ -122,6 +122,7 @@ In **Settings > Tools > MCP Server**, click the expansion arrow next to your cli | Xcode 26.3 | [Setup](./xcode.md) | | Cursor | [Setup](./cursor.md) | | VS Code (Copilot) | [Setup](./vscode.md) | +| Codex | [Setup](./codex.md) | | Windsurf | [Setup](./windsurf.md) | | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) | | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) | diff --git a/docs/integrations/vscode.md b/docs/integrations/vscode.md index 01e132a..556e784 100644 --- a/docs/integrations/vscode.md +++ b/docs/integrations/vscode.md @@ -152,6 +152,7 @@ Every team member with Vestige installed will automatically get memory-enabled C |-----|-------| | Xcode 26.3 | [Setup](./xcode.md) | | Cursor | [Setup](./cursor.md) | +| Codex | [Setup](./codex.md) | | JetBrains | [Setup](./jetbrains.md) | | Windsurf | [Setup](./windsurf.md) | | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) | diff --git a/docs/integrations/windsurf.md b/docs/integrations/windsurf.md index 6e06205..3ea7b45 100644 --- a/docs/integrations/windsurf.md +++ b/docs/integrations/windsurf.md @@ -148,6 +148,7 @@ If you have many MCP servers and exceed 100 total tools, Cascade will ignore exc | Xcode 26.3 | [Setup](./xcode.md) | | Cursor | [Setup](./cursor.md) | | VS Code (Copilot) | [Setup](./vscode.md) | +| Codex | [Setup](./codex.md) | | JetBrains | [Setup](./jetbrains.md) | | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) | | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) | diff --git a/docs/integrations/xcode.md b/docs/integrations/xcode.md index fafad89..5e106a5 100644 --- a/docs/integrations/xcode.md +++ b/docs/integrations/xcode.md @@ -249,6 +249,7 @@ Vestige uses the MCP standard — the same memory works across all your tools: | IDE | Guide | |-----|-------| | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) | +| Codex | [Setup](./codex.md) | | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) | | Cursor | [Setup](./cursor.md) | | VS Code (Copilot) | [Setup](./vscode.md) |