Let ChatGPT web see your Codex-style repo context and act like a local coding agent.

Website · 中文 README · 中文网站 · Star on GitHub · npm · Stable URL guide · FAQ · Security

CodexPro turns ChatGPT Developer Mode into a local coding agent for the folder on your machine. Install it globally, run setup in a repo, paste the copied Server URL into ChatGPT Create App, and ChatGPT can inspect files, edit code, run safe verification commands, and load the same explicit context you normally give Codex through AGENTS.md, .ai-bridge, git status, git diff, and source files.

CodexPro is not a rate-limit bypass. It uses ChatGPT's official Developer Mode and MCP app path to connect your own ChatGPT session to your own local repo. ChatGPT and Codex remain separate product surfaces, each subject to its own plan limits, safety rules, and availability.

If one workflow is unavailable and another product surface you already have access to is still available, CodexPro lets you keep working against the same local repo without modifying or evading either product's limits.

npm install -g codexpro
codexpro setup

ChatGPT web can see Codex-style context:
  AGENTS.md
  .ai-bridge plans and status
  git status and diff
  selected source files

ChatGPT web can act on your repo:
  read files
  write files
  exact-edit files
  search code
  run safe verification commands

Codex stays useful:
  execute plans locally
  handle deeper terminal-heavy work
  review or continue a handoff

What it gives you:

Normal coding mode  ChatGPT reads, writes, edits, searches, and verifies directly.
Handoff mode        ChatGPT writes .ai-bridge/current-plan.md for a local implementation agent.
Pro planning mode   Export a durable context bundle for sessions that cannot call MCP tools.
Stable URLs         Use an ngrok free dev domain or Cloudflare named tunnel so the ChatGPT app URL stays fixed.

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 ChatGPT model surfaces may not be able to 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.

CodexPro is not an OS sandbox. It is a local developer bridge with safety defaults. Read SECURITY.md before exposing it through a tunnel.

Node.js 20+
ChatGPT Plus or Pro account with Apps / Developer Mode access
Developer mode enabled from Settings -> Apps -> Advanced settings
Enforce CSP in developer mode kept enabled
One public tunnel option: Cloudflare quick tunnel, ngrok free dev domain, or Cloudflare named tunnel

Current testing shows free / Go ChatGPT accounts do not expose the app flow needed for CodexPro. Use Plus or Pro for the best experience.

Account tier and model tool support are separate things. Plus/Pro can expose Apps / Developer Mode, but a specific model surface may still be unable to call the connector. Use Pro context fallback for those sessions.

CodexPro is a public open-source MCP bridge with conservative defaults: workspace-only writes, safe bash by default, blocked secret paths, token-protected public URLs, and compact visual cards for every tool result.

CodexPro does not bypass, avoid, increase, pool, resell, or modify ChatGPT, Codex, OpenAI, or third-party model limits. It does not provide models or account access. It only exposes local repo tools to the ChatGPT session the user already controls through official MCP and Developer Mode.

ChatGPT can do MCP-backed agentic coding in your local repo, while Codex remains available for terminal execution, review, or handoff workflows. Model, tool, and quota behavior are controlled by the product and account you connect CodexPro to.

CodexPro is designed for the official ChatGPT Developer Mode / MCP app path:

• It exposes local workspace files, git state, safe verification commands, and .ai-bridge handoff files selected by the user.
• It does not ask for raw ChatGPT transcripts or broad conversation history. Context exports use explicit workspace files and bounded previews.
• It does not scrape or act as pass-through middleware for third-party services unless the user connects an authorized local integration that follows that service's terms.
• It does not automate ChatGPT, Codex, or terminal approval flows to bypass product security, rate limits, quota limits, account access, or review prompts.
• Remote MCP tools do not execute Codex/OpenCode/Pi/local agents. Agent execution is a separate user-started CLI/watch process on the user's machine.

Relevant OpenAI references: ChatGPT Developer Mode, MCP servers for ChatGPT Apps, and Apps SDK submission guidelines.

CodexPro defaults to CODEXPRO_TOOL_MODE=standard, which keeps ChatGPT's tool picker focused on the normal coding loop plus handoff/export workflows. Use --tool-mode minimal for the tightest demo surface, or --tool-mode full when you want every compatibility and debugging tool exposed.

