{"id":50761201,"url":"https://github.com/newtro/mcp-codex-bridge","last_synced_at":"2026-06-11T10:01:29.275Z","repository":{"id":359078340,"uuid":"1244425147","full_name":"newtro/mcp-codex-bridge","owner":"newtro","description":"MCP server wrapping the Codex CLI as four callable tools (status/ask/review/implement) for Claude Code. Cross-provider adversarial audits using your existing ChatGPT subscription auth.","archived":false,"fork":false,"pushed_at":"2026-05-20T09:13:42.000Z","size":2629,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T12:46:01.855Z","etag":null,"topics":["claude-code","codex","mcp","mcp-server","model-context-protocol","openai","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/newtro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T08:53:08.000Z","updated_at":"2026-05-20T09:13:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/newtro/mcp-codex-bridge","commit_stats":null,"previous_names":["newtro/mcp-codex-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/newtro/mcp-codex-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newtro%2Fmcp-codex-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newtro%2Fmcp-codex-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newtro%2Fmcp-codex-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newtro%2Fmcp-codex-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/newtro","download_url":"https://codeload.github.com/newtro/mcp-codex-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newtro%2Fmcp-codex-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34192870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","mcp","mcp-server","model-context-protocol","openai","typescript"],"created_at":"2026-06-11T10:01:25.674Z","updated_at":"2026-06-11T10:01:29.224Z","avatar_url":"https://github.com/newtro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"MCP Codex Bridge\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n# mcp-codex-bridge\n\nAn MCP server that wraps the [Codex CLI](https://github.com/openai/codex) as four callable tools so Claude Code (or any MCP-aware client) can invoke Codex inline as a critic, second opinion, or implementer. Uses your existing ChatGPT subscription auth via the Codex CLI; no OpenAI API key required, no per-token cost.\n\n## Why this exists\n\nUpping the ante on **The Adversarial Audit**. The original argument: every agentic workflow needs a second agent breaking the first one's work. The sharper version: that critic should come from a totally different provider. Claude reviewing Claude shares too much training DNA to catch what matters. Codex reviewing Claude catches what same-family review rubber-stamps. This server wires up the handoff so it happens as a tool call inside one session.\n\nBackground reading: [Wiring Agents to Each Other](https://open.substack.com/pub/jnycode/p/wiring-agents-to-each-other?r=3x6reh\u0026utm_campaign=post\u0026utm_medium=web\u0026showWelcomeOnShare=true) on the 42 Insights Substack.\n\n## What it gives Claude Code\n\n| Tool | What it does | Sandbox |\n|------|---------------|---------|\n| `codex_status` | Reports CLI version, sign-in state, default model, and configured timeout. Use to fail fast before expensive calls. | n/a |\n| `codex_ask` | General-purpose query for a second opinion or analysis. Optional context files are prepended to the prompt. | `read-only` |\n| `codex_review` | Adversarial review of a diff or file content. Returns structured BLOCKER / MAJOR / MINOR findings. | `read-only` |\n| `codex_implement` | Hands Codex a spec and a working directory; Codex makes the edits itself. | `workspace-write` |\n\n## Requirements\n\n- Node.js 20 or newer.\n- Codex CLI installed and signed in. Verify with `codex login status`; it should report `Logged in using ChatGPT`.\n- A ChatGPT Plus account or equivalent subscription that the Codex CLI is configured against.\n\nIf Codex is missing or not signed in, every tool returns a structured error with the exact command to run.\n\n## Install\n\n```bash\ngit clone https://github.com/newtro/mcp-codex-bridge.git\ncd mcp-codex-bridge\nnpm install\nnpm run build\n```\n\nThe build produces `dist/index.js` with a shebang, ready to be invoked as a CLI.\n\n## Wire it into Claude Code\n\nClaude Code reads MCP servers from `~/.claude.json`. Add this server at **user scope** so it loads in every project:\n\n```bash\n# Linux / macOS\nclaude mcp add-json --scope user codex-bridge \\\n  '{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"/absolute/path/to/mcp-codex-bridge/dist/index.js\"]}'\n\n# Windows (PowerShell). Note JSON-escaped backslashes.\nclaude mcp add-json --scope user codex-bridge `\n  '{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"D:\\\\Repos\\\\mcp-codex-bridge\\\\dist\\\\index.js\"]}'\n```\n\nVerify:\n\n```bash\nclaude mcp list\n# expect: codex-bridge: node /absolute/path/to/dist/index.js\n```\n\nIn any Claude Code session, `codex_status`, `codex_ask`, `codex_review`, and `codex_implement` will appear under the `codex-bridge` server.\n\n### Alternative: Claude Desktop / generic JSON config\n\nIf your client uses a `claude_desktop_config.json`-style file, drop the same entry into its `mcpServers` block:\n\n```json\n{\n  \"mcpServers\": {\n    \"codex-bridge\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-codex-bridge/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `CODEX_CLI_PATH` | `codex` (resolved on PATH) | Override the Codex binary location, useful when the CLI is installed outside PATH. |\n| `CODEX_MCP_TIMEOUT_MS` | `300000` (5 minutes) | Default per-call timeout. Per-call `timeout_ms` argument overrides this. |\n| `CODEX_HOME` | `~/.codex` | Directory where Codex stores its `config.toml` and credentials. The bridge reads the configured default model from `$CODEX_HOME/config.toml`. |\n\n## Tool reference\n\n### `codex_status`\n\nNo inputs. Returns plain text with CLI version, auth state, default model, default timeout, and warnings if Codex is missing or not signed in.\n\nThe `Default model` is whatever string sits in your `~/.codex/config.toml` (the bridge does not interpret or validate it).\n\n### `codex_ask`\n\n```json\n{\n  \"prompt\": \"string (required)\",\n  \"working_directory\": \"optional cwd\",\n  \"context_files\": [\"optional paths read and prepended to the prompt; truncated at 64 KiB each\"],\n  \"timeout_ms\": \"optional per-call timeout in ms\"\n}\n```\n\nRead-only sandbox. Safe for analysis questions, design discussions, and any prompt where Codex must not touch files.\n\n### `codex_review`\n\n```json\n{\n  \"diff\": \"string (required) - unified diff or full file content\",\n  \"focus_areas\": [\"security\", \"performance\", \"edge cases\"],\n  \"context\": \"what the code is trying to do\",\n  \"working_directory\": \"optional cwd\",\n  \"timeout_ms\": \"optional per-call timeout in ms\"\n}\n```\n\nAsks Codex to act as an adversarial reviewer. Output is markdown organised as BLOCKER / MAJOR / MINOR / What I checked but found clean / Verdict. This is the core cross-provider audit use case.\n\n### `codex_implement`\n\n```json\n{\n  \"spec\": \"string (required) - description of what to build\",\n  \"working_directory\": \"string (required) - absolute path of the repo to modify\",\n  \"files_in_scope\": [\"optional list of files Codex is encouraged to limit edits to\"],\n  \"approval_mode\": \"read-only | workspace-write | danger-full-access (default: workspace-write)\",\n  \"timeout_ms\": \"optional per-call timeout in ms\"\n}\n```\n\nCodex writes the files itself. `workspace-write` is the default so edits actually land; pass `read-only` if you only want a plan, or `danger-full-access` only when Codex needs to run package installs or commands beyond the workspace.\n\n## How error reporting works\n\nEvery failure is one of six classes, each with a `userAction` field telling the calling agent what to do next.\n\n| Class | When it fires | What the agent should do |\n|-------|---------------|---------------------------|\n| `CODEX_NOT_FOUND` | `codex` binary missing or not executable (ENOENT / EACCES). | Install Codex CLI, or set `CODEX_CLI_PATH`. |\n| `CODEX_NOT_AUTHENTICATED` | Codex stderr indicates \"not logged in\" / 401 / similar. | Run `codex login` to sign in with ChatGPT. |\n| `CODEX_RATE_LIMITED` | Stderr or event payload contains a rate-limit / 429 / quota message. | Wait and retry, or check ChatGPT plan usage. |\n| `CODEX_TIMEOUT` | Subprocess did not complete within the per-call timeout. SIGTERM then SIGKILL after 2 seconds. | Raise `CODEX_MCP_TIMEOUT_MS` or split the request. |\n| `CODEX_PARSE_ERROR` | Codex exited 0 but produced no `agent_message` item, or stdout was unparseable JSONL. | Run `codex --version`; the bridge may need updating to match a new event schema. |\n| `CODEX_FAILED` | Unrecognised non-zero exit. | Read the surfaced stderr for the underlying Codex error. |\n\nErrors come back as MCP tool results with `isError: true`. The body includes the class tag, the underlying message, the `userAction` string, and any captured stderr.\n\n## Logs\n\nThe server writes one JSON object per Codex invocation to its own stderr. Successful calls use `errorClass: \"OK\"`; everything else uses one of the six classes above.\n\n```json\n{\"ts\":\"2026-05-20T08:45:35.219Z\",\"tool\":\"codex_review\",\"durationMs\":12340,\"exitCode\":0,\"errorClass\":\"OK\",\"argSummary\":{\"cwd\":null,\"sandbox\":\"read-only\",\"model\":null,\"promptChars\":1234,\"timeoutMs\":300000,\"skipGitCheck\":true,\"addDirs\":0}}\n```\n\nClaude Code surfaces these via `/mcp`. Downstream log aggregators can parse them as JSON lines without a custom format. Prompt content never appears in logs; only the character count.\n\n## Development\n\n```bash\nnpm install\nnpm run build              # tsc -\u003e dist/\nnpm test                   # unit suite (fake spawn; 40 tests in ~330 ms)\nnpm run test:integration   # exercises a real Codex CLI; requires sign-in\nnode tests/smoke-tools-list.mjs   # quick MCP-protocol smoke check\nnode tests/manual-verify.mjs      # exercises all 4 tools end-to-end and rewrites docs/manual-verification.md\n```\n\n## Manual verification log\n\nA live transcript of all four tools running against a real Codex CLI is at [docs/manual-verification.md](docs/manual-verification.md). It is regenerated by `node tests/manual-verify.mjs` and serves as the proof that the integration is working end to end.\n\n## ADR\n\nArchitectural decisions (subprocess over API, four-tool surface, error classification, stack choices, prior art evaluation) are recorded in [docs/adr/0001-codex-mcp-bridge.md](docs/adr/0001-codex-mcp-bridge.md).\n\n## Related reading\n\n- [Wiring Agents to Each Other (42 Insights, Substack)](https://open.substack.com/pub/jnycode/p/wiring-agents-to-each-other?r=3x6reh\u0026utm_campaign=post\u0026utm_medium=web\u0026showWelcomeOnShare=true): the cross-provider adversarial audit argument that motivated this bridge.\n- [Model Context Protocol](https://modelcontextprotocol.io): the open standard this server speaks.\n- [Codex CLI](https://github.com/openai/codex): the upstream tool this bridge wraps.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewtro%2Fmcp-codex-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewtro%2Fmcp-codex-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewtro%2Fmcp-codex-bridge/lists"}