Workspace Bridge
Plan in ChatGPT. Build with your local agents.
Workspace Bridge lets ChatGPT read the real code on your machine, plan the work, hand bounded tasks to Claude Code, Codex, or Pi running locally, and then review what they changed. You keep the strongest model for thinking and reviewing, a cheaper local agent does the typing, and nothing runs that you have not enabled.
ChatGPT ── plans, splits the work, reviews the result
│
│ one private MCP tunnel
▼
Workspace Bridge ── your local admin console decides what is visible and allowed
│
▼
Your machine ── real files, Git, and local agents (Claude Code, Codex, Pi)
Why
Big reasoning models are best at understanding a codebase, designing an approach, and checking work. They are expensive to use for every keystroke. Local coding agents are good at carrying out a precise task against the current checkout. Workspace Bridge connects the two in one loop:
- Inspect. ChatGPT browses your project, searches it, and reads live Git status and diffs.
- Plan. It writes a short, reviewable handoff: task, context, and acceptance criteria.
- Build. You paste the handoff into your agent, or, if you have enabled it, ChatGPT starts a bounded run on Claude Code, Codex, or Pi directly.
- Review. ChatGPT reads the result and the new diff, then approves the work or plans the next iteration.
Workspace Bridge is built this way: a frontier model plans and audits, and a local agent implements through the Bridge.
Safe by default
- Read-only until you say otherwise. New projects start disabled. Once enabled, ChatGPT can write only planning notes; source edits are a separate, per-project switch.
- No remote shell. ChatGPT gets typed tools for browsing, Git evidence, handoffs, and runs. It cannot run arbitrary commands.
- Agent runs are opt-in per project and per agent. Each run uses a security profile you choose; anything the profile marks "ask" pauses the run until it gets an explicit answer.
- Your admin console never leaves your machine. The Manager listens on loopback only and is never tunnelled.
- Secrets stay out. Common credential files are blocked, tokens are kept out of APIs, logs, and chat, and support bundles are created locally and never uploaded automatically.
Know the limits too: one shared connection credential covers every enabled project, and source that ChatGPT reads leaves your machine. Read Security before enabling writes or agent runs.
What you get
- Project browsing: directory trees, globs, regex search, paginated reads with hashes, and read-only Git status and diffs.
- Planning handoffs:
TASK.md,CONTEXT.md, andACCEPTANCE.mdpublished under.workspace-handoff/, ready to paste into any agent. - Local agent runs: Claude Code, Codex, and Pi through one runtime protocol, with per-agent model policy, security profiles, resumable approvals, and run-scoped usage.
- Images: screenshots and other rasters return as native previews.
- Local Manager: a terminal-style admin console for projects, agents, routes, models, runs, and diagnostics.
- Operations:
doctordiagnostics, sanitized support bundles, native services on macOS and Linux, Discord run notifications, and a Docker image.
Works with ChatGPT through OpenAI's secure MCP tunnel, and with any MCP client that supports Streamable HTTP. Runs on macOS, Linux, and WSL2.
Quick start (about 10 minutes)
Install the package, then initialize the Bridge and one Node (the local service that owns your files):
uv tool install workspace-bridge
workspace-bridge init
workspace-bridge node --state "$HOME/.local/state/workspace-bridge-node" init \
--allow-root "$HOME/Projects"
workspace-bridge node --state "$HOME/.local/state/workspace-bridge-node" service install
workspace-bridge serve
In another terminal, show the Node token. It stays in your terminal; never paste it into chat:
workspace-bridge node --state "$HOME/.local/state/workspace-bridge-node" show-token
Then open the Manager at http://127.0.0.1:8766/:
- Sign in with the temporary bootstrap account (see Setup) and choose your own password.
- Register the Node with its URL and the token from above.
- Add a workspace mapping for one project and enable it.
- Create the shared gateway credential and generate the tunnel profile.
- Connect ChatGPT (or another MCP client) to
/mcp.
Check everything with:
workspace-bridge doctor
Browsing and manual handoffs work at this point. To let ChatGPT start agent runs, add a Claude Code, Codex, or Pi adapter; see Runtimes. Full instructions, including Docker, are in Setup. If you would rather have a coding agent do the install, point it at Agent setup.
How it works
flowchart LR
Client["ChatGPT / MCP client"] --> Tunnel["Private MCP tunnel"]
Tunnel --> Bridge["Bridge<br/>/mcp + local Manager"]
Bridge --> Node["Node<br/>files, Git, handoffs"]
Node --> Claude["Claude Code adapter"]
Node --> Codex["Codex adapter"]
Node --> Pi["Pi adapter"]
The Bridge serves the MCP endpoint and the local Manager. Each Node owns the files, Git, and handoffs on its host and never lets the Bridge reach outside its allowed roots. Adapters wrap each local agent and enforce its security profile. A run reaches an agent only through an exact workspace-to-adapter route you enabled. See Architecture.
Status
Version 0.2.0, an early release under active development. Updates are
manual (uv tool upgrade workspace-bridge, then restart services); there is
no auto-updater. Native Windows is not supported; use WSL2. Known gaps and
validation status are listed in
Operations.
Documentation
- Setup: install and configure.
- Agent setup: runbook for a coding agent installing Workspace Bridge for you.
- Runtimes: Claude Code, Codex, and Pi.
- Security: threat model and controls.
- Architecture and Operations.
- MCP tools, Runtime Protocol, File access, Images, Handoff protocol, Docker, References.
- Full documentation index.
Contributing and security
Contributions are welcome; start with CONTRIBUTING.md. Report vulnerabilities privately as described in the security policy, not in public issues.
License
MIT. See LICENSE.
Metadata
Release files for workspace-bridge 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| workspace_bridge-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for workspace_bridge-0.2.0-py3-none-any.whl |
Release files / workspace_bridge-0.2.0-py3-none-any.whl
| Download URL | workspace_bridge-0.2.0-py3-none-any.whl |
|---|---|
| Size | 567.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f1d6e3ba766c57f35959c15b9cdc83561c781f023b9317b3d71dcdd375740fc6
|
|
BLAKE2b-256 checksum How to use checksums |
1f5c04c40274c9311fada2f4ca4cab626dc5ae64eb7bb210843f7092aa5ee0aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logSecurity for workspace-bridge 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
1 file in this release has been uploaded with provenance metadata.
Attestation for workspace_bridge-0.2.0-py3-none-any.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.