### Install Dependencies and Build Project

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Standard commands for installing dependencies, type-checking, building the project using esbuild, and cleaning build artifacts.

```bash
npm install
npm run compile
npm run build
npm run clean
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Install all necessary Node.js dependencies for the project. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Install and run oz-mcp-server globally

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

Install the package globally for convenient access to the server command. Use --help to see all available options.

```bash
npm install -g @sena-labs/oz-mcp-server
oz-mcp-server --help
```

--------------------------------

### Install and Build OzBridge from Source

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Clone the OzBridge repository, install dependencies, and build the extension from source. Press F5 in VS Code to launch the Extension Development Host with the built extension.

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

--------------------------------

### Install OzBridge from Local VSIX using CLI

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Install OzBridge from a local .vsix file using the command line. Ensure 'code' is in your PATH or use the full path to the executable. The GUI method is recommended for Windows users.

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

--------------------------------

### Example Prompt with Variables

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Demonstrates embedding prompt variables like environment, profile, and run history into an Oz prompt.

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

--------------------------------

### Install OzBridge from Open VSX

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Install OzBridge using the `codium` command if you are using VSCodium, Gitpod, Theia, or Cursor with Open VSX mirror. Alternatively, search for 'OzBridge' on open-vsx.org within the editor.

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

--------------------------------

### Install OzBridge VS Code Extension

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Use this command to install the OzBridge extension directly into VS Code.

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

--------------------------------

### Run oz-mcp-server with custom port and token

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

Start the server on a specific port and with a custom bearer token for authentication.

```bash
npx @sena-labs/oz-mcp-server --port 3847 --token my-secret
```

--------------------------------

### Run Development Watch Mode

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Starts the development server in watch mode for continuous development.

```bash
npm run watch
```

--------------------------------

### Verify Warp CLI Installation

Source: https://github.com/sena-labs/ozbridge/blob/main/media/walkthrough/install-cli.md

After installing Warp, open a new terminal and run this command to confirm the `oz` executable is accessible in your system's PATH.

```bash
oz --version
```

--------------------------------

### Run Oz MCP Server with Environment Variables (Bash)

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

This snippet demonstrates how to start the Oz MCP Server using environment variables to configure the Oz path, listening port, token, and to run the server using npx.

```bash
OZ_PATH=/usr/local/bin/oz \
OZ_MCP_PORT=3847 \
OZ_MCP_TOKEN=my-secret \
npx @sena-labs/oz-mcp-server
```

--------------------------------

### Run oz-mcp-server with npx

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

Execute the server directly using npx without a prior installation. It defaults to binding on 127.0.0.1:3847.

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

--------------------------------

### Conventional Commits Type Examples

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Examples of valid commit types and scopes. Used for categorizing changes like features, fixes, and CI updates.

```text
feat(commands): add /logs slash command
```

```text
fix(parser): handle empty JSON arrays correctly
```

```text
ci: add bundle-budget workflow (v0.9 deliverable N)
```

--------------------------------

### Per-Workspace Configuration

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Example of a `.warp/warp-bridge.yaml` file for per-workspace configuration overrides. This file is automatically reloaded when changed.

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

--------------------------------

### MCP Server Health Response Example

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

A typical response from the `/health` endpoint, detailing the server's status and capabilities.

```json
{
  "ok": true,
  "name": "OzBridge",
  "version": "1.0.0",
  "tools": 6,
  "sessions": 2
}
```

--------------------------------

### Ozbridge Raw Protocol: Message Response Format

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Example of a message response received on the SSE connection for a tool invocation.

```text
event: message
data: {"jsonrpc":"2.0","id":2,"result":{"filter":"completed","count":5,"items":[…]}}
```

--------------------------------

### Update Oz CLI on Windows/Linux

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Download the latest installer from warp.dev to update the Oz CLI on Windows and Linux systems. This method is for non-macOS platforms.

```bash
download the latest installer from [warp.dev](https://www.warp.dev/).
```

--------------------------------

### OzBridge MCP Server Listening Log

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

This log line indicates that the MCP server has started successfully and is listening on the specified address and port. It also shows the number of available tools.

```log
MCP server listening on http://127.0.0.1:3847/sse (6 tools)
```

--------------------------------

### Import Core Copilot Chat Toolkit Modules

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/copilot-chat-toolkit/README.md

Imports essential modules from the copilot-chat-toolkit for building VS Code Copilot Chat extensions. Ensure you have VS Code ^1.96.0 and Node.js >=20 installed.

```typescript
import {
  CliError,
  CliErrorKind,
  ContextCollector,
  BaseConfigManager,
  CommandRouter,
  FollowupProvider,
  registerChatParticipant,
  parse,
  detectSkill,
  initLogger,
} from 'copilot-chat-toolkit';
```

--------------------------------

### Quick Health Check for Oz MCP Server

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

Use this command to perform a quick health check on the Oz MCP Server. It sends a GET request to the /health endpoint.

```bash
curl http://127.0.0.1:3847/health
```

--------------------------------

### Publishing MCP Server to Registry

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Command to log in to the MCP publisher and publish the server configuration. This step follows the creation and validation of the 'server.json' file.

```bash
mcp-publisher login github && mcp-publisher publish
```

--------------------------------

### Check Bundle Budget Locally

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Before submitting a Pull Request, verify that the 'dist/extension.js' bundle size does not exceed the 145 KB limit. This command helps confirm compliance locally.

```bash
npm run build
# On PowerShell:
(Get-Item dist/extension.js).Length
# On bash:
wc -c dist/extension.js
```

--------------------------------

### Publishing @sena-labs/oz-mcp-server to npm

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Commands to log in, build, and publish the npm package. Ensure you are logged in with an account that has publish rights for the '@sena-labs' scope. The '--access public' flag is mandatory for scoped packages.

```bash
cd packages/oz-mcp-server
npm whoami                 # 401 ⇒ not logged in
npm login                  # user with publish rights on @sena-labs
npm run build              # rebuild dist/server.js (1.2.0)
npm pack --dry-run         # expect README.md + dist/server.js + package.json
npm publish --access public   # --access public is REQUIRED for scoped pkgs
```

--------------------------------

### Build Extension Bundle

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Builds the extension bundle using esbuild, producing 'dist/extension.js'.

```bash
npm run build
```

--------------------------------

### Build Copilot Chat Toolkit Package

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Builds the 'copilot-chat-toolkit' workspace package specifically. This is a prerequisite if its 'dist/' directory is missing.

```bash
npm run build --workspace=copilot-chat-toolkit
```

--------------------------------

### Run Tests and Watch Mode

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Commands for executing the test suite, generating coverage reports, and running the project in watch mode for development.

```bash
npm test
npm run test:coverage
npm run watch
```

--------------------------------

### List Tools

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Lists available tools on the OzBridge MCP server for a given session ID.

```APIDOC
## List Tools

2. In another shell, list tools on the same sessionId.

```bash
curl -X POST 'http://127.0.0.1:3847/messages?sessionId=<uuid>'
  -H 'Content-Type: application/json'
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
```

--------------------------------

### Configure Cursor for Ozbridge

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Add this configuration to your `~/.cursor/mcp.json` file to connect Cursor to the Ozbridge SSE server.

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

--------------------------------

### Clone OzBridge Repository

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Clone your forked repository locally to begin development. Ensure you are in the cloned directory for subsequent commands.

```bash
git clone https://github.com/<your-username>/OzBridge.git
cd OzBridge
```

--------------------------------

### MCP Server Configuration (server.json)

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Schema-valid server configuration file for the MCP registry. The 'name' field must follow the reverse-DNS format (e.g., 'io.github.sena-labs/...'), not the npm scope. Ensure the 'version' matches the 'package.json' at the time of submission.

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.sena-labs/oz-mcp-server",
  "description": "Standalone MCP server that brings Warp(TM) Oz(TM) agents to Claude Code, Cursor, Codex, and any MCP client — no VS Code required.",
  "version": "1.2.0",
  "repository": {
    "url": "https://github.com/sena-labs/OzBridge",
    "source": "github",
    "subfolder": "packages/oz-mcp-server"
  },
  "websiteUrl": "https://github.com/sena-labs/OzBridge",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@sena-labs/oz-mcp-server",
      "version": "1.2.0",
      "transport": { "type": "stdio" },
      "runtimeHint": "npx"
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "disclaimer": "OzBridge is an independent project and is not affiliated with, endorsed by, or sponsored by Warp.",
      "keywords": ["mcp", "warp", "oz", "agent", "claude-code", "cursor", "codex"],
      "prerequisites": "Requires Warp(TM) installed with the oz CLI on PATH and a Warp account (a free account is sufficient for local runs).",
      "tools": ["oz_agent_run", "oz_agent_run_cloud", "oz_run_get", "oz_run_list", "oz_list_models", "oz_set_default_model"]
    }
  }
}
```

--------------------------------

### Sync Main and Create Branch

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Sync the local main branch with the remote and create a new feature branch for development.

```bash
git checkout main && git pull
git checkout -b feat/<milestone>-<slug>
```

--------------------------------

### Ozbridge Raw Protocol: List Tools

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

In a separate shell, list available tools on the Ozbridge SSE stream using a specific sessionId obtained from the initial stream.

```bash
# 2. In another shell, list tools on the same sessionId.
curl -X POST 'http://127.0.0.1:3847/messages?sessionId=<uuid>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