The smaller default tool list is deliberate. ChatGPT behaves better when routine work goes through a few high-signal tools instead of a large action catalog. Installed user/plugin skills are still discovered during workspace open; they are surfaced as context in the workspace card and can be loaded on demand with load_skill, not exposed as dozens of separate ChatGPT actions.

Standard mode exposes:

• server_config — show safety modes, limits, blocked globs, and allowed roots.
• codexpro_self_test — run one local-only diagnostic for modes, expected tools, safe bash policy, .ai-bridge write/edit, and selected-only Pro context.
• open_current_workspace — open the configured default workspace without accepting a path. Fastest/safest first call.
• open_workspace — open a local project directory using root or path and return workspace id, git status, AGENTS.md status, optional skill discovery, and optional file tree.
• tree — inspect files.
• search — search code with ripgrep or a Node fallback.
• load_skill — load bounded SKILL.md instructions for a discovered workspace, user, or plugin skill by name, with optional source/path disambiguation.
• read — read text files with line numbers.
• write — create/overwrite files and return a diff. Controlled by CODEXPRO_WRITE_MODE.
• edit — exact text replacement and return a diff. Controlled by CODEXPRO_WRITE_MODE.
• bash — run allowlisted shell commands in the workspace. Controlled by CODEXPRO_BASH_MODE.
• show_changes — one review-oriented summary with git status, diff stats, and optional diff.
• read_handoff — read .ai-bridge files.
• export_pro_context — write .ai-bridge/pro-context.md for models that cannot call MCP tools directly.
• handoff_to_agent — write .ai-bridge/current-plan.md for Codex, OpenCode, Pi, or a custom local implementation agent without executing local commands.

Minimal mode exposes only:

server_config
codexpro_self_test
open_current_workspace / open_workspace
read / write / edit
bash
show_changes

Full mode adds:

• codexpro_inventory — list discovered skill names and configured MCP server names without exposing MCP command arguments or secrets.
• list_workspaces — show opened workspaces in the current MCP session.
• workspace_snapshot — project status plus .ai-bridge handoff context.
• git_status — inspect git status.
• git_diff — inspect current diff.
• codex_context — load Codex-style context in one call: AGENTS instructions for a target path, .ai-bridge files, and optional git status/diff.
• handoff_to_codex — compatibility wrapper for handoff_to_agent with agent=codex.

Local-only companion command:

• codexpro execute-handoff — run a previously written .ai-bridge/current-plan.md through a local agent, then collect status, logs, and git diff. This is intentionally a CLI command, not a remote MCP tool.
• codexpro watch-handoff — watch .ai-bridge/current-plan.md locally and run a new plan through a configured agent when its content hash changes. This is also CLI-only and is not exposed as a remote MCP tool.

The watcher is the safer way to automate handoff execution from ChatGPT Web. ChatGPT writes the plan through handoff_to_agent; the user-started local watcher notices the new plan and runs Pi, OpenCode, Codex, or a restricted custom command from the terminal:

codexpro start --mode handoff
codexpro watch-handoff --agent opencode --model provider/model --yes

For custom local agents:

codexpro watch-handoff \
  --agent custom \
  --command "node ./agent.js --task-file {{plan_file}}" \
  --yes

Useful watcher flags:

--once                  check one new plan and exit
--dry-run               show the command without executing it
--poll-interval-ms 2000 polling interval
--debounce-ms 500       wait for the plan file to become stable
--state-file <path>     duplicate-run state, default .ai-bridge/watch-handoff-state.json

The watcher writes the same review files as execute-handoff:

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

v0.28.5+ registers a reusable Apps SDK widget resource:

ui://widget/codexpro-tool-card-v9.html

Every CodexPro tool descriptor attaches that resource through _meta.ui.resourceUri and the ChatGPT compatibility key _meta["openai/outputTemplate"]. In ChatGPT Developer Mode this renders compact cards for:

server_config and codexpro_self_test
open_current_workspace / open_workspace project summaries
codexpro_inventory, list_workspaces, workspace_snapshot
tree, search, load_skill, read
write/edit diffs
bash verification commands
git_status, git_diff, show_changes review summaries
read_handoff, codex_context
handoff/pro-context exports

Cards stay compact by default. Git details, discovered skills, file trees, terminal output, context bundles, and raw diffs are folded or bounded so the chat does not fill with project inventory unless you open it.

ChatGPT may still show some raw tool transcript around a card depending on the host UI and model behavior. CodexPro minimizes that by returning structured data, bounded previews, and a v9 card for every tool, but the ChatGPT client controls final transcript rendering.

