Local MCP bridge

Install in your repo

Use ChatGPT like your local coding agent.

Install the CLI, run setup inside a project, then paste the copied Server URL into ChatGPT Developer Mode. ChatGPT gets bounded tools for the launch project and any additional projects you explicitly allow.

npm install -g codexpro
codexpro setup

Main docs may be ahead of npm; check the npm version or use a source checkout for unreleased behavior.

explicit project access token-protected URL safe bash default repo-backed context

Install CodexPro Star on GitHub View npm package

Selected local project your repo · your ChatGPT session · your machine

bounded

01 Local repo

AGENTS.md, git state, selected files, and .ai-bridge plans.

02 CodexPro

Token-protected MCP server with workspace, bash, write, and tool modes.

03 ChatGPT app

Read, search, edit, review, verify, or hand off through Developer Mode.

Not a model proxyuses your own ChatGPT account

Not a quota bypassproduct limits still apply

Not an OS sandboxkeep roots scoped to the repo

After setup codexpro start Run this from the same repo when you want ChatGPT connected again.

01 Install

Run npm install -g codexpro once.

02 Setup

Run codexpro setup inside your project.

03 Paste

Paste the copied Server URL when creating the ChatGPT plugin.

Use the account you already have

Give ChatGPT a real local workspace, not another paste buffer.

CodexPro is for builders who already pay for ChatGPT and want that subscription to do more than answer questions. It gives ChatGPT a local project bridge: file reads, exact edits, source writes, search, git status, git diff, and allowlisted verification commands.

Codex and ChatGPT are different product surfaces. If one workflow is unavailable and another surface you already have access to is still available, CodexPro lets you work against the same local repo without changing either product's limits.

If your ChatGPT account exposes a stronger model in the web app, and that model surface can call Developer Mode apps, CodexPro lets it work against your local repo through MCP. Some model surfaces cannot call connectors or MCP tools directly. CodexPro does not provide, proxy, resell, or unlock models; it gives compatible ChatGPT sessions local coding tools and repo context.

ChatGPT web can see AGENTS.md, .ai-bridge, git state, source files, and selected Codex-style context

Normal coding mode can read, write, edit, search, and verify directly in the workspace

Pro planning mode can export a durable context bundle for sessions where MCP tools are unavailable

Best account fit A ChatGPT web surface with custom MCP access. OpenAI currently documents full write/modify MCP for Business and Enterprise/Edu, with read/fetch MCP access for Pro.

Planner to executor

Let ChatGPT plan, then run a local agent on your machine.

Handoff mode keeps ChatGPT planning-only. ChatGPT writes .ai-bridge/current-plan.md, then you decide whether to run a local implementation agent from your terminal.

codexpro execute-handoff runs the saved plan through OpenCode, Pi, Codex, or a custom command, then collects status, stdout/stderr excerpts, and the final git diff back into .ai-bridge for ChatGPT review.

Preview first

codexpro execute-handoff --agent opencode --model provider/model --dry-run

Run locally

codexpro execute-handoff --agent opencode --model provider/model

Custom agent

codexpro execute-handoff --agent custom --command "my-agent --task-file {{plan_file}}"

Result files

.ai-bridge/agent-status.md
.ai-bridge/implementation-diff.patch
.ai-bridge/execution-log.jsonl

Compared with generic workspace bridges

CodexPro is the ChatGPT-first local coding loop.

The transport can look similar: local MCP server, workspace root, and a tunnel. CodexPro is more opinionated. It is built for one job: make ChatGPT Developer Mode useful against explicitly allowed local projects without widening the trust boundary.

That means setup first, explicit safety modes, repo-backed context files, reviewable diffs, compact cards, and no model proxying, account pooling, quota bypassing, third-party Pro scraping, or OS sandbox claims.

Product loop Install, setup in a repo, allow only the projects you choose, then inspect/edit/verify.

Control surface Bash, write/edit, tool mode, Codex session reads, and handoff execution are separate switches.

Context model AGENTS.md and .ai-bridge keep durable project memory in files you can review.

Trust model Your ChatGPT account, your local repo, your explicit tunnel and token.

Quick start

Install once, then run setup in your repo.

The default path uses normal coding mode, workspace writes, safe bash, and a tunnel you choose during setup. After setup, daily startup is just codexpro start.

Install globally

npm install -g codexpro

Run guided setup

codexpro setup

Turn on Developer Mode

In ChatGPT, open Settings -> Security and login. Turn on Developer mode and keep Enforce CSP in developer mode enabled. Then open Settings -> Plugins, stay on the Plugins tab, and click the circular + beside Search plugins.