--------------------------------

### Exposed Tools

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

OzBridge exposes several tools for interacting with AI models and managing runs.

```APIDOC
## Tools Exposed

| Tool             | Purpose                                                                                                |
|------------------|--------------------------------------------------------------------------------------------------------|
| `oz_agent_run`   | Run `oz agent run` locally with a prompt. Returns the full run payload.                                |
| `oz_agent_run_cloud` | Launch a cloud run. **Consumes Warp credits.**                                                         |
| `oz_run_get`     | Fetch a run's status and output by id. Read-only.                                                      |
| `oz_run_list`    | List recent runs; supports `all` / `active` / `completed` / raw status filters plus a numeric `limit`. |
| `oz_list_models` | List the AI model ids available to the account (`oz model list`) and report the current default. Read-only. |
| `oz_set_default_model` | Set the default Oz model for every OzBridge surface by writing `defaultModel` into the workspace `.warp/warp-bridge.yaml`. Validated against `oz model list`. |

The JSON schemas for the `inputSchema` of each tool are emitted verbatim by `tools/list`, so clients can route arguments from their own prompts automatically.
```

--------------------------------

### Edit GitHub Repository Metadata

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Use the GitHub CLI to update the repository's description, homepage URL, and add relevant topics. Ensure the description is a verbatim disclaimer and the homepage points to the VS Marketplace listing.

