Get Started

Octowright is a runtime for orchestrating real Chromium, Firefox, and WebKit instances in parallel — recording every action to replayable JSONL, exporting portable replay scripts, and producing the same artifacts you see on this site. You can drive it three ways:

1. From an MCP harness (Claude Code, Codex, Cursor, Continue, Zed, …) — register it once and the harness exposes Octowright’s tool surface (browser_launch, browser_click, scenario_start, macro_run, …) directly to the model.
2. From the CLI — octowright serve, octowright scenario, octowright test, octowright persona, etc.
3. As a Python library — import octowright, drive BrowserPool and ScenarioPool from your own code.

The MCP path is usually the fastest way to get value because the harness already speaks the protocol. The other two paths are unchanged.

1. Install Octowright

git clone https://github.com/provide-io/octowright.git
cd octowright
uv sync
uv run playwright install chromium firefox webkit

uv sync resolves the Python environment from uv.lock. The second line downloads the actual browser binaries Playwright drives. Octowright uses uv exclusively — there is no pip install path because reproducible dependency resolution is a hard requirement for the recording pipeline.

Verify the install:

uv run octowright selftest

This prints the registered MCP tools without needing a live MCP client. If you see the tool list, the install is healthy.

2. Register with your MCP harness

Pick the harness you use. The command and args are the same in every case — only the config file format differs.

Claude Code

Add to .mcp.json (project-scoped) or ~/.claude.json (global):

{
  "mcpServers": {
    "octowright": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/octowright", "run", "octowright", "serve"]
    }
  }
}

Or run the convenience scaffolder, which prints the registration block with the path filled in:

uv run octowright init

Reload Claude Code. The tools appear as mcp__octowright__browser_launch, mcp__octowright__browser_click, etc.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.octowright]
command = "uv"
args = ["--directory", "/abs/path/to/octowright", "run", "octowright", "serve"]

Restart Codex. Octowright tools become callable from the Codex agent.

Cursor, Continue, Zed, and other MCP harnesses

Most MCP-aware editors accept the same JSON shape Claude Code uses. Drop this block into the harness’s MCP config (the exact filename varies — check your editor’s documentation):

{
  "mcpServers": {
    "octowright": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/octowright", "run", "octowright", "serve"]
    }
  }
}

If your harness uses a different schema (e.g. TOML, YAML, or a UI form), the same three values translate directly: command uv, working directory /abs/path/to/octowright, args run octowright serve.

3. Smoke test

A four-call sequence that exercises launch, drive, list, and close:

1. Ask the agent to call browser_launch with kind=webkit and url=https://example.com.
2. Ask it to call browser_click_by on the link text “More information”.
3. Ask it to call browser_list and confirm exactly one live instance.
4. Ask it to call browser_close with the instance_id from step 1.

If all four succeed, the install, the Playwright runtime, and the MCP wiring are healthy.

What’s actually running

octowright serve starts two things in one process: the MCP stdio server (which is what your harness talks to) and a local HTTP dashboard at http://127.0.0.1:8765. The dashboard is optional — handy for watching live browser sessions, replays, and recorded artifacts in real time. You can ignore it entirely and still get the full MCP tool surface.

Without an MCP harness

If you don’t need the LLM-driven tool surface, Octowright works fine standalone.

From the CLI

uv run octowright serve              # MCP + dashboard sidecar
uv run octowright scenario list      # list scenarios
uv run octowright persona list       # list personas
uv run octowright test               # run scenarios as tests
uv run octowright selftest           # list registered MCP tools

As a Python library

import asyncio
from octowright.browser_pool import BrowserPool
from octowright.scenarios import load_yaml_scenario
from octowright.scenarios_pool import ScenarioPool

async def main():
    pool = BrowserPool()
    scenarios = ScenarioPool()
    spec = load_yaml_scenario("examples/scenarios/cross-engine.yaml")
    live = await scenarios.start(spec=spec, browser_pool=pool)
    # …drive it however you like…
    await pool.shutdown()

asyncio.run(main())

The same BrowserPool and ScenarioPool objects power the MCP tools, so anything Octowright exposes through MCP is also reachable from Python.

Keep going

• Demos — see the recorded multi-browser bundles whose artifacts the public site is built from.
• Docs — architecture, scenarios, personas, macros, and the full CLI surface.
• GitHub — source, issues, and the canonical install reference.