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

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

```mermaid
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

| Tool | Codex policy | Configuration requirement |
| --- | --- | --- |
| `list_workspaces` | No subprocess | Valid allowlist |
| `analyze_workspace` | `read-only` | Known workspace |
| `modify_workspace` | `workspace-write` | Known workspace with `allowWrite: true` |

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](docs/SECURITY.md) before connecting it.

## Quick start

Install Node.js 24 LTS and Git, then:

```sh
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](docs/ACME_WALKTHROUGH.md), and edit the ignored configuration file
with its absolute local directory. The example `/projects/acme` is a placeholder;
it must exist before startup.

```sh
npm test
npm run doctor
npm start
```

In a second terminal:

```sh
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](examples/acme) 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](docs/CHATGPT_SETUP.md) 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

| Tool | Arguments | Result |
| --- | --- | --- |
| `list_workspaces` | `{}` | Array of `{id, allowWrite}` |
| `analyze_workspace` | `{workspace, task}` | `{workspace, mode, exitCode, output, signal}` |
| `modify_workspace` | `{workspace, task}` | Same result; write configuration checked first |

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

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

Only local operators edit paths. The complete environment reference is in
[GETTING_STARTED.md](docs/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

```sh
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](docs/GETTING_STARTED.md): installation and diagnostics.
- [Architecture](docs/ARCHITECTURE.md): components and trust boundaries.
- [Security](docs/SECURITY.md): enforcement and residual risks.
- [ChatGPT setup](docs/CHATGPT_SETUP.md): verified connection procedure.
- [ACME walkthrough](docs/ACME_WALKTHROUGH.md): thirteen practical phases.
- [Validation](docs/VALIDATION.md): 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](CONTRIBUTING.md). Keep changes small, generic, documented,
and covered by meaningful boundary tests. All repository content must be English.

## Author

Maintained by [julianlopezfp](https://github.com/julianlopezfp).

## License

[MIT](LICENSE).