Mac Developer Bridge

Give ChatGPT a real terminal on your Mac.

Mac Developer Bridge turns a ChatGPT conversation into the reasoning layer for your actual Mac. It can run shell commands, edit files, start interactive terminal sessions, manage long-running jobs, read stored Codex threads without starting another Codex model turn, and optionally operate your real logged-in Chrome tabs in the background without stealing focus.

Example: “Find the Codex session I was working on yesterday, inspect the live repo, fix CI, push the result, and tell me what changed.”

That is the kind of workflow this project is built for.

[!WARNING] Mac Developer Bridge deliberately gives an MCP client the effective permissions of your macOS user. It is not sandboxed and has no command or path allowlist. Read SECURITY.md before enabling it.

The idea

ChatGPT has the reasoning. Your Mac has the source code, terminal, credentials, build tools, local services, and work in progress. Mac Developer Bridge connects the two over MCP without adding another model or agent loop in the middle.

flowchart LR
    A[ChatGPT] -->|MCP| B[Mac Developer Bridge]
    B --> C[Shell, Git and local CLIs]
    B --> D[Filesystem]
    B --> E[Real PTY sessions]
    B --> F[Background jobs]
    B --> G[Stored Codex history]
    B --> H[Audit log and kill switch]

The bridge itself makes no OpenAI model call. It exposes deterministic local tools; ChatGPT supplies the reasoning. The Codex-history tools use read-only codex app-server methods and never call turn/start.

What this unlocks

• Recover a stored Codex thread, inspect the repo it refers to, and continue the work from ChatGPT.
• Run tests, builds, Git, package managers, database CLIs, AppleScript, and other tools already installed on your Mac.
• Keep interactive shells and terminal programs alive through a real PTY instead of pretending stdin is a terminal.
• Start long-running local jobs, inspect their logs later, and stop the whole process group.
• Read and modify files anywhere your macOS user can access.
• Optionally operate approved pages in your real logged-in Chrome profile without bringing Chrome to the foreground.

This is intentionally different from a local coding agent. There is no second reasoning loop. ChatGPT remains the agent; the Mac is the execution environment.

Quick start

For a personal ChatGPT account, the menu-bar app is the easiest path. You need macOS, Node.js 18+, cloudflared, a hostname/tunnel, and ChatGPT Developer mode.

git clone https://github.com/alexanderradahl/mac-developer-bridge.git
cd mac-developer-bridge
./menubar/build.sh
open /Applications/MacDevBridge.app

Use Start, then Copy ChatGPT Setup from the menu-bar app. The detailed OAuth and Cloudflare setup is in Connecting to ChatGPT and DEPLOY.md.

Workspace users who have access to OpenAI Secure MCP Tunnel can use install.sh instead. See Transports.

Want to see what to ask it to do? Start with the copy-paste workflows.

If this is useful, star the repo so other developers can find it. If you build something interesting with it, share the exact workflow in What are you making ChatGPT do on your Mac?.

This is an independent open-source project and is not an official OpenAI or Cloudflare product. OpenAI, ChatGPT, Codex, and Cloudflare are trademarks of their respective owners.

Open source

Mac Developer Bridge is released under the MIT License. Bug reports and focused pull requests are welcome; see CONTRIBUTING.md. Security-sensitive reports should follow the guidance in SECURITY.md rather than being posted publicly.

Capabilities

• Arbitrary shell commands through /bin/zsh -lc, under the logged-in macOS user
• Detached background jobs with persistent stdout/stderr logs, status inspection, and process-group termination
• Unrestricted file read, write, append, list, stat, copy, move, chmod, symlink, mkdir, and recursive delete
• Unified-diff application through git apply
• Stored Codex thread discovery and reading without resuming a thread or starting a Codex model turn
• Paginated Codex turn retrieval for histories too large for a single response
• Local JSONL auditing
• Outbound-only private connectivity through OpenAI Secure MCP Tunnel, or a plain-HTTP loopback front end that Cloudflare Tunnel publishes over HTTPS
• Per-user persistence through a macOS LaunchAgent
• Fail-closed unlock latch: bridge.mjs re-reads the unlock file before every tool call, so removing it refuses the next call and exits — unless the process inherited MAC_DEV_BRIDGE_FULL_ACCESS_ACK, which bypasses the file entirely
• Local kill switch (scripts/disable.sh), which stops the front end, the bridge, the optional background-Chrome native host, detached shell_start job groups, interactive pty sessions, and federated child MCP servers, verifying the same targets it signalled

Git, package managers, Vercel CLI, database CLIs, AppleScript, browser CLIs, build tools, and other installed programs remain reachable through shell_exec; the bridge deliberately maintains no command allowlist.

Tools

