WebGPT Codex Bridge

Continue a local coding task in your own web ChatGPT account. The bridge runs on your PC, using only the project and exact file paths you authorize. It does not connect to the author's PC or require their accounts. No inference API SDK, model API key, or Pro model is included or required.

Status: early release. Local CLI/stdio/HTTP read-create-modify and failure recovery are tested on Windows. Account-specific remote ChatGPT MCP, persistent login, and long-running hidden-browser behavior require the acceptance checks in compatibility. A local test is not proof of a remote ChatGPT tool call.

Install

Install Node.js 22+ and Git using official installers. Obtain this repository, open the package root containing package.json, and run (the original full-access checkout stores this package under bridge/):

git clone https://github.com/hsdc1258/webgpt-codex-bridge.git
cd webgpt-codex-bridge
npm test
npm install --global .
wgbridge help
wgbridge install-skill --dest "$env:USERPROFILE/.agents/skills"

On macOS/Linux use wgbridge install-skill --dest "$HOME/.agents/skills". The core has no npm dependencies. macOS/Linux code paths are provided but not locally certified. Reopen the Codex task to discover $webgpt-handoff; installation does not configure a ChatGPT account automatically. You can also run node /path/to/bridge/cli.mjs without global installation. Every command takes your own paths.

The distributed files are explicitly allowlisted in package.json; local configuration, credentials, runtime state, and personal browser sessions are excluded. Never commit handoff files or .webgpt-bridge/ state. Add that directory to the target project's ignore rules before starting.

For a release archive, download webgpt-codex-bridge-VERSION.tgz from the repository's Releases page, compare its published SHA-256, then run npm install --global ./webgpt-codex-bridge-VERSION.tgz. Source-based installs include tests; the small runtime archive excludes the test suite.

Related MCP server: codex-web-bridge

Start a handoff

Pause competing edits, or use a separate Git worktree. Choose a narrow project root. Copy examples/scope.json to a private work directory, then set your objective, constraints, and exact allowed files. Include future new files in the list; their initial content/hash is null. Uncommitted file content is included as it exists on disk, and current Git HEAD/branch are recorded.

wgbridge begin --root "D:/projects/my-app" --spec "D:/private/scope.json" --out "D:/private/handoff.json"

The output contains the session id, selected file text and SHA-256 hashes, and a reply schema. It excludes absolute project paths and Git remotes. Review it before sharing. The bridge blocks hidden paths, key/credential filenames, common token signatures, symlinks/junctions and hardlinks, but cannot detect all secrets or personal information in ordinary source files.

Route A: direct MCP from web ChatGPT

Use connection instructions to connect your own authenticated local bridge through your own Secure MCP Tunnel. In web ChatGPT select the app and ask:

Use WebGPT Codex Bridge. Call read_context for session SESSION_ID, implement its objective, then use apply_changes. Only the listed paths are authorized. Report actual writes separately from tests.

The MCP offers read_context, read_file, apply_changes and session_status. Reads return the authorized snapshot; apply checks live files against that snapshot. It has no arbitrary shell, delete, commit, push or deployment tool. After applying a round, read context again for updated hashes. The local bridge and tunnel run independently of Codex inference, so you can continue directly in web ChatGPT with Codex stopped. Client confirmations still apply. Tests/integration can be run from your terminal or in a resumed Codex task.

Route B: file handoff without MCP

Paste or upload handoff.json in your normal ChatGPT conversation. Ask for only the JSON object specified in instructions. Save the JSON content (without Markdown fences) as a private changes.json. No browser extension, public server, tunnel key or model API key is required for this route.

Use the response's Copy action to preserve exact code and escaping. If JSON validation fails, ask ChatGPT to regenerate a valid object with the same session/base hashes; no files are changed on a parse failure. Do not reconstruct code from an accessibility snapshot or automatically execute a suggested repair command.

wgbridge preview --root "D:/projects/my-app" --proposal "D:/private/changes.json"
wgbridge apply --root "D:/projects/my-app" --proposal "D:/private/changes.json"
wgbridge context --root "D:/projects/my-app" --session SESSION_ID --out "D:/private/next-handoff.json"

Review the proposed file contents alongside the preview hash summary. apply checks scope, hashes and current Git identity before writing. Web-generated commands are never executed. You can perform this route manually with Codex stopped; automatic transfer via Codex's hidden browser requires a running/resumed Codex task and consumes its normal usage. It is not an unattended browser agent.

Verify, resume, and finish

Inspect git diff, inspect newly created files, and run the project's relevant tests locally. The bridge never represents a model's statement as test evidence.

wgbridge status --root "D:/projects/my-app" --session SESSION_ID
wgbridge resume --root "D:/projects/my-app" --session SESSION_ID
wgbridge release --root "D:/projects/my-app" --session SESSION_ID

Only one session owns a project at a time. Every operation takes a process lock; no expired lease is stolen. After a crash use unlock --root PROJECT only when the recorded process has exited. Resume uses the saved original proposal. Writes are atomic per file, not an all-or-nothing batch; already written files are recognized on replay. A file with an unexpected hash stops recovery. Original text remains in the journal until the batch finishes. Resolve conflicts manually; do not overwrite others' edits or forge base hashes. After release, the retained state is private local history, not a Git deliverable.

Update and uninstall

Finish or reconcile any pending batch and stop the old bridge process. Pull the repository with git pull --ff-only, run its tests, then run npm install --global . from the package root. Update the skill with wgbridge install-skill --dest SKILLS_DIRECTORY --update true; changed skills receive a timestamped backup. Restart the service and refresh tool definitions in ChatGPT. Check session_status before further writes. State format is version 1; future incompatible releases must provide a migration before replacing the runtime.

Remove the command with npm uninstall --global webgpt-codex-bridge. Remove only this skill's directory after checking for local edits. Stop only the bridge/tunnel processes you started. Disconnect your app in ChatGPT if desired. Runtime journals/tokens are intentionally retained for explicit local cleanup. No scheduled task or login daemon is installed automatically.

See security and limitations, compatibility evidence, and connection setup.