mcpField
O
OzBridge

OzBridge

Local
marketplace.visualstudio.comAI & Agents3Updated 3d ago

About OzBridge

OzBridge is an open-source MCP server and VS Code extension for running Warp Oz agents from compatible clients and editors. It offers a standalone server or VS Code integration, exposing Oz runs and model controls through six MCP tools over stdio or Streamable HTTP.

Key features

  1. 01Run Warp Oz agents from MCP clients
  2. 02Six tools for runs and model selection
  3. 03stdio and Streamable HTTP transports
  4. 04VS Code `@oz` chat participant
  5. 05Copilot Agent mode tool integration

Use cases

  1. 01Run a Warp Oz agent from Claude Code
  2. 02Connect Cursor or Codex to Oz
  3. 03Use Oz within VS Code Copilot Chat

MCP support

OzBridge exposes six tools for starting and inspecting Oz runs and managing model selection. MCP clients can launch the standalone server over stdio or connect to a Streamable HTTP endpoint; Warp and the `oz` CLI are required.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
"mcpServers": {
"OzBridge": {
"command": "npx",
"args": [
"-y",
"@sena-labs/oz-mcp-server"
]
}
}
}
Run commandnpx -y @sena-labs/oz-mcp-server

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@sena-labs/oz-mcp-server

Tools

6

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
promptstringYesNatural-language instruction for the agent, e.g. "add unit tests for src/auth.ts".
modelstringNoAI model id to use, from `oz_list_models` (e.g. `claude-4-8-opus-max`). Omit to use the configured default (`auto` lets Warp choose).
profilestringNoOz agent profile name (managed in the Warp app under Settings → AI → Profiles). Omit to use the default profile.
skillstringNoAgent skill id from the 7-stage pipeline (e.g. `5-test-agent`). Omit to let the CLI choose one based on the prompt.

Details

From the project README

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

Build VS Code License: MIT Listed on MCP ServerList OzBridge screenshot

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 Oz toolset over MCP (stdio or Streamable HTTP) 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 -->|"stdio / HTTP"| 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"]

Quick start

Prerequisites (every path): Warp installed, the oz CLI on your PATH (on Linux typically ~/.warp/bin/oz — see Troubleshooting), and oz login run once in a terminal. Check with oz --version. The npm server additionally needs Node.js ≥ 22.12.

Cursor / Windsurf / VSCodium (Open VSX) — use OzBridge over MCP. Add this to ~/.cursor/mcp.json (Cursor) or ~/.codeium/windsurf/mcp_config.json (Windsurf):

{ "mcpServers": { "oz": { "command": "npx", "args": ["-y", "@sena-labs/oz-mcp-server", "--stdio"] } } }

The @oz chat participant needs GitHub Copilot Chat and is VS Code-only, so MCP is the way to drive Oz from these editors.

VS Code + GitHub Copilot Chat — install the extension (code --install-extension sena-labs.ozbridge), run oz login once, then in the Copilot Chat panel type:

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

Claude Code / Codex / any MCP client — the client spawns the server over stdio, so no long-running terminal is needed:

claude mcp add oz -- npx -y @sena-labs/oz-mcp-server --stdio
# ~/.codex/config.toml
[mcp_servers.oz]
command = "npx"
args = ["-y", "@sena-labs/oz-mcp-server", "--stdio"]

Other clients (e.g. Claude Desktop) take the same JSON as Cursor above. More options, including HTTP, in Connect your MCP client.

Feature gallery

Runs & Resources

OzBridge sidebar with active runs, history and schedules

Warp Drive

Warp Drive prompt and skills preview inside VS Code

MCP bridge

Embedded MCP bridge status with registered clients

Dashboard

OzBridge dashboard with analytics and failure triage


Table of Contents

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 (stdio or Streamable HTTP) so Claude Code, Cursor and Codex drive Oz through six MCP tools that mirror the Language Model 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.101.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:

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 MCP tools (oz_agent_run, oz_agent_run_cloud, oz_run_get, oz_run_list, oz_list_models, oz_set_default_model) to every MCP client. The simplest setup is stdio: the client spawns the standalone server itself, so there is nothing to keep running in a terminal.

