OpenDevBrowser

Script-first browser automation for AI agents. Snapshot → Refs → Actions.

OpenDevBrowser is an agent-agnostic browser automation runtime. You can use it as an OpenCode plugin, as a standalone CLI, or through the Chrome extension relay for logged-in browser sessions. It supports managed sessions, direct CDP attach, and extension-backed Ops sessions. Frontend website source and deployment are maintained in the private repo opendevbrowser-website-deploy.

<img src="assets/hero-image.png" alt="OpenDevBrowser hero image showing AI-assisted annotation and browser automation workflow" width="920" /> AI-assisted annotation and browser automation workflow

Use It Your Way

| Interface | OpenCode Required | Best For | |-----------|-------------------|----------| | CLI (npx opendevbrowser ...) | No | Any agent/workflow that can run shell commands | | Chrome Extension + Relay | No | Reusing existing logged-in tabs without launching a new browser | | OpenCode Plugin Tools | Yes | Native tool-calling inside OpenCode (opendevbrowser_*) | | Frontend Website (private repo) | No | Product website and generated docs routes |

All core automation flows are available through the CLI command surface and the plugin tool surface. Private website docs routes are generated from public repository source-of-truth docs and skill packs.

Distribution split (current target state):

Public repo (opendevbrowser): runtime, CLI, extension, docs, npm, release artifacts.
Private repo (opendevbrowser-website-deploy): website deployment (website-production branch).

Why OpenDevBrowser?

| Feature | Benefit | |---------|---------| | Script-first UX | Snapshot → Refs → Actions workflow optimized for AI agents | | Accessibility-tree snapshots | Token-efficient page representation (not raw DOM) | | Stable refs | Elements identified by backendNodeId, not fragile selectors | | Security by default | CDP localhost-only, timing-safe auth, HTML sanitization | | 3 browser modes | Managed, CDP connect, or extension relay for logged-in sessions | | Chrome-family session reuse | Managed and cdpConnect sessions bootstrap readable cookies from the discovered system Chrome-family profile; extension mode reuses the already logged-in tab | | Ops + Canvas + CDP channels | High-level multi-client /ops, dedicated /canvas, plus legacy /cdp compatibility | | Relay Hub (FIFO leases) | Single-owner CDP binding with a FIFO queue for multi-client safety | | Flat-session routing | Extension relay uses DebuggerSession sessionId routing (Chrome 125+) | | Design canvas + code sync | Persist repo-native design documents, attach same-session observers, run framework-adapter-backed code sync across built-in React or HTML or custom-elements or Vue or Svelte lanes plus repo-local BYO plugins, author tokens in canvas.html, and drive preview tabs with canvas_html or opted-in bound_app_runtime reconciliation | | Shared annotation inbox | Popup/canvas Send actions deliver into the active chat when scope is safe and degrade cleanly to annotate --stored retrieval when it is not | | Loop-closure diagnostics | Console/network polling + unified debug trace snapshots for verification workflows | | 11 bundled skill directories | Best practices, design-agent guidance, login, forms, data extraction, research, shopping, and product asset workflows | | 49 tools | Complete browser automation coverage, including the design-canvas command surface | | 97% test coverage | Production-ready with strict TypeScript |

Installation

Requires Node.js >=18.

For Humans

# Interactive installer (recommended)
npx opendevbrowser

# Or specify location
npx opendevbrowser --global   # ~/.config/opencode/opencode.json
npx opendevbrowser --local    # ./opencode.json

# Full install (config + extension assets)
npx opendevbrowser --full

# Optional: persistent global CLI
npm install -g opendevbrowser
opendevbrowser --version

Pre-release Local Package (No npm publish required)

Use this path to validate first-run onboarding before public distribution:

cd <public-repo-root>
npm pack

WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
cd "$WORKDIR"
npm init -y
npm install <public-repo-root>/opendevbrowser-0.0.17.tgz
npx --no-install opendevbrowser --help
npx --no-install opendevbrowser help

Full validated flow: docs/FIRST_RUN_ONBOARDING.md. Dependency/runtime inventory: docs/DEPENDENCIES.md. Live CLI inventory/help surface: npx opendevbrowser --help or npx opendevbrowser help.

