Codex MCP Sidecar

Codex MCP Sidecar is a local MCP server for letting Claude Code start, resume, and wait for Codex app-server sessions while a human can inspect those live sessions from a terminal.

It is designed for a specific collaboration pattern:

1. Claude starts Codex through MCP and gets back a small run handle.
2. The Codex turn keeps running in the background by default.
3. A human opens codex-runs, selects the active run, and attaches to the same live Codex session.
4. Claude calls codex_wait until the final result is ready.

This project is a local sidecar around the Codex CLI. It is not an official OpenAI product.

Why

When Claude Code calls another agent through a normal MCP tool, the human often sees only one opaque tool-call placeholder. That makes supervision difficult, especially for long running Codex work.

This sidecar keeps the Claude-facing MCP response compact, but stores the full audit trail under the project working directory and exposes a local picker for human inspection.

Features

• Uses Codex app-server instead of codex exec for Claude-facing calls.
• Defaults codex_run and codex_resume to async mode so live turns remain inspectable.
• Provides codex_wait with a 240 second soft wait slice by default, helping Claude keep prompt cache warm during long Codex work.
• Stores audit artifacts in <project-root>/.codex/codex-mcp/runs/.
• Maintains a small user-level run pointer index in $CODEX_HOME/mcp-wrapper/runs.index.jsonl.
• Lets humans inspect active and completed runs through the codex-runs CLI.
• Keeps MCP tool payloads small and leaves detailed audit data on disk.
• Avoids exposing direct inspect commands, backend details, file paths, command logs, parse errors, or deep links in normal MCP responses.

Requirements

• Node.js 20 or newer.
• npm.
• Codex CLI available as codex.
• A Codex CLI build that supports codex app-server and codex resume --remote.
• Claude Code or another MCP client that can run stdio MCP servers.

Installation

Clone the repository and install dependencies:

git clone git@github.com:0Pinky0/codex-mcp-sidecar.git
cd codex-mcp-sidecar
npm ci

Optional local bin setup:

npm link

That exposes:

• codex-mcp-sidecar: stdio MCP server entrypoint.
• codex-mcp-wrapper: compatibility alias for the same server.
• codex-runs: terminal picker for inspecting Codex runs.

You can also run the server directly with node <repo-path>/server.mjs.

Claude Code Configuration

Register the server with Claude Code. The MCP server name can be codex if you want Claude to see this sidecar as the main Codex integration:

claude mcp add-json codex '{
  "type": "stdio",
  "command": "node",
  "args": ["<repo-path>/server.mjs"],
  "env": {
    "CODEX_HOME": "~/.codex",
    "CODEX_MCP_WRAPPER_CODEX_HOME": "~/.codex"
  }
}' --scope user

Replace <repo-path> with the absolute path to this repository.

After registration, call codex_wrapper_check from Claude. A healthy local configuration returns ok: true and the detected Codex CLI version.

Exposed MCP Tools

codex_run

Starts a new persisted Codex app-server turn.

Important defaults:

• async: true
• permissions: "yolo"
• app-server mode: shared
• audit directory: <cwd>/.codex/codex-mcp/runs/

Example:

{
  "prompt": "Audit the current diff. Return findings first, then residual risk.",
  "run_name": "diff-audit",
  "cwd": "<project-root>",
  "approval_policy": "never",
  "timeout_ms": 1800000
}

Async calls return a compact running handle, typically including runId, status, threadId, and timeout state.

codex_resume

Resumes a previous Codex session by wrapper run_id.

The caller does not need to know the internal Codex thread id. The sidecar resolves it from the active run metadata, the project run index, the user-level pointer index, or compatible old audit artifacts.

Example:

{
  "run_id": "<previous wrapper run id>",
  "prompt": "Continue from the previous audit and focus on test coverage.",
  "cwd": "<project-root>",
  "timeout_ms": 1800000
}

codex_wait

Waits for an async codex_run or codex_resume turn.

By default, codex_wait soft-returns after 240 seconds if Codex is still working. The Codex turn is not stopped. Claude should call codex_wait again with the same run_id.

Example:

{
  "run_id": "<run id from codex_run or codex_resume>",
  "timeout_ms": 1800000,
  "soft_timeout_ms": 240000
}

A soft timeout response looks like this:

{
  "runId": "<same run id>",
  "status": "still_running",
  "threadId": "<codex thread id>",
  "timedOut": false,
  "waitElapsedMs": 240000,
  "nextWaitMs": 240000,
  "progress": {
    "events": 12,
    "totalTokens": 120,
    "outputTokens": 20,
    "reasoningTokens": 5
  }
}

