Codexpro

CodexPro

Use ChatGPT like your local coding agent for one token-protected workspace.

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

Installation

CodexPro requires Node.js 20+ and a ChatGPT account with Apps / Developer Mode access. OpenAI currently lists Developer Mode for Pro, Plus, Business, Enterprise, and Education accounts on web.

Install the CLI:

npm install -g codexpro

Then run setup inside the repo you want ChatGPT to work on:

cd /path/to/your/repo
codexpro setup

CodexPro copies the ChatGPT Server URL for you. In ChatGPT, open Settings -> Apps -> Advanced settings -> Create app, paste that URL, and choose Authentication: No Authentication / None.

After setup, daily use from the same repo is just:

codexpro start

CodexPro turns ChatGPT Developer Mode into a local coding agent for that folder. It gives ChatGPT bounded MCP tools for file reads, code search, exact edits, git inspection, safe verification commands, and explicit repo-backed context from AGENTS.md, .ai-bridge, git state, and selected source files.

CodexPro is not a rate-limit bypass, model proxy, hosted SaaS, or OS sandbox. 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.

Quick Choices

| Need | Use | | --- | --- | | Fast first setup | npm install -g codexpro, then codexpro setup | | Daily start | codexpro start from the same repo | | Stable ChatGPT URL | ngrok free dev domain or Cloudflare named tunnel | | Default tool surface | CODEXPRO_TOOL_MODE=standard | | Full diagnostics | codexpro start --tool-mode full | | No ChatGPT-triggered shell | codexpro start --no-bash | | Compact chat transcript | default compact bash output; use --bash-transcript full only when needed | | Local Codex history lookup | opt in with --codex-sessions metadata or read |

The GitHub main README can describe changes before they reach npm. Check the npm badge/version when installing with npm install -g codexpro; use the source-checkout path below for unreleased main behavior.

Product Boundary

| CodexPro is | CodexPro is not | | --- | --- | | A local MCP bridge for the workspace you choose | A hosted coding service | | A way for ChatGPT Developer Mode to inspect, edit, verify, and hand off work | A model unlock, proxy, resale layer, or quota workaround | | A repo-backed context system using explicit files such as AGENTS.md and .ai-bridge | Permanent ChatGPT memory across every chat | | A developer tool with conservative defaults | An OS sandbox or substitute for repo/terminal judgment |

Why CodexPro?

| ChatGPT gets | CodexPro provides | | --- | --- | | Repo context | AGENTS.md, .ai-bridge, git status, git diff, selected source files | | Coding actions | read, write, edit, search, show_changes | | Verification | safe bash for focused test, lint, build, and git commands | | Handoff | .ai-bridge/current-plan.md for Codex, OpenCode, Pi, or a custom local agent | | Fallback planning | .ai-bridge/pro-context.md for model surfaces that cannot call MCP tools |

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.

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 GPT-5.5 Pro or other model surfaces may not expose app actions in a given chat. If CodexPro actions are unavailable there, CodexPro cannot make that request reach the local server. Use a tool-capable ChatGPT surface or the Pro context fallback instead. CodexPro does not provide, proxy, resell, or unlock models; it gives compatible ChatGPT sessions local coding tools and repo context.

CodexPro vs generic workspace bridges

The high-level shape can look similar because both use a local MCP bridge, a tunnel, and a workspace root. CodexPro is narrower and more opinionated: it is built to make ChatGPT Developer Mode work like a practical local coding agent for one repo.

