OzBridge

Starting withv0.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

Note:on Windowscodemay not be in yourPATH. Use the full path or the GUI method above.

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

Then pressF5in VS Code to launch the Extension Development Host with the built extension loaded.
- Open the Copilot Chat panel (Ctrl+Shift+I/Cmd+Shift+I).
- Type@oz /configand submit.
- 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.

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, thenOzBridge MCP: Start) or run the standalone package:

Both listen onhttp://127.0.0.1:3847/sseby default. SetozBridge.mcpBearerTokento require anAuthorization: Bearer <token>header; omit theheadersblock below when auth is disabled.

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

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

Open the Copilot Chat panel and type@ozfollowed 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).

/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 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

InGitHub 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 declaredmodelDescription.

# 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 inpackage.jsonundercontributes.languageModelToolswith a strict JSONinputSchema, so the model receives accurate type hints at tool-call time. Cloud tools always show a confirmation dialog before running, regardless of the user'sBypass Approvalspreference.

The extension contributes a dedicatedActivity 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 fromoz schedule list.
- Environments— cloud environments fromoz environment list.
- MCP Servers— MCP integrations fromoz mcp list.

- Copy IDon any run / schedule / environment / MCP node.
- Open in Browseron a run node (opensapp.warp.dev/agents/<id>).
- Pause / Resume / Deleteon schedule nodes (delete asks for confirmation).

Astatus bar item($(cloud) Warp: N active, right-aligned) mirrors the Active Runs count in real time and switches towarningBackgroundat 1–2 active runs orerrorBackgroundat 3+. Clicking the indicator focuses the OzBridge sidebar.

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

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

Two commands open a real Warp terminal (Warp ≥ 0.2024.x) via thewarp://action/new_tabURI scheme:

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

If thewarp://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.

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.

All settings live underozBridge.in VS Code Settings (File → Preferences → Settings) or can be edited insettings.json.

# .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"

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

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

# 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

Runoz loginin a terminal to re-authenticate, or use theLogin Warp*button that appears in the error message inside the chat panel.

Increase the timeout inSettings → 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 bycloudPollingTimeoutMs.

The extension activates only when the@ozparticipant is invoked in Copilot Chat (or when Copilot Agent mode calls one of the LM Tools). To activate it manually:
- Open the Chat panel (Ctrl+Shift+I).
- Type@ozfollowed by any command (e.g.@oz /config).

Make sure you haveVS Code ≥ 1.96.0and theGitHub Copilot Chatextension installed and signed in.

Q: What is the difference between a local run and a cloud run?A: A local run spawns theozCLI in your workspace — no Warp credits, full access to your files. A cloud run executes on Warp's infrastructure, consumes credits, and runs detached from your machine. Both are reachable from every client.

Q: Can I use a custom model?A: Yes — setozBridge.defaultModelin 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.cmdwrappers.