Octowright

An MCP server that lets agentic coding clients drive many headed Playwright browsers in parallel with a mix of engines (Chromium, Firefox, WebKit), recording every action to a JSONL log so a session can later be exported as a standalone Playwright script.

Octowright is optimized for multi-session, mixed-engine browser orchestration with persistent profiles, structured recordings, and a local debugger dashboard.

Get started

Octowright is on PyPI (uv tool install octowright, or uvx octowright serve to run it without installing), but this guide walks the from-source path: it is what the MCP registration block below assumes, and the optional terminal plugin is only installable from the checkout. Octowright uses uv for dependency management. If you don't have uv yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, from any directory you'd like Octowright to live under (e.g. ~/code/):

git clone https://github.com/livingstaccato/octowright.git
cd octowright
uv sync                                              # install Python deps
uv run playwright install webkit firefox chromium    # install browser binaries
uv run octowright init                               # print MCP registration block + scaffold config

Engine-binary management is currently CLI-driven (playwright install / playwright install --list), not exposed as Octowright MCP tools.

The last command prints a JSON block to paste into an MCP client config, commonly .mcp.json for a project or ~/.claude.json for Claude Code. It also creates Octowright's user config directory with a sample persona, scenario, and macro so you have something to play with.

The block it prints looks like this — init substitutes your install path into <absolute-path-to-octowright>:

{
  "mcpServers": {
    "octowright": {
      "command": "uv",
      "args": [
        "--directory",
        "<absolute-path-to-octowright>",
        "run",
        "octowright",
        "serve"
      ]
    }
  }
}

Reload your MCP client. The tools appear as mcp__octowright__browser_launch, etc.

Verify in 30 seconds: ask your client to launch a webkit browser at octowright.com, click a link, list browsers, then close. The next section walks through that same flow as a tour of what Octowright actually does.

Your first 5 minutes

Once installed and registered, ask your MCP client to walk through these in order. Each step builds on the previous one and shows you what Octowright actually does.

1. Open a browser. Ask: "launch a webkit browser at octowright.com". The client calls browser_launch kind=webkit url=https://octowright.com. A real WebKit window opens on your desktop. The result includes the instance_id so the client can target later actions.

2. Drive it. Ask: "click the 'More information' link". The client calls browser_click text="More information" (an ARIA locator — no CSS selector needed). The window navigates. Every action lands in a JSONL recording on disk.

3. List what's open. Ask: "what browsers are running?". browser_list returns a one-line summary like 1 browser: 8a3f.../webkit @ iana.org/help/example-domains.

4. Save the session as a macro. Ask: "save the last few clicks as a macro called example-tour". The client calls macro_save. Now macro_run name=example-tour replays it.

5. Close the browser, then launch a named one. Ask: "close that browser, then launch a chromium browser with profile=demo at github.com". The window opens, you log in (or whatever). When you close it, the cookies/localStorage flush to the profile directory in Octowright's config dir. Re-launch with the same profile and you're already logged in.

That's the whole tool: parallel browsers, recordings, named macros, persistent profiles. Personas are profiles with metadata (display name, default URL, credential references); scenarios are pre-declared groups of personas you can spin up with one call. Both are covered later. The dashboard ties every piece together visually — see the next section.

Demo catalog

Octowright now ships a curated demo catalog on top of the raw examples/ material.

• Repo-facing catalog: demo/INDEX.md
• Authored bundle manifests: demo/bundles/<demo-id>/demo.yaml

The current hero set promotes seven offline-first bundles: first-run-session, macro-replay-loop, cross-engine-trio, role-based-duo, fixture-lab, verify-suite, and seven-mix-orchestration.

examples/ remains the raw source layer for reusable macros and scenarios. demo/bundles/ is the product-facing layer that adds audience/tag metadata, artifact expectations, regen commands, tutorial-export metadata, and small deterministic seed assets.

To refresh the generated repo catalog and per-bundle tutorial-export JSON from the manifests:

uv run python scripts/demos/record_heroes.py

Distributed Skill Pack

Octowright ships a packaged skill named octowright for Codex and project-local plugin manifests for compatible runtimes such as Claude Code and Codex.

Install everything:

uv run octowright skill install octowright --target all

Check status and drift:

uv run octowright skill status octowright --target all

Run diagnostics:

uv run octowright skill doctor --json

Notes:

• Codex skill install target is $CODEX_HOME/skills (defaults to ~/.codex/skills).
• Plugin manifests are written in the current project under .claude-plugin/plugin.json and .codex-plugin/plugin.json.
• Use --dry-run to preview writes and --force to overwrite existing installs.
• Distributed skill/plugin metadata versions are sourced from octowright.VERSION.

Dashboard

