codex-from-chatgpt

Use ChatGPT as the architect and orchestrator, while your local Codex does the
actual work on your machine.

A personal, single-user MCP bridge. ChatGPT sends an instruction, the local
service turns it into a codex app-server --stdio thread, and returns a compact
summary of what Codex did.

Why

Codex is already good at doing the work. What it does not have is someone to
decide what work to do, review the result, and push back. That is the part
you normally do by hand, one prompt at a time.

This bridge puts ChatGPT in that seat. It plans, delegates, reads the diff, and
sends the next instruction — while every command and file change happens on
your machine, in your real repository, under approvals you control.

You: "Investigate this bug and fix it."

ChatGPT
  → starts a local Codex job
  → reviews the result
  → asks Codex for a correction
  → starts an independent review
  → handles approvals with you

Codex works on your actual local repo.

Dogfooded: v0.3 was developed using v0.2 — ChatGPT orchestrated local
Codex implementation and independent review through this MCP. See
Built using itself.

Community project, not official: this is not an official OpenAI or
ChatGPT integration.

Architecture

The product boundary is deliberately small:

ChatGPT (through a Secure MCP Tunnel)
  -> MCP Streamable HTTP (/mcp)
  -> compact job API
  -> codex app-server --stdio (JSONL)
  -> local Codex

It does not use codex mcp-server, does not expose shell or filesystem as MCP
tools, and implements no broker, worker farm, or external storage.

It also does not implement its own multi-agent framework — and does not need
one. ChatGPT can orchestrate multiple independent Codex jobs through the same
five-tool API: one job implements, another reviews it, and ChatGPT arbitrates
between them.

Built using itself

codex-from-chatgpt was built and validated through the same loop it exposes:
ChatGPT coordinated tasks over MCP, the bridge created local Codex threads, and
the app-server returned snapshots to review the result. That loop was used for
the implementation, follow-ups, independent reviews, and for answering Codex
approvals.

The same loop maintains it. Using the five tools described below:

1. Use codex_start to investigate a change and its risks.
2. Use codex_continue to implement or fix one concrete part.
3. Use codex_get to review the standard handoff; request debug only when
   the bounded command log or diff is needed.
4. Use codex_respond_approval to answer specific approvals via their exact
   request_id.
5. Run independent reviews, then npm run typecheck, npm test, and
   git diff --check before calling a change done.

The idea is that the bridge is both the development tool and the artifact that
documents how it is used.

Requirements

• Node.js 20 or later.

• Codex CLI on your PATH, installed and authenticated locally. Tested against
  Codex CLI 0.147.0 (app-server v2); other versions may work, and the
  installed binary is always the authority — see
  Protocol compatibility.

• A workspace directory, or a symlink entry for one, whose supplied path is
  under the allowed administrative root. That root defaults to ~/workspace
  and must exist:

  mkdir -p ~/workspace
  

• An OpenAI Platform account that can create tunnels, and a ChatGPT workspace
  where you can enable developer mode (see Plan availability).

Check your local Codex before wiring anything up:

codex --version

Setup overview

The full path from a clean clone to a working Codex job:

clone -> install -> configure -> run locally
      -> install tunnel-client -> configure tunnel -> doctor -> run tunnel
      -> connect in ChatGPT -> verify tools -> first Codex job

Each step below corresponds to one stage of that sequence.

1. Clone, install, run locally

git clone https://github.com/joseanu/codex-from-chatgpt.git
cd codex-from-chatgpt
npm install
npm run build
npm start

The process listens on loopback only by default:

• MCP: http://127.0.0.1:8787/mcp
• health: http://127.0.0.1:8787/healthz
• readiness: http://127.0.0.1:8787/readyz

2. Verify the local service

In a second terminal, confirm both the service and the Codex app-server are up.
/readyz returns 503 until the app-server has initialized:

curl -fsS http://127.0.0.1:8787/healthz
curl -fsS http://127.0.0.1:8787/readyz

To use a different administrative root or port:

CODEX_WORKSPACE_ROOT=/absolute/path/to/workspaces PORT=8787 npm start

Leave this process running. Everything below assumes it is up.

3. Install tunnel-client

ChatGPT does not connect directly to 127.0.0.1. OpenAI's supported path for a
local MCP server is the Secure MCP Tunnel, run by
tunnel-client — a customer-run
agent that bridges a private or localhost MCP server to ChatGPT and Codex over
long-polling HTTPS, keeping the server off the public internet.

ChatGPT
  -> OpenAI control plane
  -> tunnel-client (on your machine)
  -> http://127.0.0.1:8787/mcp
  -> codex-from-chatgpt
  -> codex app-server --stdio

Get the binary from the OpenAI Platform under Tunnels, or from the
release archives. Docker
images are published at ghcr.io/openai/tunnel-client. To build from source:

go build -o bin/tunnel-client ./cmd/client

OpenAI recommends starting with the built-in guide:

tunnel-client help quickstart

Credentials, and where each one comes from

