# Grok Bridge

Grok Bridge is a local Model Context Protocol (MCP) server and Codex plugin that lets ChatGPT Desktop and Codex delegate substantial work to the locally installed Grok Build agent. It works in repositories and standalone workspace directories.

It supports durable logical jobs, automatic continuation of recoverable Grok execution boundaries, live progress logs, persisted final results, cancellation, session discovery, and transcript export. Delegated jobs use `xhigh` reasoning effort by default.

> Community project. This repository is not affiliated with, endorsed by, or maintained by xAI or OpenAI. Grok and Grok Build are not included.

## What it provides

| Tool | Purpose |
| --- | --- |
| `grok_doctor` | Check the Grok executable, authentication, runtime, and defaults. |
| `grok_consult` | Run a quick synchronous, read-only consultation. |
| `grok_start` | Start a durable background logical job with workspace or enforced read-only access. |
| `grok_poll` | Read attempt/continuation state, progress tails, and the persisted final result. |
| `grok_cancel` | Cancel a known job and its child process tree. |
| `grok_list` | List recent bridge jobs and Grok sessions. |
| `grok_export_session` | Export a Grok session transcript as Markdown. |

The bundled skill routes every task that must finish through `grok_start`, teaches Codex to recover an existing job after caller context compaction, and requires independent verification of Grok's output.

## Completion model

One `grok_start` call creates one logical job under `~/.grok/bridge/jobs`, even when several Grok CLI processes are needed to finish it. The worker:

1. consumes Grok's `streaming-json` output as a progress heartbeat;
2. treats a normal `end_turn` as completion, not process exit code alone;
3. automatically resumes the same Grok session after max-turn, max-token, or context boundaries;
4. keeps per-attempt prompts, stdout, stderr, metadata, and the final result on disk;
5. stops on authentication, quota, permission, invalid-request, total-deadline, continuation-limit, or repeated no-progress blockers.

Grok's internal context compaction remains inside Grok and does not end a logical job. A Codex caller can reconnect later, find the job with `grok_list`, and continue polling it without watching an interactive console.

## Requirements

- Node.js 20 or newer.
- Grok Build installed locally.
- Grok authenticated through its own CLI, for example with `grok login --oauth`, or with an authentication method supported by your Grok installation.
- ChatGPT Desktop, Codex CLI, or another MCP client with STDIO server support.

By default the bridge looks for Grok at `~/.grok/bin/grok` (`grok.exe` on Windows), then falls back to `grok` on `PATH`. Set `GROK_BRIDGE_GROK_EXE` to override this.

## Install

Clone the repository and install the locked dependencies:

```bash
git clone https://github.com/conrad85/grok-bridge.git
cd grok-bridge
npm ci
npm run test:doctor
```

### Option A: install as a local Codex plugin

From the cloned repository, register its local marketplace:

```bash
codex plugin marketplace add .
```

Restart ChatGPT Desktop, open the Plugins Directory, select the **Grok Bridge** marketplace, and install the plugin. The plugin bundles both the MCP server configuration and the reusable skill. See the [official OpenAI plugin packaging documentation](https://developers.openai.com/plugins/build/plugins) for current marketplace behavior.

### Option B: configure the MCP server directly

Use the absolute path to your clone:

```bash
codex mcp add grok_bridge -- node /absolute/path/to/grok-bridge/server/index.mjs
```

To make the workflow skill available to new local sessions, copy `skills/grok-bridge` into your personal skills directory:

macOS/Linux:

```bash
mkdir -p ~/.agents/skills
cp -R skills/grok-bridge ~/.agents/skills/grok-bridge
```

Windows PowerShell:

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
Copy-Item -Recurse -Force "skills\grok-bridge" "$env:USERPROFILE\.agents\skills\grok-bridge"
```

Restart the desktop app after changing MCP or skill configuration.

## Example requests

- "Ask Grok to review this implementation at xhigh effort."
- "Use Grok as a builder, implement the feature, and run the tests."
- "Have Grok reproduce this bug as a tester, then independently verify the result."
- "Have Grok finish this report in the current non-repository workspace."

## Configuration

| Environment variable | Meaning |
| --- | --- |
| `GROK_BRIDGE_GROK_EXE` | Absolute path or command name for the Grok executable. |
| `GROK_BRIDGE_HOME` | Directory for bridge jobs and bounded logs. Defaults to `~/.grok/bridge`. |
| `XAI_API_KEY` | Optional authentication method when supported by the local Grok CLI. |

After installing or updating the plugin, start a new Codex session so its bundled skill and MCP tools are loaded together. Existing sessions retain the tool set they started with. Do not depend on paths under Codex plugin caches; invoke the plugin through the skill and `grok_*` tools exposed to the session.

## Safety and privacy

Builder jobs run Grok in its workspace sandbox and add explicit denials for commits, pushes, publishing, deployment, and broad destructive commands. Read-only consultations use stricter permissions. These are defense-in-depth controls, not a substitute for reviewing delegated work.

Durable reviews, planning, and research can use `grok_start` with `access: "read_only"`; implementation uses `access: "workspace"`.

Always pass an explicit absolute working directory. It may be a Git repository, an isolated worktree, or a dedicated non-repository task directory, but it must not be a filesystem root or an unnecessarily broad home directory. Do not run concurrent write jobs against the same files.

The bridge itself has no telemetry and does not bundle credentials. Grok Build may send prompts and project context to xAI as part of its normal operation. Job requests, output, and logs are stored locally under `GROK_BRIDGE_HOME`. Read [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md) before use.

## Development

```bash
npm ci
npm run build:mcp
npm run check
npm test
npm run audit:public
```

The committed `dist/index.mjs` and `dist/worker.mjs` are self-contained plugin runtime files. Codex plugin caches do not run `npm install`, so `.mcp.json` intentionally launches the bundle instead of the source tree. Rebuild and commit both files whenever server code or runtime dependencies change.

`npm test` uses a fake Grok executable to cover automatic resume after both historical max-turn result shapes, persisted final output, blocker classification, continuation exhaustion, a no-progress watchdog, and a non-repository working directory.

Tests that invoke a real authenticated Grok installation are intentionally separate:

```bash
npm run test:doctor
npm run test:live -- /absolute/project/path
npm run test:background -- /absolute/project/path
npm run test:builder -- /absolute/fixture/path
```

## License

MIT. See [LICENSE](LICENSE).