```bash
gh repo edit sena-labs/OzBridge \
  --description "Bring Warp™ Oz™ to any IDE or agent via MCP — plus native @oz in VS Code Copilot Chat. OzBridge is an independent project and is not affiliated with, endorsed by, or sponsored by Warp." \
  --homepage "https://marketplace.visualstudio.com/items?itemName=sena-labs.ozbridge" \
  --add-topic warp,oz,mcp,model-context-protocol,vscode-extension,copilot,copilot-chat,claude-code,cursor,codex,ai-agents,llm-tools
```

--------------------------------

### Check Bundle Size

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Checks the file size of the built extension bundle in bytes.

```bash
wc -c dist/extension.js
```

--------------------------------

### Register Claude MCP Server via CLI

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

Use the `claude mcp add` command to register the OzBridge MCP server from the command line. This is an alternative to editing `~/.claude.json`.

```bash
claude mcp add --transport sse oz-bridge http://127.0.0.1:3847/sse \
  --header "Authorization: Bearer my-secret"
```

--------------------------------

### Configure Codex CLI for Ozbridge

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Add this configuration to your `~/.codex/config.toml` file to connect the Codex CLI to the Ozbridge SSE server.

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

--------------------------------

### Local Agent Execution Flow

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/DESIGN.md

Diagram illustrating the sequence of operations for running a local agent command, from user input to output formatting.

