Merge pull request #24 from xsa-dev/feat-ai/add-codex-integration-docs

[codex] Add Codex integration docs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -52,6 +52,7 @@ body:
     attributes:
       label: IDE / Client
       options:
+        - Codex
         - Claude Code
         - Claude Desktop
         - Cursor

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 |
 
 ---

docs/CONFIGURATION.md

@@ -62,7 +62,21 @@ vestige restore <file>     # 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)
 

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
+
+<details>
+<summary>Vestige tools do not appear in Codex</summary>
+
+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.
+</details>
+
+<details>
+<summary>Need to remove or re-add the server</summary>
+
+```bash
+codex mcp remove vestige
+codex mcp add vestige -- /usr/local/bin/vestige-mcp
+```
+</details>
+
+---
+
+## 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.

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) |

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) |

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) |

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) |

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) |