Skip to main content

Workspace Bridge

Workspace Bridge: plan in ChatGPT, build with your local agents

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, OpenCode v2, 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:

  1. Inspect. ChatGPT browses your project, searches it, and reads live Git status and diffs.
  2. Plan. It writes a short, reviewable handoff: task, context, and acceptance criteria, with optional screenshot or mockup references.
  3. Build. You paste the handoff into your agent, or, if you have enabled it, ChatGPT starts a bounded run on Claude Code, Codex, OpenCode v2, or Pi directly.
  4. 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.

Why plan in ChatGPT:

  • It already knows you. ChatGPT's built-in memory carries your preferences and past decisions into every planning session, with nothing to set up.
  • Take your time. Planning is a conversation, not a metered job. With ChatGPT's generous usage limits you can explore, push back, and refine a plan without worrying about running up a bill.
  • Truly remote work. The ChatGPT mobile app can drive the whole loop, so you can plan, start runs on your Claude Code, Codex, OpenCode v2, or Pi agents, and review the results from anywhere while your machine does the building.

The local Manager showing Pi, Codex, and Claude Code adapters

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, and tokens are kept out of APIs, logs, and chat.

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, and ACCEPTANCE.md kept in Bridge state, never in your repository, with a prompt ready to paste into any agent.
  • Checks: ChatGPT runs the test and lint commands you list for a workspace, and they can run after every agent run.
  • Local agent runs: Claude Code, Codex, OpenCode v2, 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: doctor diagnostics, user or system services on macOS and Linux, Nodes on other machines that pair and dial out, and Discord run notifications.

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 service that owns your files):

uv tool install workspace-bridge
workspace-bridge init
workspace-bridge local-node enable --allow-root "$HOME/Projects"
workspace-bridge serve

local-node enable runs this machine's Node inside the Bridge and registers it; --allow-root is the ceiling of folders it may expose. Then open the Manager at http://127.0.0.1:8766/:

  1. Sign in with the temporary bootstrap account (see Setup) and choose your own password.
  2. Check that the local Node shows as connected.
  3. Add a workspace mapping for one project and enable it.
  4. Create the shared gateway credential and generate the tunnel profile.
  5. 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, OpenCode v2, or Pi adapter on the Node with workspace-bridge local-node adapter add; the Node runs it as a plugin. See Runtimes. To keep the Bridge running, install it as a service with workspace-bridge service install. Projects on another machine get a paired Node there. Full instructions 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 1.0.0. 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

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 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for workspace-bridge 1.0.0
File Interpreter ABI Platform Actions
workspace_bridge-1.0.0-py3-none-any.whl Python 3 none any Details for workspace_bridge-1.0.0-py3-none-any.whl

Release files / workspace_bridge-1.0.0-py3-none-any.whl

Download URL workspace_bridge-1.0.0-py3-none-any.whl
Size 588.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
01e010342aa4bbdddbd58de88b2ad63ed7bc83771ba102250c724df2df98d8a0
BLAKE2b-256 checksum
How to use checksums
ebeb24f58723a8c0db57f46e35b54a8cadc0ae00a107c50ab4a56c62f122afae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 30, 2026.

Transparency log

Security for workspace-bridge 1.0.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-1.0.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 30, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page