# ProBridge

[![CI](https://github.com/HAMZADEMIR33412005/probridge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HAMZADEMIR33412005/probridge/actions/workflows/ci.yml)
![Version](https://img.shields.io/badge/version-1.2.0-1677ff)
![Node.js](https://img.shields.io/badge/node-%E2%89%A520.0-339933?logo=node.js&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-1677ff)

![ProBridge cover](docs/cover.png)

Open-source local MCP bridge for **ChatGPT desktop Quick Chat + GPT-5.6 Pro**.

Coding agents in Codex, OpenCode, Claude, or similar MCP hosts call ProBridge. ProBridge queues the job, opens a verified ChatGPT Quick Chat, and sends the prompt. Inside that ChatGPT session, [LocalAnt](https://github.com/yuga-hashimoto/localant) / [DevSpace](https://github.com/Waishnav/devspace) is the connector that reaches your local Mac and the active workspace.

ChatGPT Pro quota is used. Codex model quota is not. There is no model API key.

**Current target: macOS.** Windows and Linux are not supported yet. Contributions that add a real driver for those platforms are welcome.

## How it fits together

```text
Codex / OpenCode / Claude
        |
        | MCP tool call
        v
     ProBridge
   prompt · queue · status · follow-up
        |
        | drives ChatGPT desktop Quick Chat
        v
 ChatGPT Quick Chat  (GPT-5.6 Pro)
        |
        | LocalAnt / DevSpace inside ChatGPT
        v
 authenticated device tunnel
        |
        v
 local Mac / active workspace
```

The calling agent only needs three tools:

```text
gpt56_pro_start({ prompt })
gpt56_pro_status({ jobId })
gpt56_pro_followup({ jobId, prompt })
```

`start` returns immediately with a `jobId`. Poll `status`. Use `follow-up` only after that same Quick Chat round is complete.

## What this repository adds

**LocalAnt / DevSpace gives ChatGPT access to your Mac.** ProBridge does not replace that connector and cannot install it for you.

**ProBridge gives your coding agent a bridge into ChatGPT Pro.** An MCP host sends ProBridge a prompt; ProBridge queues it, drives Quick Chat, and returns job state through MCP. That is why this repository makes sense when you already want ChatGPT Pro to do local work but want Codex, OpenCode, Claude, or another agent to invoke it as a sub-agent.

## Requirements

- macOS
- Node 20+
- Xcode command-line tools (`swiftc`)
- [ChatGPT desktop](https://chatgpt.com/desktop) signed in with **Pro**
- [LocalAnt](https://github.com/yuga-hashimoto/localant) / [DevSpace](https://github.com/Waishnav/devspace) connected in ChatGPT
- Accessibility permission for the compiled `bin/ax-driver`

[LocalAnt](https://github.com/yuga-hashimoto/localant) / [DevSpace](https://github.com/Waishnav/devspace) is what gives ChatGPT Pro hands on the machine. ProBridge is what lets other agents send work into that ChatGPT session.

## Setup — two required parts

### 1. Set up ChatGPT’s local connector first

ProBridge needs ChatGPT to already have a connector that can reach your local Mac. Choose one connector and complete its upstream setup before installing ProBridge:

- **LocalAnt (the tested path):** follow [LocalAnt’s setup guide](https://github.com/yuga-hashimoto/localant). The quick start is:

  ```sh
  npx -y localant setup
  localant tools profile coding
  ```

  `localant setup` prints your authenticated MCP endpoint. In ChatGPT desktop, go to **Settings → Apps & Connectors**, enable **Developer Mode**, choose **Connectors → Create**, paste that MCP endpoint, select **Authentication: None**, and name the connector `LocalAnt`. Keep LocalAnt’s local approval and security settings appropriate for your machine.

- **DevSpace:** follow [Waishnav/devspace](https://github.com/Waishnav/devspace) and connect its local environment to ChatGPT according to that project’s instructions.

Open a ChatGPT Quick Chat and verify that the selected connector can read a harmless local project file before continuing. This is a separate ChatGPT-side setup; installing ProBridge alone does not give ChatGPT access to your Mac.

### 2. Install ProBridge on the Mac

```sh
git clone https://github.com/HAMZADEMIR33412005/probridge.git
cd probridge
node scripts/build-ax.mjs
node scripts/install.mjs
node scripts/doctor.mjs
```

`install.mjs` creates `~/.codex/config.toml` if needed, writes the ProBridge MCP entry, and makes a timestamped backup when an existing config changes. Then grant Accessibility to `bin/ax-driver` if macOS asks, keep ChatGPT desktop open, and start a **new Codex chat**.

It does not set `cwd`; Codex should launch the server from the project you already have open.

### MCP for Codex

Automatic:

```sh
node scripts/install.mjs
```

Manual: copy [`examples/codex.config.toml`](examples/codex.config.toml) into `~/.codex/config.toml` and replace the absolute server path.

The registered server name is `probridge`. After any update, start a new Codex chat so it reloads the MCP process and daemon protocol.

### MCP for Claude Code / OpenCode / other hosts

Point a stdio MCP server at this checkout:

```json
{
  "mcpServers": {
    "probridge": {
      "command": "/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node",
      "args": ["/ABS/PATH/TO/probridge/src/server.mjs"]
    }
  }
}
```

See [`examples/claude-code.mcp.json`](examples/claude-code.mcp.json) and [`examples/opencode.json`](examples/opencode.json). If ChatGPT’s bundled Node is missing, any Node 20+ binary works.

The MCP host must start the server from the project workspace, or provide exactly one `file://` root. ProBridge refuses home, Desktop, Documents, and similar broad folders.

## Use it

From an agent in the project workspace:

```text
gpt56_pro_start({
  prompt: "Inspect the failing tests, fix the root cause, run focused tests, and report changed files."
})
```

Poll:

```text
gpt56_pro_status({ jobId: "pro_..." })
```

Continue the same Quick Chat after it completes:

```text
gpt56_pro_followup({
  jobId: "pro_...",
  prompt: "Now implement the review findings."
})
```

Jobs are queued. A second New chat can be sent as soon as the previous prompt is verified as submitted. Follow-ups stay on the same conversation.

Status lives in two places:

- `~/.chatgpt-pro-subagent/` — authoritative daemon state, queue, and lock
- `<workspace>/.chatgpt-pro-jobs/<jobId>.md` — cooperative control file ChatGPT writes through LocalAnt / DevSpace

On macOS, an MCP child or detached daemon can occasionally be denied access to a valid project folder by privacy controls or an ACL (Downloads is the common case). This never rejects a job: ProBridge automatically retries the same job with its control file at `~/.chatgpt-pro-subagent/control-files/<workspace-hash>/<jobId>.md`, returns that exact path in the start response, and gives it to the ChatGPT Pro session. The project workspace remains the only allowed work scope; the fallback is only the durable status/report file.

## Related projects

- [LocalAnt](https://github.com/yuga-hashimoto/localant) — ChatGPT’s local MCP gateway / computer connector
- [DevSpace](https://github.com/Waishnav/devspace) — local environment / computer connector used with ChatGPT

## Platform support

| Platform | Status |
| --- | --- |
| macOS | Supported. Native Accessibility driver. |
| Windows | Not supported. Needs a different UI driver. |
| Linux | Not supported. Needs a different UI driver. |

The MCP server, queue, and control-file protocol are OS-agnostic. The missing piece elsewhere is a trusted replacement for `src/native/ax-driver.swift`.

## Security

ProBridge drives the ChatGPT app you already signed into, then ChatGPT uses LocalAnt / DevSpace to touch the workspace. Treat that as same-user local execution, not a sandbox.

Runtime files under `~/.chatgpt-pro-subagent` are private (`0700` / `0600`). Workspace job files are excluded from git via `.git/info/exclude` when possible; a failure to update Git metadata never prevents a job from starting. Broad personal folders are refused as workspaces.

## Development

```sh
npm test
npm run build:ax
node scripts/doctor.mjs
```

## License

MIT