Use OpenCode only if you want plugin tools. CLI and extension workflows work without OpenCode.

On successful installs, the CLI reconciles daemon auto-start on supported platforms so the relay is available on login. Existing installs are rechecked and repaired when the per-user auto-start entry is missing, stale, or malformed. If the current CLI entrypoint lives under a transient temp-root path (for example a first-run /tmp or /private/tmp workspace), OpenDevBrowser refuses to persist that path as auto-start. Plugin install still succeeds, but you must rerun opendevbrowser daemon install from a stable install location, or npx --no-install opendevbrowser daemon install from a persistent local package install, if you want login auto-start. You can remove it later with opendevbrowser daemon uninstall.

During install, bundled skills are synced for OpenCode, Codex, ClaudeCode, and AmpCLI. Default --skills-global targets:

~/.config/opencode/skill (OpenCode)
$CODEX_HOME/skills (fallback ~/.codex/skills)
$CLAUDECODE_HOME/skills or $CLAUDE_HOME/skills (fallback ~/.claude/skills)
$AMPCLI_HOME/skills or $AMP_CLI_HOME/skills or $AMP_HOME/skills (fallback ~/.amp/skills)

Use --skills-local for project-local targets:

./.opencode/skill, ./.codex/skills, ./.claude/skills, ./.amp/skills

CLI + Extension (No OpenCode)

# Start relay/daemon runtime
npx opendevbrowser serve

# Launch using extension mode (requires extension popup connected)
npx opendevbrowser launch --extension-only --wait-for-extension

# Or force managed mode without extension
npx opendevbrowser launch --no-extension

Unpacked extension load path after local install:

<WORKDIR>/node_modules/opendevbrowser/extension

Frontend Website (Private Repo)

git clone https://github.com/freshtechbro/opendevbrowser-website-deploy.git
cd opendevbrowser-website-deploy/frontend
npm install
npm run dev

Website build/data pipeline lives in the private repo:

npm run sync:assets copies mirrored assets into private frontend/public/brand.
npm run generate:docs regenerates docs, metrics, and roadmap JSON consumed by /docs.

Agent Installation (OpenCode)

Recommended (CLI, installs plugin + config + bundled skills + extension assets):

npx opendevbrowser --full --global --no-prompt

Explicit flags (config + skills, no prompt):

npx opendevbrowser --global --with-config --skills-global --no-prompt

Manual fallback (edit OpenCode config):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opendevbrowser"]
}

Config location: ~/.config/opencode/opencode.json

Restart OpenCode, then run opendevbrowser_status to verify the plugin is loaded (daemon status when hub is enabled).

Quick Start

OpenDevBrowser uses the same automation model across plugin tools and CLI commands:

1. Launch a browser session
2. Navigate to a URL
3. Take a snapshot to get element refs
4. Interact using refs (click, type, select)
5. Re-snapshot after navigation

Shipping checklist for first-time users (local-package install, daemon, extension, first task, multi-tab auth/cookies):

docs/FIRST_RUN_ONBOARDING.md

Parallel execution is target-scoped (ExecutionKey = (sessionId,targetId)): same target is FIFO, different targets can run concurrently up to the governor cap. session-per-worker remains the safest baseline for strict isolation. See docs/CLI.md (Concurrency semantics) and skills/opendevbrowser-best-practices/artifacts/provider-workflows.md (Workflow E).

Core Workflow (Plugin Tools)

| Step | Tool | Purpose | |------|------|---------| | 1 | opendevbrowser_launch | Launch a session (extension relay first; managed fallback is explicit) | | 2 | opendevbrowser_goto | Navigate to URL | | 3 | opendevbrowser_snapshot | Get page structure with refs | | 4 | opendevbrowser_click / opendevbrowser_type | Interact with elements | | 5 | opendevbrowser_disconnect | Clean up session |

CLI Automation Quick Start

Run a local daemon for persistent sessions, then drive automation via CLI commands:

# Start daemon
npx opendevbrowser serve

# Install auto-start (recommended for resilienc

Opendevbrowser

Install / Use

README