ChatGPT Codex CLI Bridge

Delegate engineering tasks from a ChatGPT conversation to Codex CLI in a pre-authorized local project through MCP.

Version 0.1 is a small, synchronous reference implementation using Node.js 24, the official MCP TypeScript SDK, and Streamable HTTP at /mcp. Every public example uses the fictional ACME project.

Why this exists

A conversation can describe a task, but a local engineering agent needs a project, a permission policy, and a bounded process lifecycle. This bridge makes that handoff explicit and reproducible without giving the conversation control over local filesystem paths.

Related MCP server: cursor-agent-bridge

The problem and the solution

An arbitrary path or shell-command endpoint would give a remote caller excessive control over the host. Instead, the bridge accepts a workspace identifier and a natural-language task. An operator-owned allowlist resolves the identifier locally. The selected MCP tool determines the Codex sandbox; write permissions also require a separate configuration decision.

Architecture

flowchart TD
  C[ChatGPT conversation] -->|MCP tool request| B[Bridge: validation and allowlist]
  B -->|Fixed argv and bounded process| X[Codex CLI sandbox]
  X --> A[ACME local repository]
  X -->|Bounded result| B
  B -->|MCP response| C

How it works

1. ChatGPT selects acme from list_workspaces.

2. The bridge validates the identifier and task, then resolves the allowlist.

3. It launches Codex using spawn(), separate arguments, shell: false, and stdin.

4. A deadline and combined stdout/stderr byte limit bound the run.

5. The result returns as MCP text containing JSON; known workspace paths are redacted.

Security model

Defaults are loopback-only, writes disabled, network-disabled agent commands, 90-second execution, 64 KiB output, and one active task. Unknown identifiers, traversal strings, extra tool arguments, and write-disabled operations fail closed. There is no generic shell endpoint or sandbox-bypass mode.

This is an authorization boundary, not a complete host isolation boundary. Codex can execute commands under its own sandbox. Read-only does not mean all reads are confined to ACME, and the allowlist cannot protect host secrets by itself. Use an isolated OS account or VM with only approved files and reviewed Codex configuration. Read the security model before connecting it.

Quick start

Install Node.js 24 LTS and Git, then:

git clone https://github.com/julianlopezfp/chatgpt-codex-cli-bridge.git
cd chatgpt-codex-cli-bridge
npm install
npm install -g @openai/codex
codex --version
codex login
cp .env.example .env
cp config/workspaces.example.json config/workspaces.json

Create a separate ACME Git repository following the walkthrough, and edit the ignored configuration file with its absolute local directory. The example /projects/acme is a placeholder; it must exist before startup.

npm test
npm run doctor
npm start

In a second terminal:

npm run smoke

npm run dev restarts on source changes. npm ci installs the committed lockfile. Windows users should follow the WSL2 instructions in the getting-started guide.

ACME example

Analyze the ACME project and tell me why the authentication tests are failing. Do not modify anything.

ChatGPT calls analyze_workspace with workspace: "acme". The operator checks that ACME remains unchanged. After explicitly enabling writes locally:

Apply the username normalization fix to ACME and run the relevant tests.

ChatGPT calls modify_workspace. The operator reviews the diff and test results. The included ACME fixture deliberately has one failing test; it is copied into a separate repository and excluded from the bridge's test suite.

Connecting ChatGPT

Use developer mode with a supported account/workspace and a remote MCP connection. For this loopback service, prefer Secure MCP Tunnel. The complete current setup guide cites official documentation checked on October 1, 2026. Account policy and interface labels can change. The bridge does not configure a ChatGPT account or create tunnel credentials automatically.

MCP tools

Identifiers match ^[a-z][a-z0-9_-]{0,63}$. Tasks are nonempty, at most 8,000 characters, and cannot contain NUL bytes. Tool errors set isError: true and return {code, message}. Schema errors are handled by the MCP SDK.

Configuration

{
  "acme": { "path": "/projects/acme", "allowWrite": false }
}

Only local operators edit paths. The complete environment reference is in GETTING_STARTED.md. Changes require a restart. No workspace paths are advertised in tool metadata or listings; exact configured and canonical workspace path strings are redacted from process output. This is best-effort redaction, not a general secret or arbitrary-path filter.

Testing

npm test
npm run doctor
npm run smoke

Tests use temporary directories, a deterministic subprocess fixture, and a real MCP HTTP client. They cover identifier validation, config failures, write gating, symlink retargeting, argv construction, output limits, timeouts, process errors, transport validation, and concurrency. They require no model calls or credentials. Doctor checks Node, config, workspace directories, CLI availability, and local login status. Model-backed acceptance checks are documented separately.

Documentation

• Getting started: installation and diagnostics.

• Architecture: components and trust boundaries.

• Security: enforcement and residual risks.

• ChatGPT setup: verified connection procedure.

• ACME walkthrough: thirteen practical phases.

• Validation: reproducible checks and release evidence.

Current limitations

Synchronous jobs can outlast client deadlines; there are no resumable sessions, job persistence, cancellation API, or execution history. Output is a bounded combined CLI transcript rather than a stable model-result schema. There is no public-server authentication layer. Native Windows process-tree termination is best effort; POSIX process groups are used on Linux/macOS. Sandbox enforcement and CLI behavior depend on the installed Codex version and platform.

Roadmap

Resumable sessions, asynchronous jobs, cancellation, audit logs, Docker packaging, authenticated remote deployment, per-workspace profiles, structured results, and execution history can be evaluated in later versions.

Contributing

See CONTRIBUTING.md. Keep changes small, generic, documented, and covered by meaningful boundary tests. All repository content must be English.

Author

Maintained by julianlopezfp.

License

MIT.