```mermaid
sequenceDiagram
    actor U as Utente
    participant CP as @oz ChatParticipant
    participant CH as CommandHandler
    participant CTX as ContextCollector
    participant CFG as ConfigManager
    participant CLI as OzCliService
    participant OZ as oz CLI (child_process)
    participant OUT as OutputFormatter

    U->>CP: @oz /run "fix linting errors"
    CP->>CH: route(command="/run", prompt)
    CH->>CTX: gather(activeEditor, selection, diagnostics)
    CTX-->>CH: contextPayload
    CH->>CFG: getConfig()
    CFG-->>CH: {model, profile, timeout}
    CH->>OUT: stream.progress("Avvio agente locale...")
    CH->>CLI: agentRun({prompt, context, model, profile, cwd})
    CLI->>OZ: spawn("oz", ["agent","run","-p","...","--output-format","json"])
    OZ-->>CLI: stdout JSON chunks + exit code
    CLI-->>CH: OzRunResult {status, output, runId}

    alt status === "SUCCEEDED"
        CH->>OUT: stream.markdown(formattedOutput)
        CH->>OUT: stream.button("Apri in Warp", openUrl)
    else status === "FAILED"
        CH->>OUT: stream.markdown("❌ Errore: ...")
    end

    OUT-->>U: Risposta renderizzata in chat
```

--------------------------------

### Run Oz MCP Server with Environment Variables (PowerShell)

Source: https://github.com/sena-labs/ozbridge/blob/main/packages/oz-mcp-server/README.md

This snippet shows how to set environment variables for the Oz MCP Server token and then run the server using npx in PowerShell on Windows.

```powershell
$env:OZ_MCP_TOKEN = "my-secret"; npx @sena-labs/oz-mcp-server
```

--------------------------------

### Test with Coverage

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Runs tests and generates a code coverage report.

```bash
npm run test:coverage
```

--------------------------------

### Type-check (lint) Project

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Runs the type-checking and linting process for the project.

```bash
npm run compile
```

--------------------------------

### VS Code Marketplace Short Description

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

The short description for the VS Code Marketplace listing. It is already live in package.nls.json and includes compliance notes.

```json
Bring Warp™ Oz™ to any IDE or agent via MCP — plus native @oz in VS Code Copilot Chat. Independent project, not affiliated with, endorsed by, or sponsored by Warp.
```

--------------------------------

### Run Unit Tests

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Executes unit tests using Vitest. The '-- --run' flag ensures tests run serially.

```bash
npm test -- --run
```

--------------------------------

### Configure Cursor for OzBridge

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Add this configuration to your `~/.cursor/mcp.json` file to enable Cursor to connect to the OzBridge MCP server. This allows dispatching Oz runs directly from Cursor.

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

--------------------------------

### Contribute to OzBridge

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Steps for contributing to the project, including forking, creating branches, committing changes, and opening pull requests. Ensure all tests pass before submission.

```bash
git checkout -b feature/amazing-feature
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature
npm run compile && npm test
```

--------------------------------

### Verify 'oz' Command Availability

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Commands to check if the 'oz' CLI is available in your system's PATH. Use 'which' on macOS/Linux and 'where' on Windows.

```bash
which oz   # macOS / Linux
where oz   # Windows (PowerShell)
```

--------------------------------

### Cursor Configuration

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Configuration for connecting to an OzBridge MCP server using Cursor.

```APIDOC
## Cursor Configuration

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

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

--------------------------------

### Verify Baseline Project Health

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Run these commands to ensure the project's baseline is green before making changes. This includes compilation, testing, and building.

```bash
npm run compile && npm test -- --run && npm run build
```

--------------------------------

### Agent Mode Tool Usage

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Interact with Oz agents in GitHub Copilot Chat's Agent mode using language model tools. Explicit tool references are prefixed with '#'.

```text
# 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.
```

--------------------------------

### Configure Claude Code for Ozbridge

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Add this configuration to your `~/.claude.json` file to connect Claude Code to the Ozbridge SSE server.

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

--------------------------------

### Ozbridge Extension Folder Structure

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Illustrates the directory layout and the primary responsibility of files within the 'src' folder.

```text
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
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Executes end-to-end tests, which require a real VS Code instance. Use 'xvfb-run -a' on headless Linux.

```bash
npm run test:e2e
```

--------------------------------

### Tag Release and Push Tags

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Tag the current release and push all tags to the remote repository. This action triggers updates for the Marketplace, Open VSX, and GitHub Releases.

