# ChatGPT Codex Bridge

ChatGPT Codex Bridge is a self-hosted MCP server that lets ChatGPT work with
your local codebase through explicit tools. It can read, edit, search, run
terminal commands, show change summaries, and optionally delegate larger
engineering jobs to the local Codex CLI.

The project is designed for people who want ChatGPT to behave more like a local
coding agent while keeping the actual source files, terminal, credentials, and
tooling on their own machine.

## What It Does

- Exposes selected local folders to ChatGPT through MCP.
- Provides workspace-scoped tools for reading, editing, writing, searching, and
  inspecting files.
- Runs Bash and Windows PowerShell commands for tests, builds, git, package
  scripts, and local diagnostics.
- Supports permission modes from read-only to full local development access.
- Adds audit snapshots, change summaries, and session rollback for edits made
  through the bridge.
- Loads project instructions from `AGENTS.md` and `CLAUDE.md`.
- Discovers local skills from bundled and user-configured skill directories.
- Supports ChatGPT Apps-compatible tool cards and workspace UI metadata.
- Can delegate larger tasks to `codex exec` with configurable model, reasoning,
  sandbox, speed, plan policy, and goal policy.
- Includes a local settings page for roots, public URL, permission mode, audit,
  and Codex delegation defaults.

Detailed feature notes are in [docs/features.md](docs/features.md).

## Install

Requirements:

- Node `>=20.12 <27`; Node 22 LTS is recommended.
- npm.
- Git.
- Bash, such as Git Bash or WSL on Windows.
- A public HTTPS tunnel or reverse proxy when connecting from ChatGPT.
- Optional: OpenAI Codex CLI if you want to use `delegate_to_codex`.

Install from a local checkout:

```bash
npm install --include=dev
npm run build
node dist/cli.js init
node dist/cli.js serve
```

After publishing to npm, the same app can be installed globally:

```bash
npm install -g chatgpt-codex-bridge
codex-bridge init
codex-bridge serve
```

The legacy `devspace` command is also kept as a compatibility alias.

## Quick Start

1. Start an HTTPS tunnel to the local server port, usually `7676`.

   ```bash
   cloudflared tunnel --url http://127.0.0.1:7676
   ```

2. Initialize the bridge.

   ```bash
   codex-bridge init
   ```

   During setup, enter:

   - the local folders ChatGPT may open;
   - the local port, usually `7676`;
   - the public HTTPS origin, without `/mcp`.

3. Start the MCP server.

   ```bash
   codex-bridge serve
   ```

4. Add this MCP endpoint to ChatGPT or another MCP host:

   ```text
   https://your-tunnel-host.example.com/mcp
   ```

5. Approve the connection with the Owner password printed by `init`.

The default local settings page is:

```text
http://127.0.0.1:7676/settings
```

Full deployment instructions are in [docs/deployment.md](docs/deployment.md).

## Configuration

The bridge stores local config and auth files under:

```text
~/.devspace/config.json
~/.devspace/auth.json
```

The `~/.devspace` path is intentionally retained for backward compatibility.
You can override it with `DEVSPACE_CONFIG_DIR`.

Common settings:

| Setting | Default | Purpose |
| --- | --- | --- |
| `DEVSPACE_ALLOWED_ROOTS` | current directory during setup | Filesystem roots ChatGPT may open. |
| `DEVSPACE_PUBLIC_BASE_URL` | required | Public origin, without `/mcp`. |
| `DEVSPACE_PERMISSION_MODE` | `safe_shell` | Tool permission policy. |
| `DEVSPACE_CODEX_DELEGATION` | `1` | Enables `delegate_to_codex`. |
| `DEVSPACE_CODEX_DEFAULT_MODEL` | `gpt-5.5` | Default Codex model. |
| `DEVSPACE_CODEX_DEFAULT_REASONING_EFFORT` | `xhigh` | Default reasoning effort. |
| `DEVSPACE_CODEX_DEFAULT_SPEED` | `normal` | Codex service tier, `normal` or `fast`. |

See [docs/configuration.md](docs/configuration.md) for the full reference.

## Security Model

This bridge gives a remote MCP client access to local development capabilities.
Treat it like granting a trusted coding partner access to your machine.

The safety model is based on:

- a narrow filesystem allowlist;
- an Owner password approval flow;
- OAuth-protected MCP sessions;
- Host header validation;
- permission modes for edits, shells, and Codex delegation;
- audit logs and rollback support for bridge-made file edits.

Do not expose it with broad roots like `~`, `/`, or `C:\` unless you understand
the risk. Keep `~/.devspace/auth.json` private.

More details are in [docs/security.md](docs/security.md).

## Package

Create a distributable npm tarball:

```bash
npm run build
npm pack
```

The package includes `dist`, `docs`, `scripts`, and `README.md`.

## Local Development

```bash
npm install --include=dev
npm run dev
npm run typecheck
npm test
npm run build
npm run start
```

## License

MIT