OzBridge — Warp Oz for any IDE or agent, via MCP

What is OzBridge?

OzBridge is an open-source Model Context Protocol (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.

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 and point any MCP client at it.

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

Warp Drive

MCP bridge

Dashboard

---

Table of Contents

• Features
• Requirements
• Installation
• Connect your MCP client
  • How do I use Warp Oz in Claude Code?
  • How do I use Warp Oz in Cursor?
  • How do I use Warp Oz in Codex CLI?
  • How do I use Warp Oz in VS Code?
• Usage
  • Chat Participant (@oz)
  • Slash Commands
  • Agent Mode — Language Model Tools
• Tools
• Configuration
• Architecture
• Development
• Contributing
• Troubleshooting
• FAQ
• License

New to Warp or to VS Code extensions? The Quick Start guide 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. See 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 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):

code --install-extension sena-labs.ozbridge

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

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:

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

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:

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:

{
  "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:

{
  "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:

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

Protocol details, endpoint reference and a raw-curl cheatsheet live in docs/MCP.md.

Usage

Chat Participant (@oz)

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

@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

| Command | Description | Example | | --- | --- | --- | | /run | Run an Oz agent locally in the workspace | @oz /run refactor this function | | /cloud | Run an Oz agent in the cloud (credits) | @oz /cloud deploy to staging | | /status | Show active runs (QUEUED / INPROGRESS) or detail by ID | @oz /status or @oz /status <runId> | | /history | Show completed runs (SUCCEEDED / FAILED) with optional filter | @oz /history, @oz /history succeeded, @oz /history <runId> | | /schedule | Create and manage scheduled runs | @oz /schedule create daily "0 9 * * *" "Run linting" | | /models | List available AI models, or set the default with /models <id> | @oz /models · @oz /models claude-4-8-opus-max | | /mcp | List configured MCP servers | @oz /mcp | | /config | Show current configuration | @oz /config | | /init | Scaffold Warp Skills and Rules files | @oz /init |

/history filters

/history               — list all completed runs (SUCCEEDED + FAILED)
/history succeeded     — only SUCCEEDED runs
/history failed        — only FAILED runs
/history <runId>       — show details for a specific run

/schedule sub-commands

/schedule list                                    — List all schedules
/schedule create <name> "<cron>" "<prompt>"       — Create a schedule
/schedule pause <id>                              — Pause a schedule
/schedule unpause <id>                            — Resume a schedule
/schedule delete <id>                             — Delete a schedule

Agent Mode — Language Model Tools

In GitHub Copilot Chat Agent mode, Copilot can call Warp Oz directly through registered Language Model Tools — you don't need to prefix your request with @oz. Copilot selects the right tool based on the prompt and its declared modelDescription.

| Tool | Reference | Behaviour | | --- | --- | --- | | oz_run_local | #ozRunLocal | Runs a local Oz agent in the current workspace. In