# Chat to Codex (C2C)

**English** | [Bahasa Indonesia](README.id.md) | [简体中文](README.zh-CN.md)

Bring your AI chat sessions to Codex. Claude Web, ChatGPT, or any chat that speaks remote MCP plans, reasons, and reviews — Codex executes, connected through a secure, read-only MCP bridge.

**No Claude API key. No reverse proxy.** Claude connects to an OAuth-protected remote MCP endpoint and reads only the workspace data it needs.

- **One connector, many projects.** Connect Claude once. Adding, switching, or closing projects requires no new connector, OAuth flow, or pairing.
- **Read-only by construction.** Claude gets no write, shell, commit, or execution tools. Codex remains the sole executor and mutator.
- **Workspace-isolated.** Projects are registered locally. Claude sees opaque workspace IDs, not arbitrary filesystem roots, and every file operation is confined to the granted workspace.
- **Local-first.** Your source code stays on your machine and is exposed only through explicit, read-only MCP requests.

Based on [codex-with-chatgpt](https://github.com/XiaoDuoYa/codex-with-chatgpt).

## Multiple chat brains

One installation serves several AI chats at once. Connect Claude Web,
ChatGPT (Plus — Developer mode → Connectors → Create → paste the `/mcp`
URL → OAuth → pairing code), or both: each holds its own token against
the installation and reads the same registered workspaces. None of them
can write, execute, or commit — Codex stays the only hands.

## How it works

```text
Claude Web (plan · reason · review)
    │
    │  OAuth once · one connector
    ▼
C2C Broker ─────── stable /mcp endpoint
    │
    │  opaque workspace capabilities
    │
    ├── Project A   ◄── Codex session
    ├── Project B   ◄── Codex session
    └── Project C
              ▲
              │  edit · shell · git · tests
              │
        Codex (execute · repair)
```

Claude inspects code, diffs, git state, and recorded test results through the broker, then gives Codex a plan. Codex is the only component that changes anything.

Every Claude-facing capability is read-only. Workspaces are registered locally by Codex/C2C and addressed through opaque IDs. Filesystem paths are canonicalized and confined to the granted workspace, while sensitive files such as `.env`, private keys, and credentials are denied.

## Quick start

Requirements: Node.js ≥ 20, `git`, `cloudflared`, and Claude Web with custom connector support.

```bash
git clone https://github.com/willio/chat-to-codex.git
cd chat-to-codex
pnpm install
pnpm build
node bin/c2c.js install   # systemwide install: ~/.c2c (app + state + launcher)
```

Install the Codex skill:

```bash
mkdir -p ~/.codex/skills/chat-to-codex
cp skill/SKILL.md ~/.codex/skills/chat-to-codex/
```

### Connect Claude — once

From your first project:

```bash
cd ~/Projects/your-project
c2c setup --mode quick
```

On first run, choose how the public endpoint is exposed:

- `c2c setup --mode quick` — temporary Quick Tunnel (no account)
- `c2c setup --mode named --zone example.com` — stable hostname (Cloudflare)

C2C starts the broker and gives you the MCP endpoint and a one-time pairing code when authorization is still needed.

In Claude Web:

**Customize → Connectors → Add custom connector**

Paste the `/mcp` URL, complete OAuth, and enter the pairing code.

Pairing codes expire after approximately five minutes. If necessary, generate another while the authorization page is open:

```bash
c2c pair
```

That's the only Claude-side setup.

### Connect ChatGPT — optional second brain

ChatGPT Plus shares the same broker: both brains read the same registered
workspaces, each with its own token. (Free ChatGPT has no custom connectors.)

Manage connectors on **chatgpt.com in a browser** — the macOS app hides the
settings.

1. Enable Developer mode: **Settings → Connectors** → scroll to **Advanced
   settings** → toggle **Developer mode (beta)**.
2. On the **Plugins** page, the **+** button opens the **New Plugin** dialog:
   - **Name**: `Chat to Codex`
   - **Connection**: keep **Server URL** selected and enter the same `/mcp`
     URL from setup (Streamable HTTP — no `/sse` suffix needed)
   - **Authentication**: **OAuth** — leave the *Advanced OAuth settings*
     client ID **empty**; ChatGPT registers itself dynamically
   - Tick the risk acknowledgment → **Create**
3. ChatGPT shows **Authenticate** → the C2C authorization page opens → run
   `c2c broker pair` and enter the fresh code.
4. **Keep the ChatGPT tab in the foreground** until it finishes connecting —
   backgrounded tabs throttle the token exchange and the connection stalls.
5. Enable the connector via the **+** menu and ask ChatGPT to call
   `list_workspaces`.

### Add another project

```bash
cd ~/Projects/another-project
codex
```

The Codex skill registers the workspace with the existing C2C installation. No new Claude connector, OAuth authorization, or pairing is required.

For a permanent connector URL, use a named Cloudflare tunnel:

```bash
c2c broker tunnel choose --mode named --zone <domain>
```

A stable endpoint is recommended for the single connector you keep in Claude. Quick Tunnels remain useful for development and temporary testing.

Advanced: failover profiles. `--profile <name>` runs an isolated installation (own state, identity, connector) under `~/.c2c/profiles/<name>/` — e.g. a second Claude account on `c2c --profile backup broker start --tunnel`.

## The loop

```text
INIT → PLAN → EXECUTED → REVIEW → DONE
```

Claude retrieves the context it needs through MCP rather than requiring files and diffs to be pasted into the conversation.

Codex executes the plan and records the result:

```bash
c2c record --task <id> --iteration <n> --tests "27 passed"
```

Claude can then independently inspect the resulting diff, git state, and recorded outcome before concluding the task.

### MCP tools

All tools are read-only:

```text
list_workspaces
workspace_info
list_directory
read_file
search_workspace
git_status
git_diff
test_status
execution_summary
```

`test_status` and `execution_summary` only read results previously recorded by Codex. They cannot run commands or tests.

## Security model

**No mutation surface.** The MCP server exposes no file-write, shell, execution, commit, or other mutation tools. Codex retains exclusive execution authority.

**Installation-level authorization.** Claude authorizes one C2C installation rather than individual projects. OAuth uses Dynamic Client Registration, PKCE with S256, short-lived pairing codes, refresh-token rotation, and revocation.

**Workspace capabilities.** Claude can address only workspaces registered locally with C2C. Unknown, missing, or revoked workspace IDs fail closed. Path traversal and symlink escapes are rejected through canonical-path containment.

**No arbitrary filesystem roots.** Claude works with opaque workspace identities. It cannot nominate another directory on the machine and turn it into a workspace.

**Untrusted repository content.** Source files, documentation, issues, and other workspace content are treated as data, never as authorization.

**Short-lived pairing.** Pairing establishes authorization without exposing a long-lived credential in the browser.

See [docs/security.md](docs/security.md) for the threat model and [SECURITY.md](SECURITY.md) for vulnerability reporting, [docs/multi-workspace.md](docs/multi-workspace.md) for the workspace architecture, and [docs/local-e2e.md](docs/local-e2e.md) for end-to-end validation.

## CLI

```text
c2c setup
c2c use
c2c broker start
c2c broker status
c2c broker pair
c2c doctor
c2c pair
c2c unpair
c2c record
c2c start
c2c status
c2c tunnel
c2c session
c2c logs
c2c sandbox-allow
c2c stop
```

Every command supports `--json` for tooling.

`c2c doctor` diagnoses and repairs the local side where possible. If the public endpoint changes and Claude requires the connector to be re-added, it reports the required action explicitly.

For compatibility, `doctor --json` exposes the canonical `connectorRepair` field while retaining `chatgptRepair` as a deprecated alias.

## Compatibility

Chat to Codex began from the ideas and architecture of `codex-with-chatgpt` and has since evolved into an independent implementation.

The current architecture uses one installation-level Claude connector serving multiple locally registered Codex workspaces.

Compatibility with earlier C2C installations is intentionally non-destructive:

- Existing per-project bridges remain supported during migration.
- Legacy `codex-with-chatgpt` state directories can be adopted.
- Compatibility fields and aliases are removed only through explicit, versioned changes.

See [docs/migration.md](docs/migration.md).

## Development

```bash
pnpm install
pnpm typecheck
pnpm test
pnpm build
```

CI runs typecheck, tests, and build on every push.

Key source areas:

```text
src/broker/       installation endpoint and routing
src/mcp/          read-only MCP tools
src/auth/         OAuth 2.1
src/workspaces/   workspace registry and sessions
src/bridge/       per-project bridge compatibility
src/cli/          C2C command-line interface
docs/             architecture, protocol, security and migration
```

## Credits

Chat to Codex builds on the original idea and architecture of [codex-with-chatgpt](https://github.com/XiaoDuoYa/codex-with-chatgpt) by [@XiaoDuoYa](https://github.com/XiaoDuoYa).

The project has since diverged into an independent Claude Web implementation, while preserving attribution to the upstream work and its MIT copyright in [LICENSE](LICENSE).

Chat to Codex is an unofficial community project and is not affiliated with or endorsed by Anthropic or OpenAI.

## License

[MIT](LICENSE)