Do not use the admin key as the daemon credential — OpenAI's docs call this
out explicitly. CONTROL_PLANE_API_KEY is the preferred variable;
OPENAI_API_KEY is only a fallback when it is unset.

4. Configure the tunnel

Export the two runtime values:

export CONTROL_PLANE_API_KEY="sk-..."
export CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef"

This project is an HTTP MCP server that is already running, so initialize from
the remote-HTTP sample and bind the main channel to its local URL:

tunnel-client init --sample sample_mcp_remote_no_auth \
  --profile codex-from-chatgpt \
  --tunnel-id "$CONTROL_PLANE_TUNNEL_ID" \
  --mcp-server-url http://127.0.0.1:8787/mcp

The resulting profile is YAML, and the main channel is required:

config_version: 1
control_plane:
  tunnel_id: tunnel_0123456789abcdef0123456789abcdef
  api_key: env:CONTROL_PLANE_API_KEY
  base_url: https://api.openai.com
mcp:
  server_urls:
    - channel: main
      url: http://127.0.0.1:8787/mcp

Profiles are discovered under $XDG_CONFIG_HOME/tunnel-client or
~/.config/tunnel-client; a single config file can also be passed with
--config or TUNNEL_CLIENT_CONFIG.

5. Doctor, then run the tunnel

Validate before starting the daemon:

tunnel-client doctor --profile codex-from-chatgpt --explain

Then run it in the foreground, in its own terminal:

tunnel-client run --profile codex-from-chatgpt

Host header: /mcp validates the Host header against the configured
HOST:PORT and rejects anything else with 403 (see
Security and limits). If your tunnel forwards its own
hostname instead of the loopback upstream, add it with
CODEX_AGENT_ALLOWED_HOSTS and restart this service.

6. Connect it in ChatGPT

Full MCP connectors live behind developer mode. An admin or owner enables it in
Workspace Settings → Permissions & Roles → Connected Data → Developer mode /
Create custom MCP connectors. Then create the custom MCP app pointing at your
tunnel, let ChatGPT scan the tools, and enable it for your chats. Do not enter a
127.0.0.1 URL in ChatGPT — it cannot reach it.

Plan availability

Full MCP support including write actions is in beta for ChatGPT
Business, Enterprise, and Edu on ChatGPT web. Pro users can build apps
with the Apps SDK and use custom apps in deep research, but for read/fetch
actions only.

This matters here: the five tools below are not read-only — they start Codex
turns that run commands and change files. On a plan limited to read/fetch, this
bridge will not work as intended. This project promises no universal support;
only the capabilities your connected ChatGPT environment exposes will be
available.

7. Verify the tools

After the scan, ChatGPT should list exactly five tools: codex_start,
codex_get, codex_continue, codex_interrupt, and codex_respond_approval.
If they are missing, re-check tunnel-client doctor and /readyz before
touching anything in ChatGPT.

8. First Codex job

Ask for something read-only first, with an absolute workspace path under the
allowed root:

Use codex_start in the workspace "/Users/you/workspace/my-project"
to inspect the git status without modifying any files. Give me the job_id,
then check the result with codex_get.

The normal flow is:

1. codex_start creates the persistent thread and begins the first turn.
2. codex_get returns the revision-aware job snapshot (standard by default).
3. When a turn finishes, codex_continue sends the next instruction to the
   same thread.
4. If Codex asks for an approval, codex_respond_approval answers it using the
   exact request_id from pending_approvals.
5. codex_interrupt stops an active turn when needed.

MCP tools

The public surface is exactly this:

codex_get has three deliberately different payload sizes:

• compact is for polling: status, revision, current activity, and critical
  errors or approvals.
• standard is the default supervisory handoff. While running it includes
  useful activity and changed files; after completion it includes the final
  message, files, deterministic diffstat, and recognized validation results,
  without the full command log or patch.
• debug includes bounded commands_executed and latest_diff fields for
  diagnosis. The underlying state remains available for recovery and is not
  discarded when standard hides it.

Pass since_revision from the previous response to suppress unchanged compact/
standard supervisory payloads; debug is always an on-demand current diagnostic
snapshot. An unchanged response is intentionally tiny (status, revision,
and unchanged: true), but pending approvals and errors are still surfaced.
The revision is persisted per job and tracks supervisory/control-plane state.
Debug-only command history and raw diff changes can update without advancing
it.

Recommended flow: save the revision from codex_start, poll with compact and
since_revision, then when the job completes call codex_get with
detail: "standard" and no cursor for the final handoff. The cursor means “I
know this supervisory state”, not “I have seen this detail view”, so a standard
request with the same revision may also be unchanged; unchanged responses omit
already-known warnings, while pending approvals and errors remain visible.

Every persistent thread also receives one short internal completion-handoff
requirement automatically. It asks Codex's final response to state actions,
files changed, validation and results, plus unresolved warnings or limitations;
the caller's original prompt remains intact, and the requirement is not
repeated on every continuation.

Approvals include their exact request_id, kind, and enough detail to choose a
decision even in compact or unchanged polling responses. pending_approval
remains an alias for the first approval, while pending_approvals carries all
currently pending approvals. The bridge never returns the raw JSONL stream.