Prefer a long-running HTTP server instead? Either enable the embedded server in VS Code ("ozBridge.mcpEnabled": true, then OzBridge: Start MCP server) or run npx -y @sena-labs/oz-mcp-server. Both listen on http://127.0.0.1:3847/mcp (Streamable HTTP) by default; the legacy /sse endpoint is deprecated. No token is required on loopback by default.

If you set ozBridge.mcpBearerToken (or --token / OZ_MCP_TOKEN for the standalone server), add an Authorization: Bearer <token> header to the URL-based configs below — e.g. "headers": { "Authorization": "Bearer <token>" } in JSON, or http_headers = { "Authorization" = "Bearer <token>" } for Codex.

How do I use Warp Oz in Claude Code?
claude mcp add oz -- npx -y @sena-labs/oz-mcp-server --stdio

Or, against a running HTTP server:

claude mcp add --transport http oz http://127.0.0.1:3847/mcp
How do I use Warp Oz in Cursor?

Add to ~/.cursor/mcp.json (Windsurf: ~/.codeium/windsurf/mcp_config.json; Claude Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "oz": {
      "command": "npx",
      "args": ["-y", "@sena-labs/oz-mcp-server", "--stdio"]
    }
  }
}

Or, against a running HTTP server: { "mcpServers": { "oz": { "url": "http://127.0.0.1:3847/mcp" } } }.

How do I use Warp Oz in Codex CLI?

Add to ~/.codex/config.toml:

[mcp_servers.oz]
command = "npx"
args = ["-y", "@sena-labs/oz-mcp-server", "--stdio"]

Or, against a running HTTP server:

[mcp_servers.oz]
url = "http://127.0.0.1:3847/mcp"
How do I use Warp Oz in VS Code?

No MCP wiring needed — install the extension (with GitHub Copilot Chat) and Oz is available immediately as the @oz chat participant and as four Language Model Tools that Copilot Agent mode calls on its own (oz_run_local, oz_run_cloud, oz_get_run, oz_list_runs). 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
CommandDescriptionExample
/runRun an Oz agent locally in the workspace@oz /run refactor this function
/cloudRun an Oz agent in the cloud (credits)@oz /cloud deploy to staging
/statusShow active runs (QUEUED / INPROGRESS) or detail by ID@oz /status or @oz /status <runId>
/historyShow completed runs (SUCCEEDED / FAILED) with optional filter@oz /history, @oz /history succeeded, @oz /history <runId>
/scheduleCreate and manage scheduled runs@oz /schedule create daily "0 9 * * *" "Run linting"
/modelsList available AI models, or set the default with /models <id>@oz /models · @oz /models claude-4-8-opus-max
/mcpList configured MCP servers@oz /mcp
/configShow current configuration@oz /config
/initScaffold 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.

ToolReferenceBehaviour
oz_run_local#ozRunLocalRuns a local Oz agent in the current workspace. Injects IDE context by default (includeIdeContext: false to opt out).
oz_run_cloud#ozRunCloudLaunches a cloud Oz agent. Shows a confirmation dialog before consuming Warp credits. Polls to terminal state by default (wait: false returns immediately with the run id).
oz_get_run#ozGetRunFetches status + output of a specific run by id. Read-only.
oz_list_runs#ozListRunsLists recent runs with a status filter (all, active, completed, or a raw OzRunStatus) and optional limit. Read-only.

Examples:

# Agent mode picks oz_run_local automatically:
Run the unit tests locally via Oz.

# Explicit tool reference (prefix with #):
Run this refactor on cloud: #ozRunCloud refactor src/auth to hexagonal architecture

# Query a previous run:
Check run #ozGetRun for run id run-abc123.

Each tool is declared in package.json under contributes.languageModelTools with a strict JSON inputSchema, so the model receives accurate type hints at tool-call time. Cloud tools always show a confirmation dialog before running, regardless of the user's Bypass Approvals preference.

Sidebar & Status Bar

