opendevbrowser Agent工作流

Launch using extension mode (requires extension popup connected)

npx opendevbrowser launch --extension-only --wait-for-extension

Installation

Requires Node.js >=18.

Interactive installer (recommended)

npx opendevbrowser

Full install (config + extension assets)

npx opendevbrowser --full

OpenCode Tool-Call Installation

Use OpenCode only when you want native opendevbrowser_* tool calls; the CLI and extension workflows work without it.

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).

---

Install auto-start (recommended for resilience)

opendevbrowser daemon install

Manual Setup

1. Ensure extension assets exist by running either: - npx opendevbrowser --full (installer path), or - npm run extension:build (repo/dev path) 2. Load unpacked from ~/.config/opencode/opendevbrowser/extension (fallback: ~/.cache/opencode/node_modules/opendevbrowser/extension). 3. Open extension popup 4. Enter the same relay port and token as the runtime config (if relayToken is missing, either add one to opendevbrowser.jsonc or use Auto-Pair). 5. Click Connect

Install/Management

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 review to get target-aware actionables and refs
4. Interact using refs (click, type, select)
5. Re-review or 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).

CLI Automation Quick Start

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

```bash

Optional: persistent global CLI

npm install -g opendevbrowser opendevbrowser --version ```

Chrome Extension (Optional)

The extension enables Extension Relay mode - attach to existing logged-in browser tabs without launching a new browser.

Requirements: Chrome 125+ (flat CDP sessions). Older versions will fail fast with a clear error.

Default Settings (Extension)

Configuration

Optional config file: ~/.config/opencode/opendevbrowser.jsonc

{
  // Browser settings
  "headless": false,
  "profile": "default",
  "persistProfile": true,
  "chromePath": "/path/to/chrome",  // Custom Chrome executable
  "flags": ["--disable-extensions"],  // Additional Chrome flags

  // Snapshot limits
  "snapshot": { "maxChars": 16000, "maxNodes": 1000 },

  // Export limits
  "export": { "maxNodes": 1000, "inlineStyles": true },

  // DevTools output
  "devtools": { "showFullUrls": false, "showFullConsole": false },

  // Security (all default false for safety)
  "security": {
    "allowRawCDP": false,
    "allowNonLocalCdp": false,
    "allowUnsafeExport": false
  },

  // Provider workflow cookie defaults (optional)
  "providers": {
    "cookiePolicy": "auto",
    "cookieSource": {
      "type": "file",
      "value": "~/.config/opencode/opendevbrowser.provider-cookies.json"
    },
    "challengeOrchestration": {
      "mode": "browser_with_helper",
      "optionalComputerUseBridge": {
        "enabled": true
      }
    }
  },

  // Public read-only sibling desktop observation runtime (enabled by default; set "off" to opt out)
  // On macOS, availability, window, and accessibility probes require the local swift command.
  "desktop": {
    "permissionLevel": "observe",
    "commandTimeoutMs": 10000,
    "auditArtifactsDir": ".opendevbrowser/desktop-runtime",
    "accessibilityMaxDepth": 2,
    "accessibilityMaxChildren": 25
  },

  // Skills configuration
  "skills": {
    "nudge": {
      "enabled": true,
      "keywords": ["form", "login", "extract", "scrape"],
      "maxAgeMs": 60000
    }
  },
  "skillPaths": ["./custom-skills"],  // Additional skill directories

  // Continuity ledger
  "continuity": {
    "enabled": true,
    "filePath": "opendevbrowser_continuity.md",
    "nudge": {
      "enabled": true,
      "keywords": ["plan", "multi-step", "refactor", "migration"],
      "maxAgeMs": 60000
    }
  },

  // Extension relay
  "relayPort": 8787,
  "relayToken": "auto-generated-on-first-run",

  // Hub daemon (relay ownership + FIFO queue)
  "daemonPort": 8788,
  "daemonToken": "auto-generated-on-first-run",

  // Updates
  "checkForUpdates": false
}

All fields are optional. OpenDevBrowser works with sensible defaults.

---

CLI + Extension (No OpenCode)