Set soft_timeout_ms to 0 only when the caller deliberately wants one long blocking wait.

codex_active_runs

Lists currently active app-server turns from the audit directory. The response is intentionally compact and does not include inspect commands or artifact paths.

codex_runs

Lists recent wrapper run handles without calling Codex.

Returned items are limited to:

{
  "runId": "<wrapper run id>",
  "status": "completed",
  "title": "Readable title"
}

codex_wrapper_check

Checks the local Codex binary, Codex home, run directory, pointer index, default timeouts, and detected Codex CLI version.

Human Inspection

The MCP tools do not return direct inspect commands. Humans inspect locally with the terminal picker:

cd <project-root>
codex-runs

The picker shows two columns:

• Running: active background Codex turns.
• Completed: recent completed turns.

Use arrow keys to move, PageUp/PageDown to change pages, Enter to attach, and q, Esc, or Ctrl-C to quit.

When a run is selected, the picker attaches using the underlying Codex command:

codex resume --remote ws://127.0.0.1:45123 <threadId>

After the attached Codex CLI exits, the picker returns to the main list instead of closing.

Other useful modes:

codex-runs --all      # Read the user-level pointer index across projects.
codex-runs --json     # Print machine-readable session data.
codex-runs --no-watch # Disable automatic refresh.

Audit Artifacts

For each run, the sidecar writes audit files under:

<project-root>/.codex/codex-mcp/runs/

Typical files:

• <runId>.jsonl: raw Codex event stream.
• <runId>.stderr.log: Codex stderr.
• <runId>.md: human-readable audit summary.
• index.jsonl: append-only project run index.
• active/<runId>.json: active run metadata while Codex is still working.

The sidecar also writes a small pointer index under:

$CODEX_HOME/mcp-wrapper/runs.index.jsonl

That pointer index is used to resolve codex_resume(run_id) across projects.

Security Notes

The default permissions profile is yolo, which maps to Codex's built-in :danger-full-access profile. This is intentional for the local orchestration workflow, but it is powerful.

Recommended precautions:

• Run the sidecar only on a machine and workspace you trust.
• Do not expose the shared app-server WebSocket to untrusted networks.
• Treat .codex/codex-mcp/runs/ as audit data that may contain prompts, command output, file paths, and model responses.
• Review audit artifacts before sharing them.

Pass sandbox explicitly when a narrower Codex sandbox is needed. An explicit sandbox overrides the default permissions profile.

Environment Variables

The environment variable names still use the historical CODEX_MCP_WRAPPER_* prefix for compatibility.

• CODEX_BIN: Codex binary. Defaults to codex.
• CODEX_MCP_WRAPPER_CODEX_HOME: Codex home used by the sidecar. Defaults to CODEX_HOME or ~/.codex.
• CODEX_MCP_WRAPPER_RUN_DIR: audit directory override. Defaults to <cwd>/.codex/codex-mcp/runs.
• CODEX_MCP_WRAPPER_POINTER_DIR: user-level pointer index directory. Defaults to $CODEX_HOME/mcp-wrapper.
• CODEX_MCP_WRAPPER_TIMEOUT_MS: default hard timeout. Defaults to 30 minutes.
• CODEX_MCP_WRAPPER_WAIT_SOFT_TIMEOUT_MS: default soft wait slice. Defaults to 240000. Set to 0 to disable soft returns.
• CODEX_MCP_WRAPPER_APP_SERVER_MODE: shared or private. Defaults to shared.
• CODEX_MCP_WRAPPER_APP_SERVER_URL: shared app-server WebSocket URL. Defaults to ws://127.0.0.1:45123.
• CODEX_MCP_WRAPPER_APP_SERVER_LISTEN: compatibility alias for CODEX_MCP_WRAPPER_APP_SERVER_URL.
• CODEX_MCP_WRAPPER_DEFAULT_PERMISSIONS: default app-server permissions profile. Defaults to yolo.

Development

Install dependencies:

npm ci

Run tests and syntax checks:

npm run ci

Run the local configuration smoke check:

npm run check-config

npm run check-config depends on a local Codex CLI installation and is not part of the GitHub Actions workflow.

Repository Hygiene

The repository intentionally ignores local state:

• node_modules/
• .codex/
• runs/
• .serena/
• editor folders and environment files

Keep audit artifacts out of commits unless a sanitized fixture is deliberately added for a test.

License

UNLICENSED.