The extension contributes a dedicated Activity Bar view (OzBridge → Runs & Resources) with five collapsible categories:

  • Active Runs — QUEUED + INPROGRESS (live-refreshed every 10 s).
  • History — SUCCEEDED + FAILED, capped at 20 entries per refresh.
  • Schedules — cron jobs from oz schedule list.
  • Environments — cloud environments from oz environment list.
  • MCP Servers — MCP integrations from oz mcp list.

Right-click menu actions:

  • Copy ID on any run / schedule / environment / MCP node.
  • Open in Browser on a run node (opens app.warp.dev/agents/<id>).
  • Pause / Resume / Delete on schedule nodes (delete asks for confirmation).

A status bar item ($(cloud) Warp: N active, right-aligned) mirrors the Active Runs count in real time and switches to warningBackground at 1–2 active runs or errorBackground at 3+. Clicking the indicator focuses the OzBridge sidebar.

Prompt variables

Inside any @oz /run … or @oz /cloud … prompt you can embed a small set of tokens that the extension resolves locally before sending the prompt to the Oz CLI. Unknown tokens (e.g. #some.other) are passed through unchanged.

TokenExpands to
#warp.envValue of ozBridge.defaultEnvironment (or (no default environment) when empty).
#warp.profileValue of ozBridge.defaultProfile.
#warp.modelValue of ozBridge.defaultModel.
#oz.historyMarkdown table of the last 10 runs from oz run list.
#oz.run/<id>Fenced JSON payload from oz run get <id> (truncated at 2 000 chars).

Example:

@oz /cloud deploy branch #warp.env profile=#warp.profile given the last runs:\n#oz.history
Hand off to Warp

Two commands open a real Warp terminal (Warp ≥ 0.2024.x) via the warp://action/new_tab URI scheme:

  • Warp: Hand off to Warp terminal… (Command Palette) — asks for a prompt and runs oz agent run --prompt "<prompt>" in a new Warp tab.
  • Warp: Hand off run to Warp terminal (sidebar context menu on any run node) — runs oz run get <runId> so you can drill into the run directly in the terminal.

If the warp:// URL handler is not registered on the current platform, the extension shows a modal with the exact command to copy into any shell as a fallback.

Tools

Six MCP tools are exposed over the bridge. Copilot Agent mode invokes them natively in VS Code; Claude Code, Cursor and Codex reach the same set through the MCP server, embedded or standalone.

ToolPurpose
oz_agent_runRun oz agent run locally with a prompt. Returns the full run payload.
oz_agent_run_cloudLaunch a cloud run. Consumes Warp credits.
oz_run_getFetch a run's status and output by id. Read-only.
oz_run_listList recent runs; filter by all / active / completed / raw status, plus a numeric limit.
oz_list_modelsList the AI model ids available to the account and report the current default. Read-only.
oz_set_default_modelSet the default Oz model by writing defaultModel into the workspace .warp/warp-bridge.yaml.

The full JSON inputSchema for each tool is emitted verbatim by tools/list. See docs/MCP.md for protocol details, a raw-curl cheatsheet and the endpoint reference.

Configuration

All settings live under ozBridge.* in VS Code Settings (File → Preferences → Settings) or can be edited in settings.json.

Per-workspace overrides (.warp/warp-bridge.yaml)

Commit a .warp/warp-bridge.yaml at the root of your repository and OzBridge will merge its values on top of the VS Code settings for everyone who opens the project. The file is reloaded automatically when it is created, changed or deleted — no VS Code reload required.

# .warp/warp-bridge.yaml — committed to Git, shared across the team.
defaultProfile: team-shared
defaultEnvironment: staging
timeoutMs: 600000
mcpEnabled: true
mcpPort: 3900
mcpBindAddress: "127.0.0.1"

Supported keys: defaultModel, defaultProfile, defaultEnvironment, timeoutMs, maxOutputChars, cloudPollingIntervalMs, cloudPollingTimeoutMs, mcpEnabled, mcpPort, mcpBindAddress.

Deliberately excluded:

  • ozPath — platform-specific, must live in user settings.
  • mcpBearerToken — secret, should never be committed.

Unknown keys and keys with the wrong type are logged to the OzBridge output channel and ignored, so a typo never breaks the extension.

SettingDefaultDescription
ozBridge.ozPathozPath to the Oz CLI executable
ozBridge.defaultModelautoDefault AI model for agent runs
ozBridge.defaultProfileDefaultDefault Oz agent profile
ozBridge.defaultEnvironment(empty)Default cloud environment name
ozBridge.timeoutMs300000Timeout for local agent runs (5 min)
ozBridge.cloudPollingIntervalMs5000Initial cloud polling interval
ozBridge.cloudPollingTimeoutMs1800000Max cloud polling duration (30 min)
ozBridge.maxOutputChars15000Max characters shown before truncation

Architecture

The extension follows a layered architecture with dependency injection at the composition root (src/extension.ts). Each layer has a single responsibility:

LayerFilesResponsibility
Typestypes/index.tsInterfaces, error classes, config shape, constants
Parsersparsers/jsonParser.ts, parsers/outputFormatter.tsJSON parsing (5-level), chat stream rendering
Servicesservices/ozCliService.ts, configManager.ts, contextCollector.ts, runPoller.ts, logger.tsCLI execution, settings, IDE context, polling, logging
Commandscommands/router.ts + 9 command filesSlash-command dispatch and business logic
Toolstools/*VS Code Language Model Tool implementations
Participantparticipant/handler.ts, followups.tsChat Participant registration and follow-ups
Folder structure
src/
├── types/index.ts          — Contracts: interfaces, errors, config
├── parsers/
│   ├── jsonParser.ts       — Robust 5-level JSON parser
│   └── outputFormatter.ts  — Chat stream formatting & truncation
├── services/
│   ├── configManager.ts    — VS Code settings wrapper with caching
│   ├── contextCollector.ts — IDE context gathering
│   ├── ozCliService.ts     — Core CLI execution via child_process
│   ├── runPoller.ts        — Async polling with exponential backoff
│   └── logger.ts           — Centralised extension logging
├── commands/
│   ├── router.ts           — Slash-command dispatch
│   └── {9 command files}   — One handler per /command
├── tools/
│   ├── baseTool.ts         — Shared helpers (textResult, errorResult)
│   ├── runLocalTool.ts     — oz_run_local
│   ├── runCloudTool.ts     — oz_run_cloud (with confirmation)
│   ├── getRunTool.ts       — oz_get_run
│   ├── listRunsTool.ts     — oz_list_runs
│   └── index.ts            — registerWarpTools()
├── participant/
│   ├── handler.ts          — Chat Participant registration
│   └── followups.ts        — Contextual follow-up suggestions
└── extension.ts            — Entry point: compose & register
Data flow
  1. User types @oz /run implement auth in Copilot Chat.
  2. VS Code dispatches the request to the @oz Chat Participant.
  3. CommandRouter maps /run to the createRunCommand handler.
  4. Handler calls ContextCollector.gather() for IDE context.
  5. Handler calls OzCliService.agentRun(), which spawns oz as a child process.
  6. JSON output is parsed via the 5-level jsonParser.
  7. OutputFormatter renders the result as markdown in the chat stream.

Development

# Install dependencies
npm install

# Type-check
npm run compile

# Build (esbuild)
npm run build

# Run tests
npm test

# Tests with coverage report
npm run test:coverage

# Watch mode (dev)
npm run watch

# Clean build artifacts
npm run clean

# Package VSIX for distribution
npm run package
Test Suite
  • 1,400+ tests across 100+ files
  • High test-to-code ratio
  • Framework: Vitest v4.0.18

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting changes.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Make sure all tests pass before submitting:

npm run compile && npm test

See also the Code of Conduct and the Security Policy.

Troubleshooting

oz command not found

Ensure Warp is installed and the oz CLI is available in your PATH.

OSTypical path
macOS/Applications/Warp.app/Contents/MacOS/oz
Linux~/.warp/bin/oz
WindowsC:\Users\<user>\AppData\Local\Programs\Warp\bin\oz.cmd
# Verify oz is available
which oz   # macOS / Linux
where oz   # Windows (PowerShell)

If oz is in PATH but the extension still reports it as unavailable, type @oz /config in the Copilot Chat panel — this triggers extension activation and the first CLI check. You can also set an explicit path in Settings → Extensions → OzBridge → Oz Path.

Authentication errors

Run oz login in a terminal to re-authenticate, or use the Login Warp button that appears in the error message inside the chat panel.

Timeout errors

Increase the timeout in Settings → Extensions → OzBridge → Timeout (ms). The default is 300 000 ms (5 minutes). For large-scale agent runs consider raising it to 600 000 ms. Cloud runs have a separate, longer timeout controlled by cloudPollingTimeoutMs.

Extension not activating

The extension activates only when the @oz participant is invoked in Copilot Chat (or when Copilot Agent mode calls one of the LM Tools). To activate it manually:

  1. Open the Chat panel (Ctrl+Shift+I).
  2. Type @oz followed by any command (e.g. @oz /config).

Make sure you have VS Code ≥ 1.101.0 and the GitHub Copilot Chat extension installed and signed in.

FAQ

Q: Does OzBridge work with Cursor, Claude Code and Codex? A: Yes. All three are MCP clients — point them at the bridge and they get the six OzBridge MCP tools (Copilot Agent mode instead gets four Language Model Tools with different names). Copy-paste configs are in Connect your MCP client.

Q: Do I need VS Code at all? A: No. The standalone @sena-labs/oz-mcp-server runs via npx with no editor involved; VS Code is only required for the @oz chat participant and the sidebar.

Q: What is the difference between a local run and a cloud run? A: A local run spawns the oz CLI (oz agent run) in your workspace with full access to your files; it still uses Warp's AI, so it may count against your Warp plan's AI usage. A cloud run executes on Warp's infrastructure, consumes Warp cloud credits, and runs detached from your machine. Both are reachable from every client.

Q: Does this extension require a Warp subscription? A: You need a Warp account (oz login). Local agent runs use your plan's AI usage allowance; cloud runs consume Warp cloud credits and may require a paid plan depending on usage. Check your account at app.warp.dev.

Q: Can I use a custom model? A: Yes — set ozBridge.defaultModel in VS Code settings or pass it inline with /run --model gpt-4o. To see all available models, use /models.

Q: Which operating systems are supported? A: macOS, Linux and Windows are all natively supported. The extension works on any platform where VS Code and the Oz CLI can run. On Windows the extension automatically handles .cmd wrappers.

Q: How do I report a bug? A: Open an issue using the bug report template. Include your OS, VS Code version, extension version and steps to reproduce.

Q: Can I use this extension with GitHub Copilot Chat? A: Yes — this extension is a VS Code Chat Participant. It appears as @oz in the Copilot Chat panel. You need GitHub Copilot Chat installed and active.

Q: How do I update the Oz CLI? A: The Oz CLI ships with Warp. Updating Warp to the latest version automatically updates the Oz CLI.

  • macOS: brew upgrade warp
  • Windows/Linux: download the latest installer from warp.dev.

Q: What happens if the agent run times out? A: The extension shows a timeout error with the configured limit in seconds. You can increase the timeout via ozBridge.timeoutMs in settings. Cloud runs have a separate, longer timeout controlled by cloudPollingTimeoutMs.

Q: Can I run multiple agents in parallel? A: Yes — each /run or /cloud command spawns an independent process. Multiple chat messages can trigger concurrent agent executions.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer

OzBridge is an independent project developed by Ivan Sena under the Sena Labs name. It is not affiliated with, endorsed by, sponsored by, or officially associated with Warp, Inc., Microsoft, GitHub, or Visual Studio Code.

Warp™ and Oz™ are trademarks of Warp, Inc.; other names may be trademarks of their respective owners. They are used here nominatively only to describe interoperability. OzBridge uses solely Warp's documented public interfaces (the oz CLI, the Model Context Protocol, and WARP_OUTPUT_FORMAT); it does not modify, reverse-engineer, or compete with Warp.

This extension is provided "as is", without warranty of any kind. Use it at your own risk. See DISCLAIMER.md for details.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.