The visual cards are not unlocked by "normal coding mode" alone; the MCP server has to register an HTML resource with text/html;profile=mcp-app and point tool descriptors at it.

The widget sets both domain and CSP metadata surfaces:

_meta.ui.domain
_meta["openai/widgetDomain"]
_meta.ui.csp
_meta["openai/widgetCSP"]

CODEXPRO_WIDGET_DOMAIN defaults to https://rebel0789.github.io for this package. For app submission, set it to a dedicated HTTPS origin you control, for example https://widgets.yourdomain.com. The CSP lists are intentionally strict because the widget has no external fetches, fonts, scripts, images, or iframes.

After upgrading or changing widget metadata, open the CodexPro app settings in ChatGPT Developer Mode and click Refresh / Refresh actions so ChatGPT reloads the tool descriptors and resource URI.

Recommended install:

npm install -g codexpro

First run from the repo you want ChatGPT to work on:

codexpro setup

Daily start after setup:

codexpro start

No-install fallback:

npx codexpro@latest start --root /absolute/path/to/your/repo

From source:

cd codexpro
npm install
npm run build

From the project folder you want ChatGPT to work on:

codexpro setup

That is the intended low-friction first-run path. It:

- uses the current folder as the workspace root
- asks for the local port, mode, tunnel provider, and stable URL choice
- saves the workspace profile for future codexpro start runs
- starts the local HTTP MCP server
- generates a private CodexPro token
- supports Cloudflare quick tunnel, ngrok free dev domain, Cloudflare stable tunnel, or local-only mode
- installs cloudflared into ~/.codexpro/bin if Cloudflare is selected and it is missing
- waits for the public HTTPS tunnel URL
- copies the exact ChatGPT Server URL to your clipboard
- starts in normal coding mode with workspace edits enabled
- shows a compact terminal control panel
- lets you press Enter to open ChatGPT in your browser
- lets you press `o` to open a local setup/status page

After setup, daily use from the same repo is:

codexpro start

Before you paste the CodexPro URL, turn on Developer Mode in ChatGPT:

ChatGPT Settings
-> Apps
-> Advanced settings
-> Developer mode: on
-> Enforce CSP in developer mode: on
-> Create app

This is a one-time ChatGPT setting. Keep CSP enabled; CodexPro widgets are built for that path.

In Create App, use:

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

The copied Server URL already includes the private CodexPro token. Do not paste the token separately unless your ChatGPT UI supports custom headers.

Keep the terminal running while ChatGPT uses the connector. When you stop it, the quick-tunnel URL stops working.

If cloudflared is missing, CodexPro downloads the official Cloudflare binary into ~/.codexpro/bin on supported macOS, Windows, and Linux machines. No sudo, admin shell, Homebrew, apt, or winget step is required. To skip that behavior:

codexpro start --no-install-cloudflared

OS behavior:

macOS    auto-installs ~/.codexpro/bin/cloudflared, copies with pbcopy, opens ChatGPT with open
Windows  auto-installs ~/.codexpro/bin/cloudflared.exe, copies with clip, opens ChatGPT with start
Linux    auto-installs ~/.codexpro/bin/cloudflared, opens ChatGPT with xdg-open when available

Linux clipboard copy requires one of wl-copy, xclip, or xsel. If none is installed, CodexPro prints the URL clearly so it can be copied manually.

First-run tunnel choice:

cloudflare  Cloudflare quick tunnel. Easiest demo path, new URL each restart.
ngrok       ngrok free dev domain. Recommended stable URL for most users.
stable      Cloudflare named tunnel. Stable URL with your own Cloudflare domain.
local       No public tunnel. Only for local MCP clients.

If you use quick mode, the Server URL changes every time the tunnel restarts. That means you must update the ChatGPT app Server URL each time. Use quick mode for demos, not daily work.

Recommended daily path: create a free ngrok account, use the dev domain assigned to your account, save it in codexpro setup, and keep the same ChatGPT app Server URL across restarts.

CodexPro saves the selected tunnel provider, hostname, port, mode, and auth token for that workspace. Future launches from the same folder reuse it:

codexpro start

If you start CodexPro in a new folder and already have saved setups, it shows a numbered list. Press Enter to reuse the first saved setup, type another number, or type new to choose a fresh tunnel.

