claude-codex-team

# 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`.