```git
git tag v1.2.0 && git push --tags
```

--------------------------------

### Codex CLI Configuration

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Configuration for connecting to an OzBridge MCP server using Codex CLI.

```APIDOC
## Codex CLI Configuration

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

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

--------------------------------

### Cloud Agent Execution and Polling Flow

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/DESIGN.md

Diagram showing the sequence for executing a command via the cloud agent, including user confirmation, polling for results, and final notification.

```mermaid
sequenceDiagram
    actor U as Utente
    participant CP as @oz ChatParticipant
    participant CH as CommandHandler
    participant CLI as OzCliService
    participant OZ as oz CLI
    participant POLL as RunPoller
    participant OUT as OutputFormatter

    U->>CP: @oz /cloud "run full test suite"
    CP->>CH: route(command="/cloud", prompt)
    CH->>OUT: stream.progress("Lancio agente cloud...")
    
    Note over CH: Conferma esplicita richiesta (D-Q2)
    CH->>OUT: stream.markdown("⚠️ Confermi lancio cloud? Consuma crediti Warp.")
    
    CH->>CLI: agentRunCloud({prompt, env, model, skill})
    CLI->>OZ: spawn("oz", ["agent","run-cloud","-p","...","--output-format","json"])
    OZ-->>CLI: {runId, status:"QUEUED"}
    CLI-->>CH: OzRunResult
    CH->>OUT: stream.markdown("🚀 Run avviata: {runId}")
    CH->>POLL: startPolling(runId, interval=5s)

    loop Ogni 5s (backoff → 30s, max 30 min)
        POLL->>CLI: runGet(runId)
        CLI->>OZ: spawn("oz", ["run","get","--id",runId,"--output-format","json"])
        OZ-->>CLI: {status, output}
        alt status === "INPROGRESS"
            POLL->>POLL: continua polling
        else status === "SUCCEEDED" | "FAILED"
            POLL->>OUT: notifica risultato finale
            OUT-->>U: Notifica VS Code + risultato
        end
    end
```

--------------------------------

### Package VSIX Extension

Source: https://github.com/sena-labs/ozbridge/blob/main/AGENTS.md

Packages the extension into a VSIX file for distribution.

```bash
npm run package
```

--------------------------------

### Configure Claude Code for OzBridge

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/launch/LAUNCH-KIT.md

Add this configuration to your `~/.claude.json` file to enable Claude Code to connect to the OzBridge MCP server. This allows dispatching Oz runs directly from Claude Code.

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

--------------------------------

### Ozbridge Raw Protocol: Invoke Tool

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Invoke a specific tool on the Ozbridge SSE stream, providing the tool name and its arguments. The response will stream back on the SSE connection.

```bash
# 3. Invoke a tool.
curl -X POST 'http://127.0.0.1:3847/messages?sessionId=<uuid>' \
  -H 'Content-Type: application/json' \
  -d '{ 
        "jsonrpc":"2.0",
        "id":2,
        "method":"tools/call",
        "params":{
          "name":"oz_run_list",
          "arguments":{"status":"completed","limit":5}
        }
      }'
```

--------------------------------

### Enable OzBridge MCP Server in VS Code Settings

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

To enable the MCP server, set the `ozBridge.mcpEnabled` setting to `true` in your VS Code settings. Optional settings for port, bind address, and bearer token can also be configured.

```json
{
  "ozBridge.mcpEnabled": true
}
```

--------------------------------

### Invoke Tool

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Invokes a specific tool on the OzBridge MCP server with provided arguments.

```APIDOC
## Invoke Tool

3. Invoke a tool.

```bash
curl -X POST 'http://127.0.0.1:3847/messages?sessionId=<uuid>'
  -H 'Content-Type: application/json'
  -d '{
        "jsonrpc":"2.0",
        "id":2,
        "method":"tools/call",
        "params":{
          "name":"oz_run_list",
          "arguments":{"status":"completed","limit":5}
        }
      }'
```

Responses stream back on the SSE connection as:
```
event: message
data: {"jsonrpc":"2.0","id":2,"result":{"filter":"completed","count":5,"items":[…]}}
```
```

--------------------------------

### Open SSE Stream

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Opens the Server-Sent Events (SSE) stream to the OzBridge MCP server.

```APIDOC
## Open SSE Stream