If you are running this repository from source instead of npm:

npm run connect:chatgpt -- --root /absolute/path/to/your/repo

Guided onboarding:

codexpro setup

setup asks for the workspace folder, local port, mode, and public URL strategy, then prints the exact codexpro start ... command and can launch it immediately. It saves the selected tunnel provider, hostname, local port, mode, and generated CodexPro auth token for that workspace under ~/.codexpro/profiles/, so future codexpro start runs from the same folder can reuse the stable URL setup automatically.

From a source checkout:

npm run connect:setup

Preflight diagnostics:

codexpro doctor

doctor does not start the MCP server or open a tunnel. It checks the local package build, Node version, workspace profile, port availability, tunnel prerequisites, clipboard support, and browser-open support. Run it before filing setup bugs or before recording a demo.

Use --no-copy-url if you do not want CodexPro to copy the connector URL. Add --open-chatgpt if you want the browser to open automatically instead of pressing Enter.

Local setup/status page:

press o in the CodexPro terminal control panel

The page shows the active workspace, local MCP endpoint, safety modes, allowed roots, and the exact ChatGPT setup steps. It is served by the local CodexPro process and stays token-protected when auth is enabled.

Saved workspace profile behavior:

codexpro setup
  choose quick, stable, ngrok, or local
  enter the Cloudflare/ngrok hostname when needed
  accept the generated CodexPro auth token
  save the profile

future codexpro start
  loads the saved profile for the current folder
  reuses the saved tunnel provider, hostname, port, mode, and token

If setup finds a saved ngrok or Cloudflare stable profile, CodexPro prints the saved hostname and the short daily command:

codexpro start

That is enough from the same workspace folder. Use codexpro setup again only when you want to change the port, mode, tunnel provider, hostname, or CodexPro auth token.

Useful profile flags:

codexpro start --no-profile      # ignore saved profile for this run
codexpro setup --no-save-config  # run setup without saving
codexpro setup --save-config     # explicitly save setup choices

Workspace settings:

codexpro settings
codexpro settings show
codexpro settings list
codexpro settings set --tunnel ngrok --hostname your-domain.ngrok-free.dev
codexpro settings use --from-root /path/to/another/repo
codexpro settings set --tunnel cloudflare
codexpro settings delete --yes

Use codexpro settings when you want to make ngrok the default, switch back to Cloudflare quick tunnels, reuse a saved setup from another repo, or delete the saved workspace preference. The saved token is redacted when settings are shown.

Terminal controls:

Enter  open ChatGPT connector settings in your browser
c      copy Server URL again
o      open local setup/status page
h      show controls
q      stop CodexPro

Advanced controls such as u for printing the full URL, p for Create App fields, and m for mode help are still available through h.

Startup modes:

codexpro start                 # normal coding mode: read/write/edit/search/bash
codexpro setup                 # guided onboarding for new users
codexpro start --mode handoff  # planning-only .ai-bridge handoff
codexpro start --mode pro      # export context for models without MCP tools
codexpro stable --hostname codexpro.example.com --tunnel-name codexpro
codexpro ngrok --hostname your-domain.ngrok-free.dev

This is the lightweight launcher so you do not have to manually start the MCP server, generate a token, start Cloudflare, and copy/paste multiple fields by hand.

If you are running from source, use npm run connect -- --root /absolute/path/to/your/repo.

By default this:

- starts the local HTTP MCP server
- generates a bearer token
- starts a Cloudflare quick tunnel
- installs `cloudflared` into `~/.codexpro/bin` on supported OSes when it is missing
- copies the exact /mcp endpoint with a codexpro_token query parameter
- copies the public HTTPS Server URL to your clipboard when clipboard support is available
- tells ChatGPT Developer Mode to use No Authentication / None
- uses CODEXPRO_WRITE_MODE=workspace so ChatGPT can edit files directly

In ChatGPT Developer Mode, use the printed fields:

Name: CodexPro
Connection: Server URL
Server URL: https://<cloudflare-host>/mcp?codexpro_token=<token>
Authentication: No Authentication / None

Planning-only handoff mode:

codexpro start \
  --root /absolute/path/to/your/repo \
  --bash safe \
  --mode handoff \
  --tunnel cloudflare

In handoff mode, ChatGPT can create a plan for a local implementation agent without getting direct source-write access. Use handoff_to_agent from ChatGPT with agent=opencode, agent=pi, agent=codex, or a custom agent id. CodexPro writes:

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

