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

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.

OzBridge brings Warp Oz to any IDE or agent that speaks the Model Context Protocol (MCP). 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.

Feature gallery

Runs & Resources

Warp Drive

MCP bridge

Dashboard

---

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • Chat Participant (@oz)
  • Slash Commands
  • Agent Mode — Language Model Tools
• Configuration
• Architecture
• Development
• Contributing
• Troubleshooting
• FAQ
• License

---

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.

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. Injects IDE context by default (includeIdeContext: false to opt out).
oz_run_cloud	#ozRunCloud	Launches 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	#ozGetRun	Fetches status + output of a specific run by id. Read-only.
oz_list_runs	#ozListRuns	Lists 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.

Token	Expands to
#warp.env	Value of ozBridge.defaultEnvironment (or (no default environment) when empty).
#warp.profile	Value of ozBridge.defaultProfile.
#warp.model	Value of ozBridge.defaultModel.
#oz.history	Markdown 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.

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 Warp Bridge 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.

Setting	Default	Description
ozBridge.ozPath	oz	Path to the Oz CLI executable
ozBridge.defaultModel	auto	Default AI model for agent runs
ozBridge.defaultProfile	Default	Default Oz agent profile
ozBridge.defaultEnvironment	(empty)	Default cloud environment name
ozBridge.timeoutMs	300000	Timeout for local agent runs (5 min)
ozBridge.cloudPollingIntervalMs	5000	Initial cloud polling interval
ozBridge.cloudPollingTimeoutMs	1800000	Max cloud polling duration (30 min)
ozBridge.maxOutputChars	15000	Max 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:

Layer	Files	Responsibility
Types	types/index.ts	Interfaces, error classes, config shape, constants
Parsers	parsers/jsonParser.ts, parsers/outputFormatter.ts	JSON parsing (5-level), chat stream rendering
Services	services/ozCliService.ts, configManager.ts, contextCollector.ts, runPoller.ts, logger.ts	CLI execution, settings, IDE context, polling, logging
Commands	commands/router.ts + 9 command files	Slash-command dispatch and business logic
Tools	tools/*	VS Code Language Model Tool implementations
Participant	participant/handler.ts, followups.ts	Chat 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.

OS	Typical path
macOS	/Applications/Warp.app/Contents/MacOS/oz
Linux	~/.warp/bin/oz
Windows	C:\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.96.0 and the GitHub Copilot Chat extension installed and signed in.

FAQ

Q: Does this extension require a Warp subscription? A: A free Warp account is sufficient for local agent runs. Cloud runs 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.