Create a ChatGPT plugin

In New Plugin, name it CodexPro. Use Connection: Server URL and paste the copied URL. The form may default to OAuth; set Authentication to No Authentication / None before creating the plugin.

Use CodexPro in chat

Ask ChatGPT to inspect files, make scoped edits, and verify with search, read, bash, and git tools.

Tunnel choices

Pick the URL strategy that matches your workflow.

Fastest

Cloudflare quick tunnel

No account flow. Good for demos. The URL changes every restart, so you must update the ChatGPT app Server URL each time.

codexpro start

Recommended

ngrok free dev domain

Best simple stable URL. Create a free ngrok account, use the assigned dev domain, and keep the same ChatGPT app URL across restarts.

codexpro ngrok --hostname your-name.ngrok-free.dev

Custom

Cloudflare named tunnel

Use your own domain, such as codexpro.example.com, and keep one ChatGPT URL.

codexpro stable --hostname codexpro.example.com --tunnel-name codexpro

Tailnet

Tailscale Funnel

Use your device's .ts.net hostname when your tailnet already allows public Funnel HTTPS.

codexpro tailscale --hostname your-device.your-tailnet.ts.net

ngrok setup

Use ngrok's free dev domain for a fixed ChatGPT connector URL.

ngrok free accounts include a dev domain. Find it in the ngrok dashboard under Universal Gateway -> Domains, save it once in CodexPro, and future starts from the same repo are just codexpro start.

That means users do not need to change ChatGPT settings every time they restart CodexPro.

One-time ngrok auth

ngrok config add-authtoken YOUR_NGROK_TOKEN

Save the CodexPro workspace profile

codexpro settings set --tunnel ngrok --hostname your-name.ngrok-free.dev

Daily start

codexpro start

Quick tunnel

codexpro start --tunnel cloudflare

Named tunnel with your domain

cloudflared tunnel login
cloudflared tunnel create codexpro
cloudflared tunnel route dns codexpro codexpro.example.com

Daily stable start

codexpro stable --hostname codexpro.example.com --tunnel-name codexpro

Cloudflare setup

Start instantly with quick tunnels or keep a custom domain with named tunnels.

CodexPro can install cloudflared into ~/.codexpro/bin when it is missing. No sudo, Homebrew, apt, or winget step is required for the default path.

Quick tunnels are disposable. If you own a domain, use a Cloudflare named tunnel and route DNS to a hostname such as codexpro.example.com. The hostname stays the same across restarts, so the ChatGPT app Server URL does not need to change.

Modes

Use the right level of control for the task.

Normal coding

Default. ChatGPT can inspect, write, edit, search, and verify inside the workspace.

Handoff

Planning-only. ChatGPT writes .ai-bridge/current-plan.md and Codex executes locally.

Pro planning

Exports a durable context file for models or surfaces that cannot call connectors or MCP tools directly.

Complete setup data

Everything needed to install, connect, use, and stop CodexPro.

This page keeps the high-signal details in one place: commands, ChatGPT app fields, tunnel choices, tools, saved settings, safety defaults, and useful links.

Install

Install globally once

npm install -g codexpro

This gives users the simple codexpro command everywhere.

First run

Guided setup

codexpro setup

Setup saves the tunnel provider, hostname, port, mode, and token for the current workspace.

Daily start

Reuse saved profile

codexpro start

After setup, future starts from the same repo reuse the saved profile automatically.

ChatGPT settings path

Enable plugins once

Open: ChatGPT Settings
Go to: Security and login
Enable: Developer mode
Keep on: Enforce CSP in developer mode
Then: Plugins -> Plugins tab -> + beside Search plugins

This is a one-time ChatGPT setting. CodexPro widgets work with CSP enabled.

Create Plugin fields

Paste the copied URL

Name: CodexPro
Description: Local workspace bridge for ChatGPT coding
Connection: Server URL
Server URL: Paste copied CodexPro URL
Authentication: No Authentication / None

The form may initially show OAuth; select No Authentication / None. The copied Server URL includes a private CodexPro token and is for a personal connector only. Shared or multi-user production deployments require OAuth or Authorization-header authentication.

Doctor

Preflight checks

codexpro doctor

Checks Node, build output, saved profile, port availability, tunnel prerequisites, clipboard support, and browser-open support.

Settings

Manage saved profiles

codexpro settings
codexpro settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
codexpro settings delete --yes