Then run the implementation locally with codexpro execute-handoff:

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

Dry-run first if you want to inspect the exact command:

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

Pi adapter:

codexpro execute-handoff --agent pi --model provider/cheap-model

Custom adapter:

codexpro execute-handoff \
  --agent custom \
  --command "my-agent --model {{model}} --task-file {{plan_file}}" \
  --model provider/cheap-model

Template placeholders:

{{model}}      model passed with --model
{{plan_file}}  absolute path to .ai-bridge/current-plan.md
{{plan_text}}  full plan text as one argument
{{root}}       workspace root

By default, execute-handoff asks for local confirmation before running. Use --yes only in trusted scripts. After execution, CodexPro writes:

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

Then let ChatGPT review those files through read_handoff or codex_context.

Manual fallback:

opencode run --model provider/cheap-model "$(cat .ai-bridge/current-plan.md)"
git diff --no-ext-diff -- > .ai-bridge/implementation-diff.patch

For debugging whether ChatGPT is actually reaching the local server, add:

--log-requests

To open ChatGPT settings automatically:

codexpro start --root /absolute/path/to/your/repo --open-chatgpt

To prevent automatic cloudflared installation:

codexpro start --root /absolute/path/to/your/repo --no-install-cloudflared

Request logs print method, path, status, and duration. CodexPro also logs tool name, success/error state, and duration as [CodexProTool] ... lines. Query strings, file contents, and prompts are not logged, so the codexpro_token and source content are not printed.

For faster ChatGPT runs, keep the first call narrow:

Call open_current_workspace with include_tree=false unless you need the tree immediately.
Use tree with max_depth=2 and max_entries=100 when you need file structure.
Use load_skill only for the specific discovered skill needed for the task.
Use --tool-mode full and call codexpro_inventory only when you want ChatGPT to see full global skill and MCP server inventory.
Do not call open_workspace after open_current_workspace unless you are switching to a different root.
Use tree/search/read for inspection, one targeted search plus show_changes for review, and bash only for focused build/test/lint verification.

open_current_workspace and open_workspace discover workspace, user, and plugin skills by default. Use include_global_skills=false when you only want repo-local instructions, or include_skills=false when you want the fastest possible open call. load_skill only accepts a discovered skill name plus optional source and exact displayed path, then reads that skill's SKILL.md with a bounded byte limit; it does not accept arbitrary file paths. If multiple discovered skills still match, CodexPro returns an ambiguity error instead of guessing. workspace_snapshot stays narrower by default for speed. In --tool-mode full, use codexpro_inventory for global/user/plugin skills and MCP server names. codexpro_inventory reports names/descriptions and sanitized paths only; it does not expose MCP command arguments or environment values.

CodexPro is not reading Codex's private runtime memory. It gives ChatGPT explicit workspace context through tools:

open_current_workspace  root, safety mode, AGENTS.md status, git status
codex_context           AGENTS chain, .ai-bridge handoff files, optional git status/diff
read_handoff            .ai-bridge files only
workspace_snapshot      larger project snapshot plus .ai-bridge context

codex_context is the closest match to "load what Codex should know." It reads AGENTS-style instruction files from the workspace root down to a target path:

AGENTS.override.md
AGENTS.md
agents.md
.agents.md

Then it adds:

.ai-bridge/current-plan.md
.ai-bridge/agent-status.md
.ai-bridge/implementation-diff.patch
.ai-bridge/codex-status.md
.ai-bridge/decisions.md
.ai-bridge/open-questions.md
.ai-bridge/execution-log.jsonl
git status
optional git diff

Use it before planning or review:

Call open_current_workspace with include_tree=false.
Call codex_context with target_path="src/App.tsx" and include_diff=false.
Then inspect only the files needed for the task.

This keeps ChatGPT closer to Codex's instruction model without hidden state, browser memory, or repeated broad file scans.

Demo/Codex-like mode, where ChatGPT can use write and edit on source files:

codexpro start \
  --root /absolute/path/to/your/repo \
  --bash safe \
  --write workspace \
  --tunnel cloudflare

Local-only mode, for local MCP clients that can reach 127.0.0.1 directly:

codexpro start --root /absolute/path/to/your/repo --tunnel none

The local endpoint is usually:

http://127.0.0.1:8787/mcp