octowright serve boots two things in one process: the MCP stdio server (what your client talks to) and a Starlette HTTP server on http://127.0.0.1:6286/ (what you look at) — every live browser and scenario, closed-session cleanup, a per-session debugger (video, action timeline, console/downloads/screenshots), live WebSocket updates, and a Playwright trace-viewer deep-dive.

Ask your MCP client "give me the octowright dashboard URL" (it'll call the octowright_dashboard_url MCP tool), or just open the URL directly.

Full reference: docs/dashboard.md.

Concepts: how the pieces relate

Five layers, each building on the one below:

1. Browser. A single live Playwright browser — one engine (chromium / firefox / webkit), one window. Identified by an instance_id. Every action you run against it gets appended to a JSONL recording, and a separate BrowserContext gives it its own cookie jar (so seven parallel Discord tabs never share auth, even when they all run on WebKit).

2. Profile. A directory on disk (<octowright-config>/profiles/<persona>/<kind>/) that stores cookies, localStorage, IndexedDB, and service-worker state between browser runs. When you pass profile=dante to browser_launch, the browser uses a persistent context pointed at that directory — close the browser, re-launch tomorrow, and you're still logged in. Profiles are scoped per engine; Dante on WebKit and Dante on Firefox are two distinct profile dirs under the same persona.

3. Persona. A named identity that owns profiles across one or more engines, plus metadata: display name, default_url (which is also the context's Playwright base_url, so a macro can navigate /orders and stay portable across deployments), default_macros to run at launch, credentials (references to env vars or shell commands — secrets themselves are never stored on disk), and an app dict for domain metadata. Think of a persona as "Dante — my Discord power user across all three engines", and a profile as one engine-specific piece of that identity. You launch it with browser_launch profile=dante; the resolver (browser_suggest_for_url) works out which persona to reuse when the URL is ambiguous. See docs/personas.md for the full profile.yaml shape.

4. Scenario. A pre-declared group of personas to launch together, each with a role (player, monitor, spectator). Declared in <octowright-config>/scenarios/<name>.yaml (or a Python build() function for dynamic rosters). scenario_start name=discord-raid launches all seven participants in parallel, applies shared fixtures (dialog policy, mock routes), runs each participant's startup macros. You can then broadcast a macro across all participants (scenario_run_macro), role-filter (role=player), or drive a single participant by its instance_id. See docs/scenarios.md for the full spec shape.

5. Dashboard. The web UI bundled with octowright serve is the visual projection of everything above. The dashboard page lists every live browser, every live scenario, recent closed sessions, every persona, every macro; each session links to a debugger page with embedded video, click-to-seek action timeline, console messages, downloads, and screenshots. The Playwright trace viewer is one button away. See the Dashboard section above for what it shows; this layer doesn't add new state — it just makes the other four layers observable.

When to reach for which. A single browser for one-shot exploration. A named profile when you want login state to survive. A persona when that identity is worth metadata and credential references. A scenario when you need N coordinated browsers as a single unit. The dashboard whenever you want to see what's happening rather than ask your MCP client.

Operation ordering. Every browser session serializes its own operations FIFO — a second tool call, a background capture, or a queued macro action against the same instance_id waits its turn instead of racing the one in flight, and one macro (or macro sequence, or artifact replay) holds its browser for the whole run so a manual action can't land mid-sequence. Different sessions never wait on each other. A queued operation gives up after OCTOWRIGHT_OPERATION_QUEUE_TIMEOUT_SECONDS (default 300s, see Configuration) and fails with a plain tool error — it never takes down the MCP connection or another browser. Closing a session drains whatever is already queued, then rejects anything new; if the browser or page closes out from under an in-flight call instead, that call still fails cleanly and any still-queued work is released with a session-closed error. Embedders driving BrowserSession directly: list_pages(), list_frames(), and set_dialog_policy() are async now and must be awaited, and a session should be torn down through BrowserPool.close() rather than closing the underlying Playwright objects directly so the drain/reject behavior above still applies.

Tools

Every mutating tool takes an instance_id returned from browser_launch. Each call appends a record to that instance's JSONL log.

Browser lifecycle

Input

Recorded CSS click and fill actions also capture semantic metadata when Playwright can resolve it. Macro playback and exported replay scripts try that ARIA locator first, then fall back to the original CSS selector.

Inspection

Assertions

Network & dialogs

Pages, frames, downloads

Profiles, personas, scenarios, macros, goldens

Housekeeping

Persistent profiles, personas, macros, scenarios

Quick orientation — each links to its full reference:

• Persistent profiles. Pass profile=<name> to browser_launch and cookies/localStorage/IndexedDB survive close/relaunch ((kind, profile) is the identity; each live browser still has its own isolated BrowserContext). Window titles get a (<persona-emoji><engine-emoji>) [<profile>] badge so parallel windows are distinguishable, and protected sessions refuse a close without force=True. Full reference: docs/personas.md.
• Personas. A named identity that owns profiles across engines, plus display name, default_url, startup macros, and credential references (never secrets themselves — persona_credentials_check pre-flights them). Full reference: docs/personas.md.
• Macros. Record a flow once (macro_save), replay it with different args later (macro_run), across any persona/profile. if_selector / try / try_each cover multi-DOM-version flows. Full reference: docs/macros.md.
• Scenarios. A named, declared group of personas launched together with roles, fixtures, and verify macros — scenario_start brings up N participants in parallel; scenario_run_macro broadcasts across them. Full reference: docs/scenarios.md.

Configuration

All defaults live in src/octowright/defaults.py and can be overridden via environment variables:

On POSIX systems, Octowright follows the XDG Base Directory split:

• Config: ${XDG_CONFIG_HOME:-~/.config}/octowright/ for durable user-authored data.
• State: ${XDG_STATE_HOME:-~/.local/state}/octowright/ for session history, logs, and manifests.
• Cache: ${XDG_CACHE_HOME:-~/.cache}/octowright/ for rebuildable analysis captures.

On Windows, config uses %APPDATA%\octowright\, while state and cache use %LOCALAPPDATA%\octowright\State\ and %LOCALAPPDATA%\octowright\Cache\.

CLI

octowright is a Click-based CLI; subcommands let you do common housekeeping without going through an MCP client:

Capability profiles

The full MCP tool surface is currently 134 tools on a core install — every workflow Octowright supports (browser driving, macros, scenarios, persona management, etc.) shows up in the LLM's tool schema by default. When the LLM only needs a slice, set OCTOWRIGHT_PROFILE (or pass --profile to octowright serve) to one or more comma-separated profile names. Tools not listed in any active profile are skipped at registration time, so the LLM-visible schema shrinks. Seven meta/Advisor tools are always registered so agents can inspect Octowright, find the dashboard, and surface local guidance even under narrow profiles.

octowright serve --profile=core              # 31 tools — core + always-on
octowright serve --profile=core,macros       # 46 tools — browser + macro pipeline + always-on
octowright serve --profile=core,scenarios    # browser + multi-browser orchestration

The active profile shows up in octowright selftest and in the octowright_status MCP tool's profile block. If a tool you expected is missing, that's where to look. The dict lives in src/octowright/server/profiles.py — extend it to add or rebalance groups.

Octowright Advisor

Octowright Advisor is a local, deterministic guidance layer exposed through always-on MCP tools. octowright_status includes an advisor block, and octowright_advisor_status returns the same Advisor snapshot directly: preferences, recent usage summary, and current suggestions. (octowright_status also carries an upgrade block on the first run after a version change — present its highlights to the user as a "what's new" note.)

Advisor currently suggests two things:

• Macro candidates: agents call octowright_advisor_record_macro_observation when they notice repeated workflows. Two observations with the same signature produce a macro_candidate suggestion. Advisor never auto-saves a macro.
• Profile changes: recent MCP tool usage can suggest narrowing or expanding OCTOWRIGHT_PROFILE. Profile-change suggestions can be prompt-only or marked auto_apply when the profile_change preference is automatic.

Agents should check Advisor status after first-touch status and before asking a user whether repeated work should become a macro. Preferences are persisted in the local Advisor state file and can be changed with octowright_advisor_set_preference. Set OCTOWRIGHT_ADVISOR_STATE to isolate that JSON state file for tests or separate deployments.

Telemetry

Both halves of Octowright (Python server, TypeScript dashboard) use the provide.telemetry family for structured logging, with opt-in OpenTelemetry trace/metric export to any OTLP collector:

export PROVIDE_TRACE_ENABLED=1
export PROVIDE_METRICS_ENABLED=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
uv run octowright serve

Full reference: docs/telemetry.md.

Safari caveat

Playwright's webkit channel is the bundled upstream WebKit engine, not Apple's Safari.app. It shares the engine family but is a separate binary (playwright install webkit). Driving actual Safari.app with your cookies/profile requires Apple's safaridriver and is not supported by Playwright today.

Selftest

uv run octowright selftest

Prints the list of registered tools without needing a live MCP client.

Documentation

• docs/README.md: full documentation index.
• docs/getting-started.md: install, registration, and first successful run.
• docs/engines.md: engine install/status/reinstall and launch-mode behavior.
• docs/personas.md: persona/profile lifecycle and credential preflight.
• docs/macros.md: macro record/replay, linting, and test execution.
• docs/scenarios.md: multi-browser orchestration lifecycle.
• docs/goldens.md: baseline capture vs verify policy.
• docs/dashboard.md: web UI, per-session debugger, trace deep-dive.
• docs/telemetry.md: structured logging, OTLP export, HTTP metrics.
• docs/ci-quality.md: quality gates and local CI parity commands.
• docs/troubleshooting.md: fast diagnosis for common failures.
• docs/architecture/: system diagrams and architecture references.
• CHANGELOG.md: release summaries.