Use settings to switch providers, reuse another repo setup, or delete a workspace preference.

Controls

Terminal keys

Enter: Open ChatGPT connector settings
c: Copy Server URL again
o: Open local admin dashboard
q: Stop CodexPro

Local admin

Setup, profile, and status

Press o to open the token-protected admin dashboard. It shows install/start commands, ChatGPT connection steps, saved profile settings, modes, allowed roots, and advanced restart shortcuts.

Default standard tools

Focused local repo actions exposed through MCP.

codexpro server_config codexpro_self_test open_current_workspace open_workspace tree search read view_image write edit bash show_changes read_handoff wait_for_handoff export_pro_context handoff_to_agent

Safety defaults

Blocked paths

.env, private keys, .git, node_modules, generated build/cache folders, paths outside the workspace, and symlink escapes are refused.

Safe bash

Verification without full shell

Safe mode allows common repo inspection, git, tests, lint, typecheck, and build commands. Use full bash only for trusted local repos.

No surprise shell

Disable or target bash

Use codexpro start --no-bash, or keep bash enabled with --bash-session main --require-bash-session. Session labels target this local CodexPro server, not a Codex app chat.

Codex sessions

Opt-in local history browser

--codex-sessions metadata lists local Codex session ids, titles, cwd paths, and resume commands. read mode adds bounded transcript reads; neither mode attaches to a live Codex chat.

Visual widgets

Compact cards for key results

Opt-in v10 cards render workspace, analysis, changes, Git, handoff, and terminal verification. Reads and searches stay in normal chat output; terminal output and raw diffs remain folded or bounded.

Stable URL rule

One URL needs one reserved hostname

Cloudflare quick tunnels change on restart. Use an ngrok free dev domain, Cloudflare named tunnel, or Tailscale Funnel when you want one ChatGPT app URL.

Local web admin

Edit next-run profile defaults

The token-protected local page can save tunnel, hostname, port, mode, bash, Codex sessions, write/tool mode, widget origin, and tunnel config paths for the next codexpro start. Raw tunnel tokens, account switching, and background services stay out of the browser.

Local executor

Execution stays on your machine

execute-handoff is a terminal command, not a remote MCP tool. Use --dry-run before running unfamiliar agents or custom commands.

Star the GitHub repo npm package Stable URL guide FAQ Security notes

FAQ

The questions users will ask before installing.

Short answers for account requirements, setup, URLs, safety, and what ChatGPT can actually access.

Which ChatGPT account should I use?

Use a ChatGPT web surface with custom MCP access. OpenAI currently documents full write/modify MCP for Business and Enterprise/Edu, with read/fetch MCP access for Pro. Availability can change, and a specific model surface may still be unable to call connectors; use Pro context fallback for those sessions.

Does CodexPro bypass rate limits?

No. It does not bypass, avoid, increase, pool, resell, or modify ChatGPT, Codex, OpenAI, or third-party model limits. Every request still runs through your own ChatGPT session and whatever limits that account has.

Why install globally?

Global install gives users one command: codexpro setup. It avoids long npx commands and makes daily startup simply codexpro start.

What URL should I use?

Use Cloudflare quick tunnel for demos. Use an ngrok free dev domain, Cloudflare named tunnel, or Tailscale Funnel when you want one ChatGPT app URL that survives restarts.

Can ChatGPT see my Codex context?

It can read explicit context files such as AGENTS.md, .ai-bridge, git status/diff, and selected source files. It cannot read hidden Codex runtime memory.

Should CSP stay enabled?

Yes. In Settings -> Security and login, turn on Developer mode and keep Enforce CSP in developer mode enabled. Create and manage the connection under Settings -> Plugins.

Start and stop

Keep the terminal running while ChatGPT uses the connector.

CodexPro owns the local MCP server and the tunnel process. Stop it when the session is over.

Start

Run codexpro start in the target repo. The Server URL is copied automatically.

Open

Press Enter in the terminal to open ChatGPT connector settings.

End

Press q or Ctrl+C. Quick tunnel URLs stop working. Stable hostnames stay reserved.

Safety boundary

This is a local developer bridge, not an OS sandbox.

Public tunnels are token-protected by default.
.env, private keys, .git, node_modules, and symlink escapes are blocked.
Safe bash allows common inspection and test commands, not arbitrary shell control.
--no-bash disables all ChatGPT-triggered shell commands.
--bash-session with --require-bash-session requires explicit session targeting before bash runs.
Use handoff mode when you want ChatGPT to plan and Codex to edit.