Some ChatGPT models or product surfaces may not be able to call Developer Mode apps, connectors, or MCP tools directly. This can include stronger planning-model surfaces even when the same ChatGPT account can create and use the CodexPro app from other chats. When that happens, use a durable context bundle instead of fighting the tool boundary.

Generate a bundle:

codexpro pro-bundle --root /absolute/path/to/your/repo --copy

This writes:

.ai-bridge/pro-context.md

The bundle includes the file tree, git status, current diff, recent commits, selected important config files, changed files, and existing .ai-bridge handoff context. --copy also copies the bundle to the macOS clipboard when pbcopy is available.

For an exact selected-file bundle, disable the automatic config/docs and changed-file inclusions:

codexpro pro-bundle \
  --root /absolute/path/to/your/repo \
  --path README.md \
  --path package.json \
  --no-important-files \
  --no-changed-files \
  --no-diff \
  --no-ai-bridge \
  --copy

Useful options:

codexpro pro-bundle \
  --root /absolute/path/to/your/repo \
  --path src/App.tsx \
  --glob "src/**/*.ts" \
  --max-files 32 \
  --max-total-bytes 300000 \
  --copy

Paste the bundle into any model that cannot call MCP tools directly and ask it to produce a narrow implementation plan. Save the returned plan to a file, then apply it:

codexpro pro-apply --root /absolute/path/to/your/repo --file plan.md

Or pipe from stdin:

cat plan.md | codexpro pro-apply --root /absolute/path/to/your/repo --stdin

That writes:

.ai-bridge/current-plan.md

Then run Codex, OpenCode, Pi, or another local implementation agent against .ai-bridge/current-plan.md.

The launcher uses Cloudflare quick tunnels when you pass or default to:

--tunnel cloudflare

Quick tunnels are good for demos, but the trycloudflare.com URL changes whenever the tunnel restarts. Do not use quick tunnels if you want a URL users can keep in ChatGPT.

CodexPro needs cloudflared for public HTTPS tunnels. The launcher first uses cloudflared from PATH, then ~/.codexpro/bin, then downloads the official Cloudflare release into ~/.codexpro/bin when it is missing.

codexpro start

To force a fresh local install:

codexpro install-cloudflared

You can also force a refresh during normal startup with codexpro start --install-cloudflared.

To manage Cloudflare Tunnel yourself, opt out and pass a path:

codexpro start --no-install-cloudflared --cloudflared /path/to/cloudflared

Automatic install currently supports:

macOS:   arm64, x64
Windows: x64, 32-bit
Linux:   x64, 32-bit, arm64, arm

Other platforms can still work by installing cloudflared manually and passing --cloudflared <path>.

For daily use, use ngrok's free dev domain, a Cloudflare named tunnel, or a Cloudflare dashboard-managed tunnel token. This gives you one stable ChatGPT connector URL, for example:

https://codexpro.example.com/mcp?codexpro_token=<your-codexpro-token>

There is one unavoidable boundary: a permanent public URL needs a tunnel provider such as Cloudflare or ngrok and a hostname reserved with that provider. CodexPro can run the tunnel after that setup, but a quick tunnel cannot be made permanent.

If you use quick mode, you will need to edit the ChatGPT app every restart because the copied Server URL changes.

One-time Cloudflare CLI setup with your own domain:

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

Then daily startup is one command:

codexpro stable \
  --root /absolute/path/to/your/repo \
  --hostname codexpro.example.com \
  --tunnel-name codexpro \
  --token keep-this-codexpro-token-stable \
  --bash safe

Put this stable Server URL into ChatGPT Developer Mode once:

https://codexpro.example.com/mcp?codexpro_token=keep-this-codexpro-token-stable

After that, users only restart the local command. They do not need to edit the ChatGPT connector unless they change the hostname or token.

If you create a remotely managed tunnel in the Cloudflare dashboard instead, save its tunnel token to a local file and run:

codexpro start \
  --root /absolute/path/to/your/repo \
  --tunnel cloudflare-named \
  --hostname codexpro.example.com \
  --cloudflare-token-file ~/.codexpro/cloudflare-tunnel-token \
  --token keep-this-codexpro-token-stable \
  --bash safe

Token naming matters:

--cloudflare-token-file  Cloudflare's tunnel connector token.
--token                  CodexPro's MCP auth token used in the ChatGPT URL.

If you already installed ngrok and authenticated it:

ngrok config add-authtoken <your-ngrok-token>

Create a free ngrok account, find your assigned dev domain in the ngrok dashboard under Universal Gateway -> Domains, then start CodexPro with:

codexpro ngrok \
  --root /absolute/path/to/your/repo \
  --hostname your-domain.ngrok-free.dev \
  --token keep-this-codexpro-token-stable

Equivalent explicit form:

codexpro start \
  --root /absolute/path/to/your/repo \
  --tunnel ngrok \
  --hostname your-domain.ngrok-free.dev \
  --token keep-this-codexpro-token-stable

CodexPro runs ngrok in the background with:

ngrok http http://127.0.0.1:8787 --url https://your-domain.ngrok-free.dev

Put this Server URL into ChatGPT Developer Mode once:

https://your-domain.ngrok-free.dev/mcp?codexpro_token=keep-this-codexpro-token-stable

After that, keep using the same hostname and token. You do not need to recreate the ChatGPT app unless you change either one.

After saving this in codexpro setup, daily startup from that repo is just:

codexpro start

CodexPro will reuse the saved ngrok hostname and saved CodexPro token.

You can run CodexPro for multiple repositories at once, but each running workspace needs its own local port:

# repo A
codexpro setup  # choose port 8787

# repo B
codexpro setup  # choose port 8788

If both repositories use quick tunnels, different local ports are enough because each run gets a different temporary public URL.

If both repositories use stable ngrok or Cloudflare URLs, each repository also needs its own public hostname:

repo A  port 8787  codexpro-a.ngrok-free.dev
repo B  port 8788  codexpro-b.ngrok-free.dev

Do not point two running repositories at the same local port or the same ngrok/Cloudflare hostname. The second process will fail because the port or public hostname is already owned by the first process.

For Namecheap and custom-domain setup, read DOMAIN_SETUP.md. The key point is that a stable domain can solve your own repeated ChatGPT connector setup now, but a single shared URL for every future user needs a hosted relay or per-user tunnel routing.

If ChatGPT does not let you edit an existing app's Server URL, do not use quick tunnels for daily work. Use codexpro stable with a Cloudflare named tunnel and put the stable URL into ChatGPT once:

codexpro stable-help

For a less manual daily workflow, create a shell alias:

alias codexpro-local='codexpro start --root /path/to/your/repo --bash safe'

Then run:

codexpro-local

CODEXPRO_ROOT=/absolute/path/to/your/repo \
CODEXPRO_ALLOWED_ROOTS=/absolute/path/to/your \
CODEXPRO_BASH_MODE=safe \
CODEXPRO_WRITE_MODE=workspace \
CODEXPRO_HTTP_TOKEN='replace-with-long-random-token' \
npm run start:http

Health check:

curl 'http://127.0.0.1:8787/healthz?codexpro_token=replace-with-long-random-token'

MCP endpoint:

http://127.0.0.1:8787/mcp?codexpro_token=replace-with-long-random-token

For clients that launch local MCP commands:

node /absolute/path/to/codexpro/dist/stdio.js \
  --root /absolute/path/to/your/repo \
  --allow-root /absolute/path/to/your \
  --bash safe \
  --write workspace

Example MCP config:

{
  "mcpServers": {
    "CodexPro": {
      "command": "node",
      "args": [
        "/absolute/path/to/codexpro/dist/stdio.js",
        "--root",
        "/absolute/path/to/your/repo",
        "--allow-root",
        "/absolute/path/to/your",
        "--bash",
        "safe",
        "--write",
        "handoff"
      ]
    }
  }
}

CODEXPRO_WRITE_MODE=workspace is the default normal coding mode. Use handoff when you want planning-only behavior and do not want ChatGPT to edit source files directly.

off        write/edit tools are disabled; handoff_to_agent and handoff_to_codex still write .ai-bridge/current-plan.md
handoff    write/edit can only write inside .ai-bridge/
workspace  write/edit can write workspace files, except blocked paths

The launcher defaults to workspace in normal coding mode and handoff in handoff/pro planning modes.

CODEXPRO_TOOL_MODE=standard is the default. It exposes the normal coding loop plus show_changes, Pro context export, and generic agent handoff.

minimal   smallest surface for demos and simple coding: open/read/write/edit/bash/show_changes
standard  default surface for normal coding plus handoff/export
full      all tools, including inventory, workspace snapshots, raw git tools, codex_context, and compatibility wrappers