1. Open the SSE stream (keep this process running).

```bash
curl -N http://127.0.0.1:3847/sse
```

First frame printed:
```
event: endpoint
data: /messages?sessionId=<uuid>
```
```

--------------------------------

### MCP Protocol Methods

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

The OzBridge implements the Model Context Protocol (MCP) with a small set of supported methods for server interaction.

```APIDOC
## MCP Protocol Methods

- `initialize`: Returns server capabilities and `serverInfo`.
- `ping`: Health probe, always returns `{}`.
- `tools/list`: Enumerates the registered tools.
- `tools/call`: Invokes a tool by name.

Notifications (JSON-RPC requests without an `id`) are dropped if the method is unknown. Resource/prompt/sampling capabilities are *not* advertised in this release.
```

--------------------------------

### Local Validation Commands

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Run local validation commands to ensure code quality and test coverage before committing.

```bash
npm run compile
npm test -- --run
npm run build
```

--------------------------------

### Slash Commands for Oz Agents

Source: https://github.com/sena-labs/ozbridge/blob/main/README.md

Execute various Oz agent functionalities using slash commands within Copilot Chat.

```text
/run Refactor this function
```

```text
/cloud deploy to staging
```

```text
/status
```

```text
/status <runId>
```

```text
/history
```

```text
/history succeeded
```

```text
/history <runId>
```

```text
/schedule create daily "0 9 * * *" "Run linting"
```

```text
/models
```

```text
/models claude-4-8-opus-max
```

```text
/mcp
```

```text
/config
```

```text
/init
```

--------------------------------

### PR Body Template

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Use this three-section template for writing the pull request body, detailing changes, verification steps, and future considerations.

```markdown
## What
- bullet 1
- bullet 2

## Verification
- `npm run compile` — clean.
- `npm test -- --run` — **<count> / <count>** green.
- Bundle size: **XX.XX KB** (budget 145 KB).

## Next
- Follow-up 1
```

--------------------------------

### Ozbridge Raw Protocol: Open SSE Stream

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Open the Server-Sent Events (SSE) stream from Ozbridge. This process should be kept running to receive events.

```bash
# 1. Open the SSE stream (keep this process running).
curl -N http://127.0.0.1:3847/sse
# First frame printed:
#   event: endpoint
#   data: /messages?sessionId=<uuid>
```

--------------------------------

### Enable OzBridge Kill-Switch

Source: https://github.com/sena-labs/ozbridge/blob/main/SECURITY.md

Configure VS Code settings to enable the OzBridge kill-switch. This disables extension functionality during critical incidents. Settings can be applied per-user or per-workspace.

```jsonc
// VS Code settings.json (per-user or per-workspace)
{
  "ozBridge.killSwitch.enabled": true,
  "ozBridge.killSwitch.reason": "Investigating SEC-2026-04-21"
}
```

--------------------------------

### Claude Code Configuration

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Configuration for connecting to an OzBridge MCP server using Claude.

```APIDOC
## Claude Code Configuration

Add to `~/.claude.json`:

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

--------------------------------

### Create and Merge Pull Request

Source: https://github.com/sena-labs/ozbridge/blob/main/CONTRIBUTING.md

Create a pull request and automatically merge it if all checks pass. This includes squashing commits and deleting the branch.

```bash
gh pr create --base main --head feat/<milestone>-<slug> \
  --title "<conventional title>" --body-file pr-body.md
gh pr merge <branch> --squash --delete-branch --auto
```

--------------------------------

### Bearer Authentication

Source: https://github.com/sena-labs/ozbridge/blob/main/docs/MCP.md

Details on how to authenticate requests using Bearer tokens.

```APIDOC
## Bearer Authentication

When `ozBridge.mcpBearerToken` is non-empty, every request must carry an `Authorization: Bearer <token>` header. Requests missing or with a mismatching token receive `401 Unauthorized`. Comparison is constant-time via `crypto.timingSafeEqual`.

Bind to loopback (`127.0.0.1`) whenever possible; only change `ozBridge.mcpBindAddress` if you understand the implications.
```