Approvals accept only the values and objects defined by the installed protocol
for command execution, file changes, permissions, and legacy approvals.
request_id is mandatory: two approvals can be pending at once, and one is
never answered by position or by "the last one received".

Lifecycle, persistence, and recovery

States are starting, running, awaiting_approval, interrupting,
completed, interrupted, failed, and recovery_required.

v0.3 allows a single active turn per process/app-server. A concurrent start
or continue returns a semantic backend-busy error; interrupt remains
available for the active turn. A process failure or a timeout with an uncertain
outcome leaves the job in recovery_required — never in an invented
completed.

The minimal job_id → thread_id index, workspace, last turn, and summary are
written atomically to a local file. Its location can be set with
CODEX_AGENT_STATE_FILE. Its contents may include final messages, diffs,
files, commands, and errors, so treat it as potentially sensitive.

On app-server initialization, persisted jobs are rehydrated via thread/read
and, where applicable, thread/resume. If the state cannot be proven, the job
stays in recovery_required rather than silently becoming completed.

Security and limits

• The service binds to 127.0.0.1 by default.
• /mcp validates the Host header against the configured HOST:PORT and
  answers 403 to anything else. This closes DNS rebinding: a website the user
  visits cannot resolve its own domain to 127.0.0.1 and talk to the local
  service. Add extra hostnames with CODEX_AGENT_ALLOWED_HOSTS if the tunnel
  rewrites Host.
• The workspace path must be absolute, existing, and logically under the
  allowed root. A symlink located under that root is supported: it is resolved
  before the canonical path is sent to Codex. A path supplied outside the root
  is still rejected.
• For an accepted symlink, the root is a logical entrypoint boundary; the
  symlink target may therefore live outside the root's physical directory.
• NUL bytes, .. segments, and invalid roots are rejected.
• The remote client cannot choose config, model, sandbox, or permissions;
  environment overrides are administrative and local to the process.
• These tools are not read-only. Review Codex approvals before accepting
  commands, file changes, or permissions.
• Non-loopback binds require the explicit opt-in
  CODEX_AGENT_ALLOW_NON_LOOPBACK=1, and only when a tunnel covers the whole
  transport. The tunnel is not part of this repository.

Administrative configuration

• HOST and PORT: default 127.0.0.1:8787.
• CODEX_AGENT_ALLOW_NON_LOOPBACK=1: permits a non-loopback bind, only with
  equivalent external protection.
• CODEX_AGENT_ALLOWED_HOSTS: comma-separated extra hostnames accepted in the
  Host header on /mcp. Only needed if the tunnel forwards its own Host
  instead of the loopback upstream.
• CODEX_BIN: local binary; defaults to codex.
• CODEX_RPC_TIMEOUT_MS: generic RPC timeout; defaults to 30000 ms.
• CODEX_SHUTDOWN_TIMEOUT_MS: graceful shutdown wait; defaults to 2000 ms.
• CODEX_AGENT_STATE_FILE: optional state JSON location.
• CODEX_WORKSPACE_ROOT: optional administrative root; defaults to
  ~/workspace. Must be an existing absolute path.
• CODEX_AGENT_MODEL and CODEX_AGENT_REASONING_EFFORT: optional local
  overrides; without them Codex uses its own local configuration.

Protocol compatibility

The implementation is pinned against the observed protocol of
codex-cli 0.147.0, app-server v2. The installed binary is the authority:
OpenAI/Codex can change independently of your local CLI.

The client uses initialize → initialized, bidirectional JSONL, and the
required RPCs thread/start, thread/resume, thread/list, thread/read,
turn/start, and turn/interrupt, plus server-initiated approvals.

The generated TypeScript bindings in protocol/codex-0.147.0-ts/ are tracked
because the code imports them for build-time type safety.

The JSON schemas are not tracked — nothing in the runtime or the build
consumes them, so the repository does not carry hundreds of derived files. If
you want them as a protocol reference, generate them against your installed
binary:

codex app-server generate-json-schema --out protocol/codex-0.147.0-json-schema

That directory is in .gitignore. To move the pin to another version, install
and verify the new CLI and regenerate the bindings:

codex app-server generate-ts --out protocol/codex-<version>-ts

Then review imports, approvals, and tests against the installed binary.

Local validation

npm run typecheck
npm test
npm run build
git diff --check

The optional integration test against the installed binary:

CODEX_REAL_APP_SERVER=1 npm test -- --test-name-pattern='installed codex'

Documentation and sources

Official OpenAI documentation this project is built against:

• Secure MCP Tunnel guide
• openai/tunnel-client
• tunnel-client onboarding
• tunnel-client configuration reference
• tunnel-client permissions
• tunnel-client troubleshooting
• Developer mode and MCP apps in ChatGPT
• MCP in ChatGPT
• Codex App Server

Everything outside those interfaces — the job model, the compact snapshot, the
approval routing by request_id, the recovery semantics, and the workspace
validation — is this project's own design.

License

MIT. See LICENSE.