Launcher examples:

codexpro start --tool-mode minimal
codexpro start --tool-mode full

CODEXPRO_BASH_MODE=safe is the default. It allows common inspection and test commands, including:

pwd, ls, find
git status, git diff, git log, git show, git branch, git rev-parse, git ls-files
npm/pnpm/yarn/bun test/build/lint/typecheck/check, including suffix scripts such as npm run build:clients
pytest, go test, cargo test, cargo check, cargo clippy, tsc, eslint, biome check

Use the MCP read and search tools for file contents. The safe shell blocks obvious destructive commands, redirects, pipes, curl, wget, ssh, docker, git push/reset/clean/checkout/switch/restore, find -exec, find -delete, and file-content shell readers such as cat, grep, rg, head, and tail.

CODEXPRO_BASH_MODE=off disables bash completely.

CODEXPRO_BASH_MODE=full allows arbitrary shell commands. Use this only for trusted local repos; MCP itself is not an OS sandbox.

By default the bash environment is sanitized. To inherit your full local environment:

CODEXPRO_INHERIT_ENV=1 CODEXPRO_BASH_MODE=full npm run start:http

Blocked by default:

.env, .env.*
.git internals
node_modules
private key patterns such as *.pem, *.key, id_rsa, id_ed25519
build/cache outputs such as dist, build, .next, coverage, .cache
paths outside the opened workspace root
workspace roots outside CODEXPRO_ALLOWED_ROOTS
symlinks that resolve outside the workspace root
symlinks that resolve to blocked paths

Extra blocked globs can be added with a comma-separated env var:

CODEXPRO_BLOCKED_GLOBS='**/secrets/**,**/*.sqlite,**/*.db' codexpro start --root /repo

Use CodexPro.

Call server_config first, then codexpro_self_test.
If self-test fails, stop and report the failed checks.
Then call open_current_workspace with include_tree=false.

Act as a coding agent. Inspect the relevant files, make the requested source edits with write/edit, then verify with search/read/bash and show_changes when useful. Use bash only for focused verification commands such as build, test, lint, or typecheck.

Keep changes scoped to the request. Do not use handoff_to_agent unless I explicitly ask for planning-only handoff.

After upgrading CodexPro or changing the Server URL, refresh the app actions in ChatGPT before judging the card UI. Existing cards do not retroactively re-render after a widget URI change.

Read .ai-bridge/current-plan.md and execute it in small, reviewable steps.

After each meaningful change, update .ai-bridge/agent-status.md with:

- what changed
- files touched
- tests, lint, or typecheck commands run
- results
- blockers or questions
- what ChatGPT or another reviewer should review next

Keep .ai-bridge/decisions.md aligned with implementation choices. Save the final review diff to .ai-bridge/implementation-diff.patch when practical. Do not overwrite .ai-bridge/current-plan.md unless asked.

Default codexpro start is already workspace-write normal coding mode.

Use CodexPro.

Open ~/tmp/codexpro-example as the active workspace. Demonstrate each tool call while you work:

1. server_config
2. open_workspace
3. tree
4. read the relevant HTML/table file
5. write README.md explaining the demo
6. edit the repeated table row so each tool appears once
7. run one final targeted search and show_changes to verify

Narrate which CodexPro tool you are using before each call.

1. Start CodexPro MCP against your repo with codexpro start --root /repo.
2. Connect the printed endpoint in ChatGPT Developer Mode.
3. Ask ChatGPT to inspect the repo, edit files directly, and verify the work with search/read/bash/git tools.
4. If your chosen ChatGPT model cannot call tools, run codexpro pro-bundle --root /repo --copy, paste the bundle into that model, then apply its plan with codexpro pro-apply --root /repo --file plan.md.
5. Use codexpro start --mode handoff only when you want ChatGPT to write .ai-bridge/current-plan.md for Codex, OpenCode, Pi, or another local implementation agent instead of editing source files itself.

npm install
npm run build
npm run smoke
npm run doctor -- --tunnel none

Before publishing or opening a pull request, check:

npm pack --dry-run

The package should not include local runtime reports, .ai-bridge, .env files, tunnel tokens, or generated tarballs.

For public release gates, see PUBLIC_LAUNCH_CHECKLIST.md. For contribution and security boundaries, see CONTRIBUTING.md and SECURITY.md.

MIT