codex-chatgpt-bridge

# Codex ChatGPT Bridge **Codex ChatGPT Bridge** is a local MCP bridge that lets ChatGPT web sessions connect to your real machine, inspect user-approved local files, and delegate local work to Codex. It is for people who want the ChatGPT web experience to act as the researcher, planner, reviewer, or project lead, while Codex remains the local executor with access to the real working tree. This is an unofficial local-first bridge. It is not an OpenAI API wrapper, and it does not move your project into a remote sandbox. > Alpha status: the default mode is intentionally conservative. No local files are exposed until the user grants folders or explicitly enables full delegate mode. ## What It Can Do - Let ChatGPT web read and search approved local project folders through MCP tools. - Let ChatGPT web write files only inside explicitly writable grants. - Let ChatGPT web ask local Codex to run bounded repo, shell, or GUI tasks. - Let users choose between a safer restricted mode and a powerful full delegate mode. - Help installers detect broken tunnels, stale ChatGPT app URLs, and unstable quick tunnels without printing secrets. ## Core Idea ChatGPT web is often the better discussion surface for deep research, product thinking, planning, and review. Codex is often the better local executor because it can inspect and modify the actual files on your machine. This bridge connects those two roles: ```text ChatGPT web model -> MCP App / connector -> stable HTTPS tunnel or local endpoint -> Codex ChatGPT Bridge -> local files and local Codex ``` ## One-Line Install With Codex Ask Codex: ```text Install https://github.com/dalomeve/codex-chatgpt-bridge on this computer. ``` That should be enough. Codex should read this README and `docs/agent-install.md`, install the bridge, create a local config, start the service, ask which folders ChatGPT may access, and help create the ChatGPT MCP app/connector. After installation, Codex should not stop at "installed." It should verify that ChatGPT can call the bridge with `bridge_status` or `list_grants`. If browser automation is unavailable, it should give the exact manual remaining step. ## Install Manually Use an isolated tool install: ```bash uv tool install git+https://github.com/dalomeve/codex-chatgpt-bridge.git ``` Or clone for local development: ```bash git clone https://github.com/dalomeve/codex-chatgpt-bridge.git cd codex-chatgpt-bridge python3.11 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` Create config and start the bridge: ```bash codex-chatgpt-bridge init codex-chatgpt-bridge grant ~/Projects/my-app --name my-app codex-chatgpt-bridge run ``` Check local health: ```bash curl http://127.0.0.1:8766/healthz ``` ## ChatGPT Setup The local MCP endpoint is: ```text http://127.0.0.1:8766/mcp ``` If ChatGPT web cannot reach local `127.0.0.1`, expose the local bridge through a stable HTTPS tunnel and use the HTTPS URL in ChatGPT's Developer Mode app or MCP connector. A stable tunnel is part of a successful install. A random `trycloudflare.com` quick tunnel is useful for a short smoke test, but it should not be treated as a long-term connector URL. Recommended tunnel order: 1. OpenAI Secure MCP Tunnel, when available. 2. A named Cloudflare Tunnel or another stable, access-controlled HTTPS endpoint. 3. A temporary `trycloudflare.com` quick tunnel only for smoke tests. The bridge supports two connector URLs: - Bearer-protected URL: `/mcp` - ChatGPT no-auth secret URL: `/mcp/<connector-secret>` Use the no-auth secret URL when ChatGPT's app setup only offers OAuth, unauthenticated, or mixed auth. Treat the full secret URL as a credential. Print setup instructions without secrets: ```bash codex-chatgpt-bridge print-chatgpt-setup ``` Display the local bearer token and secret connector URL on your own machine: ```bash codex-chatgpt-bridge print-chatgpt-setup --show-token ``` Diagnose a connector URL or tunnel log without printing the connector secret: ```bash codex-chatgpt-bridge tunnel-doctor --url <connector-url> --log <tunnel-log> ``` When using ChatGPT web, type `@` and select the bridge app from the menu so it becomes a real app chip. Plain text such as `@Codex ChatGPT Bridge` is not enough. ## Typical Use Cases Ask ChatGPT web to read local project context: ```text @Codex ChatGPT Bridge read the README, package config, and src tree for this project. Explain what this repo does and where the main extension points are. ``` Ask ChatGPT web to review local code and delegate fixes: ```text @Codex ChatGPT Bridge inspect the current repo, identify the failing test, and ask local Codex to implement the smallest fix. Run the focused tests before reporting back. ``` Ask ChatGPT web to use Codex as a local device agent: ```text @Codex ChatGPT Bridge call codex_delegate with permission_level=repo_edit. Task: update the CLI help text, add tests, and run the test suite. Expected result: tests pass and the diff contains only the requested change. ``` Ask ChatGPT web to drive a local GUI task, if you explicitly enabled that level: ```text @Codex ChatGPT Bridge call codex_delegate with permission_level=gui_control. Task: open TextEdit and type 你好. Expected result: TextEdit is open and contains the requested text. ``` ## Modes ### Restricted Mode Restricted mode is the default. ChatGPT can only access folders the user grants: ```bash codex-chatgpt-bridge grant ~/Projects/my-app --name my-app codex-chatgpt-bridge grant ~/Projects/my-app --name my-app --write codex-chatgpt-bridge grant ~/Projects/my-app --name my-app --write --execute ``` Each grant can allow: - `read`: search and read files. - `write`: write files through bridge tools. - `execute`: ask local Codex to work in that directory. Even inside grants, restricted mode blocks paths that look like secrets, including `.env`, `.ssh`, private keys, certificates, token files, and credential-like names. ### Full Delegate Mode Full delegate mode is for a trusted personal machine where you explicitly want ChatGPT web to act as the planning brain and local Codex as the local device agent. ```bash codex-chatgpt-bridge set-mode full_delegate codex-chatgpt-bridge enable-codex-tasks codex-chatgpt-bridge set-tool-profile delegate ``` In `full_delegate`, the bridge no longer requires path grants and no longer blocks sensitive-looking paths. The connector can ask the bridge to read, write, and execute anywhere the local bridge process can access. Codex session tools default to full local execution. Use this only when the connector URL is private and you trust the ChatGPT session that will call it. Return to safer defaults: ```bash codex-chatgpt-bridge set-mode restricted codex-chatgpt-bridge set-tool-profile full codex-chatgpt-bridge disable-codex-tasks ``` ## Tools - `bridge_status`: check bridge health and available capabilities. - `set_bridge_mode`: switch between restricted grants and full delegate mode. - `grant_path`: add a persisted read, write, or execute grant from ChatGPT. - `revoke_grant`: remove a persisted grant from ChatGPT. - `list_grants`: show approved directories and permissions. - `search_files`: search readable grants with ripgrep. - `read_file`: read a UTF-8 text file inside a readable grant. - `write_file`: write text inside a writable grant. - `codex_task_run`: ask local Codex to work in an executable grant. Hidden and disabled by default. - `codex_delegate`: hand one structured local computer, file, shell, repo, GUI, or project task to local Codex in a single MCP call. - `codex_session_start`: start a persistent local Codex session for project work. - `codex_session_continue`: continue a recorded local Codex session. - `codex_session_list`: list recorded local Codex sessions. - `codex_session_status`: inspect one recorded local Codex session. The default tool profile is `full`, which exposes low-level file, grant, and Codex session tools. For ChatGPT web as the planning brain and local Codex as the device agent, use the `delegate` profile. It exposes one main action tool, `codex_delegate`, plus read-only status tools. ## ChatGPT Host Limits Developer Mode and MCP app availability are account and rollout dependent. Treat the current account UI and an actual `bridge_status` tool call as the source of truth. ChatGPT web may still block destructive custom MCP calls before they reach this bridge. If ChatGPT replies with `blocked_by_openai_safety_check` or says the tool call was blocked by OpenAI's safety check, the local bridge did not receive that request and no local Codex session was started. ## macOS Service ```bash codex-chatgpt-bridge install-launch-agent --load ``` Logs are written to: ```text ~/Library/Logs/codex-chatgpt-bridge/ ``` ## Security Notes - Do not expose this bridge to the public internet without authentication or a tunnel policy you understand. - Do not publish the bearer token, connector secret URL, tunnel runtime key, `.env` contents, cookies, or private local paths. - Prefer project-level grants over full-home or full-disk grants. - Do not grant write or execute access to large directories unless you are comfortable with that risk. - Review ChatGPT tool calls before allowing broad write or execute behavior. - Treat `full_delegate` as device-agent mode: it is powerful enough to modify local files and run Codex on your machine. ## Development ```bash python3.11 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ruff check . pytest ``` --- # Tool List **Codex ChatGPT Bridge** is a local MCP bridge that connects the ChatGPT web interface to your local machine, allowing it to read authorized local files and delegate tasks to Codex for execution. It is suitable for workflows where the ChatGPT web interface handles research, planning, discussion, review, and acceptance, while Codex performs local modifications, commands, tests, or GUI operations on actual project files. This is an unofficial, local-first bridge. It is not an OpenAI API wrapper and does not move your projects to a remote sandbox. > Current status: alpha. The default mode is conservative. Unless a user authorizes a directory or explicitly enables full delegate, local files are not exposed. ## Capabilities - Allow the ChatGPT web interface to read and search authorized local project directories through MCP tools. - Write files only in directories explicitly granted write permission. - Enable the ChatGPT web interface to delegate tasks to local Codex, such as repo management, shell commands, GUI operations, or project tasks. - Provide users with the option to choose between a restricted mode and a powerful full delegate mode. - Assist with diagnosing broken tunnels, outdated ChatGPT app URLs, and unstable quick tunnels without printing secrets. ## Core Concept The ChatGPT web interface excels at in-depth research, product thinking, planning, and acceptance, while Codex is better suited for local execution, as it can see and modify the actual workspace on the machine. This bridge connects the two: ```text ChatGPT Web Interface Model -> MCP App / connector -> Stable HTTPS tunnel or local endpoint -> Codex ChatGPT Bridge -> Local Files and Local Codex ``` ## One-Line Installation with Codex You can instruct Codex to install the bridge: ```text Install https://github.com/dalomeve/codex-chatgpt-bridge to this machine. ``` This should be sufficient. Codex should read this README and `docs/agent-install.md`, install the bridge, create local configurations, start the service, and prompt for folder authorization. It should then verify that ChatGPT can call `bridge_status` or `list_grants`. If the environment cannot automate browser interactions, it should provide precise manual steps. ## Manual Installation Install using a standalone tool: ```bash uv tool install git+https://github.com/dalomeve/codex-chatgpt-bridge.git ``` Or clone and develop locally: ```bash git clone https://github.com/dalomeve/codex-chatgpt-bridge.git cd codex-chatgpt-bridge python3.11 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` Create configurations and start: ```bash codex-chatgpt-bridge init codex-chatgpt-bridge grant ~/Projects/my-app --name my-app codex-chatgpt-bridge run ``` Check local service: ```bash curl http://127.0.0.1:8766/healthz ``` ## Connecting to ChatGPT The local MCP address is: ```text http://127.0.0.1:8766/mcp ``` If the ChatGPT web interface cannot directly access `127.0.0.1`, you need to expose the local bridge using a stable HTTPS tunnel and specify the HTTPS address in the ChatGPT Developer Mode app or MCP connector. A stable tunnel is a prerequisite for successful installation. A temporary `trycloudflare.com` quick tunnel can be used for brief smoke testing but should not be used as a long-term connector URL. Recommended tunnel order: 1. OpenAI Secure MCP Tunnel, if available for your account and environment. 2. Named Cloudflare Tunnel or other stable, access-controlled HTTPS endpoints. 3. Temporary `trycloudflare.com` quick tunnel for smoke testing. The bridge supports two types of connection addresses: - Bearer-protected address: `/mcp` - ChatGPT secret-free address: `/mcp/<connector-secret>` If ChatGPT creates an app with OAuth, unauthenticated, or hybrid authentication, use the secret-free address. This complete URL serves as the connection credential and should not be shared publicly. Print setup instructions without secrets: ```bash codex-chatgpt-bridge print-chatgpt-setup ``` Display bearer token and secret connector URL on your machine: ```bash codex-chatgpt-bridge print-chatgpt-setup --show-token ``` Diagnose connector URL or tunnel logs while hiding connector secrets: ```bash codex-chatgpt-bridge tunnel-doctor --url <connector-url> --log <tunnel-log> ``` When using ChatGPT, type `@` and select the bridge app from the menu to create a proper app chip. Typing `@Codex ChatGPT Bridge` without further specification will not engage the tool. ## Typical Use Cases Let ChatGPT read local project context: ```text @Codex ChatGPT Bridge read the README, package configuration, and src directory of this project. Explain what this repository does and where the main extension points are. ``` Let ChatGPT review local code and delegate fixes to Codex: ```text @Codex ChatGPT Bridge check the current repo, identify failing tests, and have local Codex make minimal fixes. Run relevant tests before reporting. ``` Let ChatGPT use Codex as a local device agent: ```text @Codex ChatGPT Bridge call codex_delegate with permission_level=repo_edit. Task: Update CLI help text, add tests, and run the test suite. Expected result: Tests pass, diff includes only changes related to this request. ``` Let ChatGPT drive local GUI if explicitly granted: ```text @Codex ChatGPT Bridge call codex_delegate with permission_level=gui_control. Task: Open TextEdit and input "Hello". Expected result: TextEdit is open with the specified text. ``` ## Modes ### Restricted Mode Restricted is the default mode. ChatGPT can only access user-authorized directories: ```bash codex-chatgpt-bridge grant ~/Projects/my-app --name my-app codex-chatgpt-bridge grant ~/Projects/my-app --name my-app --write codex-chatgpt-bridge grant ~/Projects/my-app --name my-app --write --execute ``` Each grant can include: - `read`: Search and read files. - `write`: Write files through bridge tools. - `execute`: Allow local Codex to work in that directory. Even within authorized directories, restricted mode blocks paths resembling keys, such as `.env`, `.ssh`, private keys, certificates, token files, and credential-like filenames. ### Full Delegate Mode Full delegate mode is for trusted personal machines where you want ChatGPT to act as the controlling brain and local Codex as the device agent. ```bash codex-chatgpt-bridge set-mode full_delegate codex-chatgpt-bridge enable-codex-tasks codex-chatgpt-bridge set-tool-profile delegate ``` Under `full_delegate`, the bridge no longer requires path grants and does not block paths resembling keys. The connector can request the bridge to read, write, and execute any path accessible by the local bridge process. Codex session tools use full local execution by default. Use this mode only when the connector URL is secret and you trust the ChatGPT session calling it. Revert to secure defaults: ```bash codex-chatgpt-bridge set-mode restricted codex-chatgpt-bridge set-tool-profile full codex-chatgpt-bridge disable-codex-tasks ``` ## Available Tools - `bridge_status`: Check bridge health and capabilities. - `set_bridge_mode`: Switch between restricted and full delegate modes. - `grant_path`: Add persistent read, write, or execute authorization from ChatGPT. - `revoke_grant`: Remove persistent authorization from ChatGPT. - `list_grants`: View authorized directories and permissions. - `search_files`: Search readable authorized directories with ripgrep. - `read_file`: Read UTF-8 text files within readable authorized directories. - `write_file`: Write text files within writable authorized directories. - `codex_task_run`: Run tasks with local Codex in executable authorized directories. Hidden and disabled by default. - `codex_delegate`: Delegate structured local computer, file, shell, repo, GUI, or project tasks to local Codex with a single MCP call. - `codex_session_start`: Start a sustainable local Codex session. - `codex_session_continue`: Continue a recorded local Codex session. - `codex_session_list`: List recorded local Codex sessions. - `codex_session_status`: Check the status of a local Codex session. The default tool profile is `full`, exposing underlying file, authorization, and Codex session tools. For ChatGPT to act as the controlling brain and local Codex as the device agent, use the `delegate` profile. It mainly exposes `codex_delegate` and a few read-only status tools. ## ChatGPT Host Limitations Developer Mode and MCP app availability depend on account and gradual rollout. Verify with your current account UI and a real `bridge_status` tool call. ChatGPT may still intercept destructive custom MCP calls before they reach the bridge. If ChatGPT replies with `blocked_by_openai_safety_check` or mentions that tool calls were intercepted by OpenAI safety checks, the local bridge did not receive the request and did not start a local Codex session. ## macOS Persistent Service ```bash codex-chatgpt-bridge install-launch-agent --load ``` Logs are located at: ```text ~/Library/Logs/codex-chatgpt-bridge/ ``` ## Security Notes - Do not expose this bridge to the public internet without authentication or a trusted tunnel policy. - Do not publicly share the bearer token, connector secret URL, tunnel runtime key, `.env` contents, cookies, or private local paths. - Prefer granting permissions to individual project directories over entire home or disk grants. - Avoid granting write or execute access to large directories unless you are comfortable with the risk. - Review ChatGPT tool calls before allowing broad write or execute permissions. - Treat `full_delegate` as device-agent mode: it is powerful enough to modify local files and run Codex on your machine. ## Development ```bash python3.11 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ruff check . pytest ```