CodexPro

Local coding tools for ChatGPT, scoped to one repo.

Install

Requirements:

• Node.js 20+
• A ChatGPT account with Apps / Developer Mode access
• One HTTPS route to your local machine when connecting ChatGPT from the web

Install the CLI:

npm install -g codexpro

Run setup inside the repo you want ChatGPT to work on:

cd /path/to/your/repo
codexpro setup

CodexPro prints and copies the Server URL. In ChatGPT, open:

Settings -> Apps -> Advanced settings -> Create app

Paste the Server URL and choose Authentication: No Authentication / None. CodexPro uses its own URL token.

Daily use from the same repo:

codexpro start

What It Does

CodexPro starts a local MCP server for the current workspace. ChatGPT can then:

• read files and inspect the repo
• search code
• make scoped edits with write, edit, or guarded apply_patch
• run safe verification commands through bash
• review changed files with show_changes
• write handoff plans under .ai-bridge
• export a selected context bundle for model surfaces that cannot call tools

CodexPro is not a hosted service, model proxy, quota bypass, account pool, or OS sandbox. It connects your own ChatGPT session to your own local repo through the official Developer Mode / MCP app path.

Normal Commands

codexpro setup
codexpro start
codexpro start --root /path/to/repo
codexpro doctor
codexpro settings

Useful modes:

codexpro start --no-bash
codexpro start --tool-mode minimal
codexpro start --tool-mode full
codexpro start --mode handoff
codexpro start --mode pro

Tool cards are opt in:

CODEXPRO_TOOL_CARDS=1 codexpro start

Public URL Options

ChatGPT web needs a public HTTPS Server URL. CodexPro supports:

• Fast demo URL: codexpro start --tunnel cloudflare
• Stable ngrok domain: codexpro ngrok --hostname your-domain.ngrok-free.dev
• Stable Cloudflare route: codexpro stable --hostname codexpro.example.com --tunnel-name codexpro
• Tailscale Funnel: codexpro tailscale --hostname your-device.your-tailnet.ts.net
• Local only: codexpro start --tunnel none

Cloudflare quick tunnels honor HTTPS_PROXY, ALL_PROXY, or HTTP_PROXY when those env vars are set.

Stable modes should use a stable CodexPro token:

codexpro tailscale \
  --hostname your-device.your-tailnet.ts.net \
  --token keep-this-token-stable

Tailscale Funnel must already be allowed for your tailnet. It requires MagicDNS, HTTPS certificates, and Funnel policy support. CodexPro runs:

tailscale funnel http://127.0.0.1:8787

Then ChatGPT uses:

https://your-device.your-tailnet.ts.net/mcp?codexpro_token=keep-this-token-stable

Safety Defaults

• Public tunnel mode requires a CodexPro HTTP token.
• Generic writes are hidden unless CODEXPRO_WRITE_MODE=workspace.
• Safe bash blocks broad shell patterns and secret/build/cache paths.
• apply_patch is workspace-scoped and rejects blocked paths, symlink patches, and secret-looking patch content.
• show_changes keeps a review checkpoint so repeated unchanged reviews collapse.
• Tool-card metadata is off unless CODEXPRO_TOOL_CARDS=1.

Read SECURITY.md before exposing CodexPro through any tunnel.

RAM And ChatGPT Memory

CodexPro can reduce what it sends to ChatGPT. Current local fixes:

• binary-file checks scan with a reusable 64 KiB buffer instead of allocating the whole file
• ChatGPT tool-card structured payloads are compacted only for card output, not for normal tool data
• bash chat transcripts stay compact by default

That helps avoid oversized MCP/card payloads. It does not force Chrome, ChatGPT, or an old browser iframe to release memory that the client already holds. If the browser tab has already grown, reload the ChatGPT page or restart the browser.

Repo Context

CodexPro uses explicit files, not hidden chat memory:

AGENTS.md
.ai-bridge/current-plan.md
.ai-bridge/agent-status.md
.ai-bridge/decisions.md
.ai-bridge/open-questions.md
.ai-bridge/execution-log.jsonl

For non-tool model surfaces:

codexpro start --mode pro

Or from a local checkout:

codexpro pro-bundle --root /path/to/repo --copy
codexpro pro-apply --root /path/to/repo --file plan.md

Handoff

ChatGPT can write a plan without executing a local agent:

codexpro start --mode handoff

Then you run execution locally:

codexpro execute-handoff --agent codex --yes
codexpro watch-handoff --agent codex --yes

handoff_to_agent is planning-only over MCP. CodexPro does not expose arbitrary local agent execution as a remote ChatGPT tool.

Troubleshooting

Run:

codexpro doctor

Common fixes:

• Quick tunnel URL changed: rerun codexpro start and update the ChatGPT app Server URL.
• Stable URL does not respond: check the tunnel provider first, then the CodexPro token.
• ChatGPT cannot call tools in one model/chat: switch to a ChatGPT surface that supports Developer Mode app actions.
• Local port is busy: start another repo with --port 8788.
• Tool list looks stale: create a new ChatGPT app entry or change the connector URL token.

Development

npm install
npm run build
npm run smoke
npm run stress

Useful release checks:

npm run build
npm run smoke
CODEXPRO_TOOL_CARDS=1 npm run smoke
npm audit --audit-level=high
npm pack --dry-run
git diff --check

Docs

• Website
• FAQ
• Security
• Stable URL guide
• Changelog