OzBridge

# OzBridge — Warp Oz for any IDE or agent, via MCP
[![Build](https://github.com/sena-labs/OzBridge/actions/workflows/ci.yml/badge.svg)](https://github.com/sena-labs/OzBridge/actions/workflows/ci.yml)
[![VS Code](https://img.shields.io/badge/VS%20Code-%5E1.96.0-blue)](https://code.visualstudio.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![OzBridge screenshot](media/screenshot.png)
## What is OzBridge?

**OzBridge is an open-source [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) server and VS Code extension that runs Warp Oz cloud and local agents from any
MCP-compatible client — GitHub Copilot Chat, Claude Code, Cursor and Codex CLI.**

> **Independent extension** — not affiliated with, endorsed by, or sponsored by Warp, Inc.
> **Warp™** and **Oz™** are trademarks of Warp, Inc., used here nominatively only to
> describe interoperability. OzBridge uses solely Warp's **documented public interfaces**
> (the `oz` CLI, the Model Context Protocol, and the `WARP_OUTPUT_FORMAT` env var); it does
> not modify, reverse-engineer, or compete with Warp. See [DISCLAIMER](DISCLAIMER.md).

Run it embedded in VS Code — where Oz shows up natively as the `@oz` **Chat
Participant** and as **Agent-Native Language Model Tools** that Copilot Agent
mode invokes autonomously — or expose the same Oz toolset over HTTP+SSE so
**Claude Code, Cursor and Codex** drive Oz too. No editor at all? Ship the
standalone [`@sena-labs/oz-mcp-server`](packages/oz-mcp-server) and point any
MCP client at it.

```mermaid
flowchart LR
    subgraph clients["MCP clients"]
        CC["Claude Code"]
        CU["Cursor"]
        CX["Codex CLI"]
    end
    VSC["VS Code<br/>Copilot Chat"]

    clients -->|"HTTP + SSE"| BR
    VSC -->|"@oz participant<br/>LM Tools"| BR

    BR["OzBridge<br/>(6 MCP tools)"] -->|"spawn"| CLI["oz CLI"]
    CLI -->|"local run"| WS["Your workspace"]
    CLI -->|"cloud run"| CLOUD["Warp Oz cloud"]
```


## Feature gallery

### Runs & Resources

![OzBridge sidebar with active runs, history and schedules](media/screenshot-runs.png)

### Warp Drive

![Warp Drive prompt and skills preview inside VS Code](media/screenshot-drive.png)

### MCP bridge

![Embedded MCP bridge status with registered clients](media/screenshot-mcp.png)

### Dashboard

![OzBridge dashboard with analytics and failure triage](media/screenshot-dashboard.png)

---

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Connect your MCP client](#connect-your-mcp-client)
  - [How do I use Warp Oz in Claude Code?](#how-do-i-use-warp-oz-in-claude-code)
  - [How do I use Warp Oz in Cursor?](#how-do-i-use-warp-oz-in-cursor)
  - [How do I use Warp Oz in Codex CLI?](#how-do-i-use-warp-oz-in-codex-cli)
  - [How do I use Warp Oz in VS Code?](#how-do-i-use-warp-oz-in-vs-code)
- [Usage](#usage)
  - [Chat Participant (`@oz`)](#chat-participant-oz)
  - [Slash Commands](#slash-commands)
  - [Agent Mode — Language Model Tools](#agent-mode--language-model-tools)
- [Tools](#tools)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Development](#development)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [License](#license)

> **New to Warp or to VS Code extensions?** The
> [Quick Start guide](https://sena-labs.github.io/OzBridge/QUICK-START.html) is a
> step-by-step visual walkthrough — prerequisites, per-OS install, first run,
> every slash command, settings and troubleshooting — written for readers with
> no prior setup. Full documentation site: <https://sena-labs.github.io/OzBridge/>.

---

## Features

- **MCP bridge — Warp Oz for any client** — expose the Oz toolset as a Model Context Protocol server over HTTP+SSE so **Claude Code, Cursor and Codex** drive Oz through the same tools Copilot sees. Run it embedded in VS Code (opt-in) or fully standalone via [`@sena-labs/oz-mcp-server`](packages/oz-mcp-server). See [`docs/MCP.md`](docs/MCP.md).
- **`@oz` Chat Participant** — interact with Warp Oz agents from the VS Code chat panel.
- **Agent-Native Language Model Tools** — Copilot Agent mode can invoke Warp Oz directly, without typing `@oz`.
- **One-click model selection** — pick the Oz model from a QuickPick (`OzBridge: Select Model`), the `$(sparkle)` status-bar indicator, or `@oz /models <id>` — no hand-typing an id into settings. Agents switch it via the MCP tools `oz_list_models` / `oz_set_default_model`.
- **Warp sidebar + status bar** — Activity Bar view with Active Runs, History, Schedules, Environments, MCP Servers and Secrets, plus a `$(cloud) Warp: N active` indicator and a `$(sparkle) <model>` model indicator (click to switch).
- **Context variables & Warp handoff** — inline `#warp.env`, `#warp.profile`, `#warp.model`, `#oz.history` and `#oz.run/<id>` tokens expanded into any `/run` or `/cloud` prompt, plus a one-click handoff to an actual Warp terminal.
- **Per-workspace config** — optional `.warp/warp-bridge.yaml` committed to the repo overrides `ozBridge.*` settings for everyone who opens the project. Precedence: YAML > VS Code settings > defaults. Secrets like `mcpBearerToken` and platform-specific `ozPath` are deliberately excluded.
- **9 slash commands** covering the full agent workflow: `/run`, `/cloud`, `/status`, `/history`, `/schedule`, `/models`, `/mcp`, `/config`, `/init`.
- **IDE context injection** — automatically includes workspace path, active file, selection and diagnostics in every prompt.
- **Agent skill detection** — maps prompt keywords to the 7-agent pipeline (spec, design, implement, review, test, deploy, maintenance).
- **Cloud run polling** — exponential-backoff polling with real-time progress updates in the chat stream.
- **Robust JSON parser** — 5-level fallback for mixed text/JSON CLI output.
- **Configurable** — every setting is exposed via the VS Code Settings UI under `ozBridge.*`.
- **Minimal runtime footprint** — one bundled workspace package (`copilot-chat-toolkit`) plus the `vscode` API; no third-party network code. Production bundle ~160 KB.

## Requirements

- **VS Code** ≥ 1.96.0 (the `@oz` participant requires the stable Chat Participant API; LM Tools additionally require `vscode.lm.registerTool`).
- **[Warp Terminal](https://www.warp.dev/)** installed, with the `oz` CLI accessible in `PATH`.
- A **Warp account**, signed in via `oz login`.
- **GitHub Copilot Chat** extension (optional but required to actually invoke `@oz` or use Agent mode tools).

## Installation

### From a registry

Starting with `v0.9.0`, OzBridge is published to both registries on
every tagged release.

**VS Code Marketplace** (Stable / Insiders / Cursor with Microsoft
marketplace access):

```bash
code --install-extension sena-labs.ozbridge
```

**Open VSX** (VSCodium, Gitpod, Theia, Cursor with Open VSX mirror):

```bash
codium --install-extension sena-labs.ozbridge
# or, inside the editor GUI, search for "OzBridge" on open-vsx.org
```

Direct links:

- Marketplace — <https://marketplace.visualstudio.com/items?itemName=sena-labs.ozbridge>
- Open VSX — <https://open-vsx.org/extension/sena-labs/ozbridge>

### From VSIX (local)

**Option A — VS Code GUI (recommended):**

1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS).
2. Type **"Extensions: Install from VSIX…"**.
3. Select the `ozbridge.vsix` file.

**Option B — CLI:**

```bash
code --install-extension ozbridge.vsix
```

> **Note:** on Windows `code` may not be in your `PATH`. Use the full path or
> the GUI method above.

### From source

```bash
git clone https://github.com/sena-labs/OzBridge.git
cd OzBridge
npm install
npm run build
```

Then press `F5` in VS Code to launch the Extension Development Host with the
built extension loaded.

### Verify the installation

1. Open the Copilot Chat panel (`Ctrl+Shift+I` / `Cmd+Shift+I`).
2. Type `@oz /config` and submit.
3. The panel should show a table with the current configuration and the
   detected Oz CLI path. If the CLI is missing you will see an *"Install
   Warp"* action button that opens the download page.

## Connect your MCP client

OzBridge exposes the same six Oz tools to every MCP client. Start the bridge
first — either enable the embedded server in VS Code (`"ozBridge.mcpEnabled": true`,
then **OzBridge MCP: Start**) or run the standalone package:

```bash
npx -y @sena-labs/oz-mcp-server
```

Both listen on `http://127.0.0.1:3847/sse` by default. Set
`ozBridge.mcpBearerToken` to require an `Authorization: Bearer <token>` header;
omit the `headers` block below when auth is disabled.

### How do I use Warp Oz in Claude Code?

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "oz-bridge": {
      "type": "sse",
      "url": "http://127.0.0.1:3847/sse",
      "headers": { "Authorization": "Bearer my-secret" }
    }
  }
}
```

### How do I use Warp Oz in Cursor?

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "oz-bridge": {
      "url": "http://127.0.0.1:3847/sse",
      "headers": { "Authorization": "Bearer my-secret" }
    }
  }
}
```

### How do I use Warp Oz in Codex CLI?

Add to `~/.codex/config.toml`:

```toml
[[mcp.servers]]
name = "oz-bridge"
url = "http://127.0.0.1:3847/sse"
authorization = "Bearer my-secret"
```

### How do I use Warp Oz in VS Code?

No MCP wiring needed — install the extension and Oz is available immediately as
the `@oz` chat participant and as Language Model Tools that Copilot Agent mode
calls on its own. See [Usage](#usage).

Protocol details, endpoint reference and a raw-`curl` cheatsheet live in
[`docs/MCP.md`](docs/MCP.md).

## Usage

### Chat Participant (`@oz`)

Open the Copilot Chat panel and type `@oz` followed by your request:

```text
@oz fix the failing test in src/auth/login.ts
```

The extension injects an IDE context block (workspace path, active file,
selection, diagnostics) before the prompt and runs the Oz agent. Results
stream back as markdown with action buttons (e.g. *Retry*, *Open run*).

### Slash Commands

| Co