# WebGPT Codex Bridge

Continue a local coding task in your own web ChatGPT account. The bridge runs on **your PC**, using your accounts and OS permissions. No inference API SDK, model API key, or Pro model is included or required.

**v0.2 adds explicit full access:** launch with `--access full` to run arbitrary shell commands, tests, Git commits/pushes and deployment CLIs, and read/write any OS-accessible path. Commands have durable output, stdin and cancellation, no default timeout, and no handoff-session or job quota. Updating an existing installation does not enable this mode automatically. Read [full-access setup and exact boundaries](docs/full-access.md) before connecting it. OS permissions and ChatGPT/Codex product controls remain.

Status: early release. Local execution and failure recovery are tested. Account-specific remote ChatGPT MCP, persistent login, and long-running hidden-browser behavior require the acceptance checks in [compatibility](docs/compatibility.md). 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/`):

```powershell
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.

## Start a handoff

The remaining handoff sections describe **scoped mode**, which is retained for compatibility. Full-access users follow [docs/full-access.md](docs/full-access.md) and do not need `begin`, file scope, or `release`.

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.

```powershell
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](docs/connection.md) 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.

```powershell
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.

```powershell
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](docs/security.md), [compatibility evidence](docs/compatibility.md), and [connection setup](docs/connection.md).