# codex-bridge

Give Claude Code a Codex sparring partner.

`codex-bridge` is an MCP server that lets Claude Code ask GPT Codex for adversarial planning, code review, debugging, research, and risk triage without leaving your project workflow.

The npm package is `@ndcorder/codex-bridge`. The installed CLI binary and MCP server key are both `codex-bridge`.

## What It Does

- `codex_plan`: get an implementation plan with trade-offs and stop-ship checks before writing code.
- `codex_review`: ask Codex for critical code review, with evidence mode on by default.
- `codex_ask`: brainstorm, sanity-check assumptions, or compare approaches.
- `codex_risk_radar`: score a diff and choose the right collaboration depth.
- `codex_research`: run multi-turn research and write durable research artifacts.
- `codex_debug`: run structured root-cause analysis for hard bugs.
- `codex_stats`, `codex_sessions`, `codex_reset`: inspect and manage bridge sessions.

## Requirements

- Node.js 20 or newer is recommended. CI runs on Node 20 and 22.
- The Codex CLI must be installed, authenticated, and available as `codex` on `PATH`.
- An MCP-capable client such as Claude Code.

Check the Codex CLI before configuring the bridge:

```bash
codex --version
```

## Quick Start

From the project where you want Claude Code to use Codex:

```bash
npx -y @ndcorder/codex-bridge init
```

This command:

- creates or updates `.mcp.json` with a `codex-bridge` stdio server entry
- preserves existing MCP servers
- appends Codex Bridge guidance to `CLAUDE.md` if it is not already present

Restart Claude Code after running the init command.

## Manual MCP Configuration

If you prefer to edit MCP config yourself, add this server entry:

```json
{
  "mcpServers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ndcorder/codex-bridge"]
    }
  }
}
```

## First Workflows

Ask Codex to plan before a risky change:

```text
Use codex_plan to review this approach before implementation:
<describe the feature, constraints, and files involved>
```

Ask for evidence-based review after changes:

```text
Use codex_review with include_diff=true and evidence_mode=true.
Focus on security, data loss, and API regressions.
```

Use risk radar when deciding how much review a diff needs:

```text
Use codex_risk_radar on the current diff and recommend whether to ask,
review, or plan then review.
```

See [`docs/USAGE.md`](docs/USAGE.md) for more workflows.

## Configuration

Environment variables:

- `CODEX_BRIDGE_MODEL` or `CODEX_MODEL`: default model override. Default: `gpt-5.3-codex`.
- `CODEX_BRIDGE_RETRIES`: transient retry count. Default: `1`.
- `CODEX_BRIDGE_RETRY_BACKOFF_MS`: retry backoff base in milliseconds. Default: `500`.
- `CODEX_BRIDGE_MAX_SESSIONS`: max in-memory sessions before oldest-session eviction. Default: `200`.
- `CODEX_BRIDGE_SESSION_TTL_MS`: session inactivity TTL in milliseconds. Default: `86400000`.

Common per-request runtime options:

- `working_dir`: project directory for Codex file access and implicit session key.
- `timeout`: timeout in milliseconds, max `600000`.
- `session_id`: explicit context isolation key.
- `model`: per-request Codex model override.
- `retries`: per-request retry count, max `10`.
- `retry_backoff_ms`: per-request retry backoff base, max `60000`.

Full tool schemas are in [`docs/TOOLS.md`](docs/TOOLS.md).

## Documentation

- [`docs/INSTALL.md`](docs/INSTALL.md): installation, MCP setup, and verification.
- [`docs/USAGE.md`](docs/USAGE.md): practical workflows and examples.
- [`docs/TOOLS.md`](docs/TOOLS.md): complete MCP tool reference.
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md): common setup and runtime failures.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): maintainer architecture notes.
- [`CONTRIBUTING.md`](CONTRIBUTING.md): development workflow.
- [`RELEASE.md`](RELEASE.md): release checklist.
- [`SECURITY.md`](SECURITY.md): vulnerability reporting.
- [`CHANGELOG.md`](CHANGELOG.md): release history.

## Local Development

```bash
npm install
npm run build
npm test
```

Run the full verification suite:

```bash
npm run verify
```

The full suite includes unit tests, the MCP stdio smoke test, and the bake-off black-box suite.

## Release Commands

- `npm run release:bump`: bump patch version in `package.json` and `package-lock.json`.
- `npm run release:bump:patch|minor|major`: explicit semver bump.
- `npm run release:notes`: generate `.release/RELEASE_NOTES.md` from `CHANGELOG.md`.
- `npm run release:pack-check`: build and run `npm pack --dry-run`.
- `npm run release:prepare`: run verify, pack check, and release notes generation.

Publish scoped packages publicly with:

```bash
npm publish --access public
```

## Package Contents

The npm package intentionally ships only runtime output and documentation:

- `dist/src`
- `README.md`
- `CHANGELOG.md`
- `docs/*.md`

Generated research artifacts are written to the consuming project's `.codex-bridge/` directory when `codex_research` receives `working_dir`.