```bash

Tool Reference

OpenDevBrowser provides 70 tools organized by category: Most runtime actions also have CLI command equivalents (see docs/CLI.md). Complete source-accurate inventory (tools + CLI + /ops + /canvas + /cdp): docs/SURFACE_REFERENCE.md. Terminal help now mirrors the generated public-surface manifest rooted at src/public-surface/source.ts and refreshed by scripts/generate-public-surface-manifest.mjs. npx opendevbrowser --help and npx opendevbrowser help both show every command with its usage and primary flags, every grouped CLI flag, and every bundled opendevbrowser_* tool with its CLI equivalent or tool-only scope. See docs/ASSET_INVENTORY.md for the brand and generated help/public-surface asset inventory used by packaging and website-sync flows.

CLI Commands

The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, browser capture and replay, desktop observation, targets, pages, export, devtools, annotate, and canvas). All commands listed in the CLI reference are implemented and available in the current codebase. See docs/CLI.md for the full command and flag matrix. See docs/SURFACE_REFERENCE.md for the source-accurate inventory matrix (77 CLI commands, 70 tools, /ops, /canvas, and /cdp channel contracts).

CLI Category Matrix (core command groups)

Local Package Validation

Use this flow to validate first-run onboarding from a source tarball without relying on the published registry package.

cd <public-repo-root>
npm pack

WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
ISOLATED_ROOT=$(mktemp -d /tmp/opendevbrowser-first-run-isolated-XXXXXX)
export HOME="$ISOLATED_ROOT/home"
export OPENCODE_CONFIG_DIR="$ISOLATED_ROOT/opencode-config"
export OPENCODE_CACHE_DIR="$ISOLATED_ROOT/opencode-cache"
export CODEX_HOME="$ISOLATED_ROOT/codex-home"
export CLAUDECODE_HOME="$ISOLATED_ROOT/claudecode-home"
export AMP_CLI_HOME="$ISOLATED_ROOT/ampcli-home"
cd "$WORKDIR"
npm init -y
npm install <public-repo-root>/opendevbrowser-0.0.34.tgz
npx --no-install opendevbrowser --help
npx --no-install opendevbrowser help

Published npm consumer proof is tracked separately in docs/RELEASE_RUNBOOK.md through scripts/registry-consumer-smoke.mjs.

Set OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1 before npm install only if you need a packaging smoke test that avoids the install-time managed-skill refresh entirely.

See docs/FIRST_RUN_ONBOARDING.md for the full onboarding checklist, docs/DEPENDENCIES.md for runtime inventory, and docs/SURFACE_REFERENCE.md for the live CLI and tool surface.

Successful installs reconcile daemon auto-start on supported platforms so the relay is available on login. macOS LaunchAgents persist a stable WorkingDirectory under ~/.cache/opendevbrowser so launchd does not start the daemon from /. If the current CLI entrypoint lives under a transient temp-root path such as a first-run /tmp or /private/tmp workspace, OpenDevBrowser refuses to persist that path as auto-start. Rerun opendevbrowser daemon install, or npx --no-install opendevbrowser daemon install from a persistent local package install, from a stable install location if you want login auto-start; remove it later with opendevbrowser daemon uninstall.

Bundled skills sync to OpenCode, Codex, ClaudeCode, and AmpCLI targets during install. npx opendevbrowser manages global or project-local targets according to the selected skills mode, and package installation (npm install -g, local tarball install, or equivalent) best-effort syncs the canonical bundled packs into the managed global targets during package postinstall. See docs/CLI.md for exact target paths.

Or force managed mode without extension

npx opendevbrowser launch --no-extension ```

Unpacked extension load path after local install: - <WORKDIR>/node_modules/opendevbrowser/extension

Core Workflow (Plugin Tools)

---

Preflight daemon-backed workflows

npx opendevbrowser status --daemon --output-format json

DevTools Integration

• Console Capture - Monitor console.log, errors, warnings
• Network Tracking - Request/response metadata (method, url, status)
• Debug Trace Snapshot - Combined page/console/network/exception diagnostics with blocker metadata
• Screenshot - Visible, ref-targeted, or full-page PNG capture (file or base64)
• Dialog - Inspect or handle JavaScript dialogs per target
• Performance - Page load metrics

Macro Workflows

Connection Flow (Extension Relay)

1. Extension checks the discovery endpoint at http://127.0.0.1:8787/config.
2. It learns the relay port and whether pairing is required.
3. If pairing is required and Auto-pair is on, it fetches the token from http://127.0.0.1:<relayPort>/pair.
4. It connects to ws://127.0.0.1:<relayPort>/extension using the extension origin.

/config and /pair accept loopback requests with no Origin (including Origin: null) to support MV3 + PNA; non-extension origins are still rejected, and preflights include Access-Control-Allow-Private-Network: true.

Where Extension Assets Live

Extension assets are bundled inside the NPM package and extracted on install/startup:

• Primary: ~/.config/opencode/opendevbrowser/extension
• Fallback: ~/.cache/opencode/node_modules/opendevbrowser/extension

Extraction is handled by extractExtension() (see src/extension-extractor.ts).

---

Repair OpenCode's cached packages, manifest pin, and lockfile, then restart OpenCode

npx opendevbrowser --update ```

Architecture overview: docs/ARCHITECTURE.md Release checklist: docs/DISTRIBUTION_PLAN.md Documentation index: docs/README.md Frontend docs: docs/FRONTEND.md Dependency inventory: docs/DEPENDENCIES.md Local-only generated artifacts such as prompt-exports/, root artifacts/, coverage/, CONTINUITY*.md, and sub_continuity.md stay uncommitted; .gitignore is authoritative.

---

System Workflow (Happy Path)

1. launch (extension or managed) -> sessionId
2. snapshot -> refs
3. Action commands (click, type, press, hover, check, etc.) -> repeat snapshot
4. disconnect on completion

Troubleshooting: Extension Won't Connect

• Ensure the active tab is a normal http(s) page (not chrome:// or extension pages).
• Confirm relayPort and relayToken in ~/.config/opencode/opendevbrowser.jsonc match the popup (Auto-pair should fetch the token).
• If relayPort is 0, the relay is off.
• relayToken: false disables relay/hub behavior entirely.
• relayToken: "" (empty string) keeps relay enabled but disables pairing requirements.
• Install auto-start with opendevbrowser daemon install from a stable install location so the relay is available on login.
• Clear extension local data and retry if the token/port seem stuck.
• If another process owns the port, change relayPort or stop it; opencode listening is expected.