| CodexPro focuses on | Why it matters | | --- | --- | | ChatGPT-first coding loop | The first-run path is install, setup in a repo, paste one Server URL, then let ChatGPT inspect, edit, verify, and review that workspace. | | Explicit safety modes | Bash, write/edit, tool catalog size, Codex session reads, and handoff execution are separate controls instead of one broad remote-control switch. | | Repo-backed continuity | AGENTS.md and .ai-bridge/* keep durable project context in the repo, not hidden in a chat transcript or one machine-local UI state. | | Reviewable outputs | Tool cards, diffs, show_changes, smoke tests, and handoff status files are designed so users can see what changed before trusting it. | | TOS-safe product boundary | CodexPro does not proxy models, pool accounts, scrape third-party Pro sites, bypass quotas, or pretend to be an OS sandbox. |

So the short answer is: generic workspace bridges may share the transport idea, but CodexPro is positioned as the cleaner ChatGPT-to-local-repo coding product with stricter defaults, clearer admin controls, and a repo-first agent workflow.

Preview

The website and ChatGPT cards are designed to keep repo inventory, git details, terminal output, and raw diffs folded until you ask for them. The normal path is a compact card plus a clear diff or verification result, not a chat full of raw tool data.

Feature Map

| Area | Details | | --- | --- | | Workspace open | open_current_workspace, open_workspace, tree, search, read | | Editing | workspace-scoped write and exact-replacement edit, both returning diffs | | Review | show_changes, git_status, git_diff, compact visual cards | | Safety | workspace-only writes, safe bash by default, blocked secret/build/cache paths, token-protected public URLs | | Context | codex_context, read_handoff, selected-only export_pro_context | | Local execution | execute-handoff and watch-handoff run from your terminal, not as remote MCP tools |

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

Requirements

Node.js 20+
ChatGPT 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 an account tier where ChatGPT shows Apps / Developer Mode.

Account tier and model tool support are separate things. Eligible accounts can expose Apps / Developer Mode, but a specific model surface may still be unable to call the connector. If CodexPro actions are unavailable in that chat, use another tool-capable ChatGPT surface or the Pro context fallback for that session.

Status

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 optional compact visual cards.

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.

Compliance boundary

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.

Tools exposed to ChatGPT

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. Workspace open calls stay lean by default; use explicit skill discovery or codexpro_inventory when ChatGPT needs installed user/plugin skills, then load only the required skill with load_skill.

CodexPro also exposes one stable wrapper tool named codexpro. It accepts action plus args and can call only tools already registered by the current tool/write/bash mode. Use it for advanced connector-cache or custom workflow cases where a stable visible schema matters. The explicit tools below remain the preferred default because they give ChatGPT clearer descriptions and validation.

Standard mode exposes:

• codexpro — stable supertool wrapper for already-registered actions; call with action=list_actions to see what the current mode allows.
• 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; literal search falls back to Node when ripgrep is unavailable, while regex search requires ripgrep.
• 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. Advertised only when CODEXPRO_WRITE_MODE=workspace.
• edit — exact text replacement and return a diff. Advertised only when CODEXPRO_WRITE_MODE=workspace.
• bash — run allowlisted shell commands in the workspace. Hidden when CODEXPRO_BASH_MODE=off.
• show_changes — one review-oriented summary with git status, diff stats, and optional diff.
• read_handoff — read .ai-bridge files.
• wait_for_handoff — read-only polling of .ai-bridge/handoff-run-state.json after a local executor run.
• 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:

codexpro
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 for the current CodexPro server/config.
• 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.
• codexpro loop-handoff — run a bounded local execute/review loop where a user-provided reviewer command can pass or rewrite .ai-bridge/current-plan.md for another local executor iteration.

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      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
.ai-bridge/handoff-run-state.json

For autonomous local handoff loops, use loop-handoff with an explicit reviewer command:

codexpro loop-handoff \
  --agent opencode \
  --model provider/model \
  --review-command "node ./reviewer.js --status {{status_file}} --diff {{diff_file}} --log {{log_file}} --plan-file {{plan_file}}" \
  --max-iters 3 \
  --stop-if-no-files-changed \
  --stop-if-same-diff \
  --yes

The reviewer command runs locally after each executor iteration. It must inspect the generated files, then either print CODEXPRO_REVIEW=PASS or print CODEXPRO_REVIEW=FAIL and update .ai-bridge/current-plan.md with the next fix plan. CodexPro stops on pass, max iterations, missing verdict, no usable follow-up plan, repeated diff, no new executor changes, reviewer error, executor/test failure, or human cancellation. Loop change detection compares each iteration against a pre-execution baseline and counts unstaged diffs, staged diffs, and bounded untracked file fingerprints outside .ai-bridge.

Useful loop placeholders:

{{plan_file}}    .ai-bridge/current-plan.md
{{status_file}}  .ai-bridge/agent-status.md
{{diff_file}}    .ai-bridge/implementation-diff.patch
{{log_file}}     .ai-bridge/execution-log.jsonl
{{tests_file}}   .ai-bridge/loop-tests.txt
{{review_file}}  .a

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rebel0789](https://github.com/rebel0789)
- **Source:** [rebel0789/codexpro](https://github.com/rebel0789/codexpro)
- **License:** MIT
- **Homepage:** https://rebel0789.github.io/codexpro/

Install and usage instructions live in the source repository linked above.