| Tool | Purpose | |---|---| | bridge_status | Runtime identity, paths, permissions context, shell, audit mode, Codex binary, focus policy, and background-Chrome status | | chrome_workspace_status | Inspect the extension-owned MDB Chrome group, lease activity, and reusable background-tab pool; no website grant required | | chatgpt_extension_status | Inspect the installed ChatGPT Chrome extension, OpenAI native-host registration, and live read-only page-bridge status without patching the OpenAI extension | | chatgpt_conversation_start | Experimentally start or continue one exact ChatGPT conversation through the signed-in page's first-party runtime action; no UI typing/clicking or credential export | | chrome_workspace_setup | Provision a growth-only MDB pool target from 1 to 32 tabs; default is eight, with creation deferred until Chrome is naturally focused | | chrome_tabs | List tabs in the real signed-in Chrome profile without activating Chrome; scoped only when Strict approvals is on | | chrome_open | Lease an idle tab from the persistent MDB group and open a URL without creating a new tab | | chrome_navigate | Navigate an approved tab without selecting it | | chrome_snapshot | Read visible text and interactive elements from an approved tab | | chrome_click | Click an element in an approved tab without foregrounding Chrome | | chrome_fill | Fill inputs, textareas, selects, or contenteditable fields in the background | | chrome_close | Release an MDB workspace tab back to the idle pool, or close a non-workspace background tab | | shell_exec | Run any foreground shell command, optionally with cwd, env, stdin, timeout, and output cap | | shell_start | Start a detached long-running process | | shell_job_status | Inspect running state and log tails | | shell_job_list | List persistent job metadata | | shell_job_kill | Signal a background process group | | fs_read | Read text or base64 with offset pagination | | fs_write | Atomic replace, create, append, or binary write | | fs_list | Recursive or non-recursive directory listing | | fs_stat | lstat metadata and symlink target | | fs_manage | mkdir, remove, move, copy, chmod, or symlink | | apply_patch | Apply or check a unified diff with git apply | | codex_thread_read | Read a stored Codex thread without resuming it | | codex_thread_list | Search and page stored Codex threads | | codex_thread_turns_list | Page stored turns with full, summary, or omitted items | | audit_tail | Read the local bridge audit tail |

Background Chrome without stealing focus

On macOS, the optional Background Browser integration operates the same signed-in Chrome profile you already use, so existing website sessions work, but routine automation happens through a small local extension instead of AppleScript UI automation or Chrome DevTools Protocol page selection. The native host is bound at install time to the selected Chrome profile/account and refuses a signed-out or mismatched profile.

This is intentionally opt-in because authenticated browser control is powerful. Install the native host once, then load the unpacked extension once in Chrome:

./scripts/install-background-chrome.sh

Then in Chrome open chrome://extensions, enable Developer mode, choose Load unpacked, and select this repository's chrome-extension/ directory. The expected extension id is pcebfblnmcappinbenkmddjdapaoajgm.

The extension keeps a Chrome-native tab group named MDB. By default it targets eight extension-owned idle tabs, with a hard maximum of 32. They are created only while the existing MDB Chrome window is already naturally foreground, then leased and reused for routine work. The group is collapsed when idle and expands while one or more tabs are leased. This preserves the no-focus-steal boundary around a macOS/Chrome quirk measured on this project: even chrome.tabs.create({ active:false }) can bring Chrome to the foreground.

The pool self-heals and has a persistent growth-only capacity target. chrome_workspace_setup(pool_size=16) records a 16-tab target immediately. If the MDB Chrome window is already focused, the missing tabs are created and grouped at once; otherwise status reports the pending count and the extension expands on the next natural Chrome focus. A lower later request never closes existing tabs. When every current tab is leased and no expansion is already pending, pressure raises the target by four, up to 32, and attempts immediate creation only when Chrome is already focused. MDB never activates Chrome to satisfy either manual or automatic provisioning.

chrome_workspace_status is grantless because it only reads extension-owned local workspace state. It reports current and target pool sizes, the 32-tab maximum, four-tab automatic growth step, pending capacity, lease age/idle metadata, the 10-minute idle-reclaim timeout, and the 20-second lease-wait budget. chrome_workspace_setup is also grantless: provisioning is always accepted locally, while actual creation remains deferred when Chrome is not focused. Legacy/internal tabs.open callers are routed to the same workspace.open lease path, so they cannot create loose tabs outside MDB. When all tabs are busy, chrome_open first provisions or creates capacity where safe, then waits briefly for a release; abandoned leases are reclaimed after 10 minutes without browser activity, while every navigate/snapshot/click/fill renews an active lease.

Relaxed access is the default. Normal HTTP/HTTPS work, including localhost and non-default ports, through the signed-in MDB Chrome profile does not require a terminal approval command or per-site allowlist. This is intentional: Mac Developer Bridge already exposes unrestricted shell/file authority as the logged-in macOS user, and the useful default is for browser execution to match that operator-chosen trust level while remaining background-first.

Relaxed approval does not relax Chrome routing. Direct Chrome control through shell_exec/shell_start — AppleScript, JXA, direct Chrome executable launches, or shell open of an HTTP/HTTPS URL (including `open -g