dev-browser

<p align="center"> <img src="assets/header.png" alt="Dev Browser - Browser automation for Claude Code" width="100%"> </p>

Brought to you by Do Browser.

A browser automation tool that lets AI agents and developers control browsers with sandboxed JavaScript scripts.

Key features:

• •Sandboxed execution - Scripts run in a QuickJS WASM sandbox with no host access
• •Persistent pages - Navigate once, interact across multiple scripts
• •Auto-connect - Connect to your running Chrome or launch a fresh Chromium
• •Full Playwright API - goto, click, fill, locators, evaluate, screenshots, and more

Demo

https://github.com/user-attachments/assets/c6cf7fb9-b1dc-46ed-93b9-6e7240990c53

CLI Installation

npm install -g dev-browser
dev-browser install    # installs Playwright + Chromium

Quick start

# Launch a headless browser and run a script
dev-browser --headless <<'EOF'
const page = await browser.getPage("main");
await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
console.log(await page.title());
EOF

# Connect to your running Chrome (enable at chrome://inspect/#remote-debugging)
dev-browser --connect <<'EOF'
const tabs = await browser.listPages();
console.log(JSON.stringify(tabs, null, 2));
EOF

PowerShell (Windows)

@"
const page = await browser.getPage("main");
await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
console.log(await page.title());
"@ | dev-browser

With --connect:

@"
const page = await browser.getPage("main");
console.log(await page.title());
"@ | dev-browser --connect

Windows notes

PowerShell install:

npm install -g dev-browser
dev-browser install

To attach to a running Chrome instance on Windows:

chrome.exe --remote-debugging-port=9222
dev-browser --connect

Windows npm installs download the native dev-browser-windows-x64.exe release asset during postinstall, and the generated npm shims invoke that executable directly.

Using with AI agents

After installing, just tell your agent to run dev-browser --help — the help output includes a full LLM usage guide with examples and API reference. No plugin or skill installation needed.

<details> <summary>Allowing dev-browser in Claude Code without permission prompts</summary>

By default, Claude Code asks for approval each time it runs a bash command. You can pre-approve dev-browser so it runs without permission checks by adding it to the allow list in your settings.

Per-project — add to .claude/settings.json in your project root:

{
  "permissions": {
    "allow": [
      "Bash(dev-browser *)"
    ]
  }
}

Per-user (global) — add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(dev-browser *)"
    ]
  }
}

The pattern Bash(dev-browser *) matches any command starting with dev-browser followed by arguments (e.g. dev-browser --headless, dev-browser --connect). This is safe because dev-browser scripts run in a sandboxed QuickJS WASM environment with no host filesystem or network access.

You can also allow related commands in the same list:

{
  "permissions": {
    "allow": [
      "Bash(dev-browser *)",
      "Bash(npx dev-browser *)"
    ]
  }
}

Tip: If you've already been prompted and clicked "Always allow", Claude Code adds the specific command pattern automatically. The settings file approach lets you pre-approve it before the first run.

</details>

<details> <summary>Legacy plugin installation (Claude Code / Amp / Codex)</summary>

Claude Code

/plugin marketplace add sawyerhood/dev-browser
/plugin install dev-browser@sawyerhood/dev-browser

Restart Claude Code after installation.

Amp / Codex

Copy the skill to your skills directory:

# For Amp: ~/.claude/skills | For Codex: ~/.codex/skills
SKILLS_DIR=~/.claude/skills  # or ~/.codex/skills

mkdir -p $SKILLS_DIR
git clone https://github.com/sawyerhood/dev-browser /tmp/dev-browser-skill
cp -r /tmp/dev-browser-skill/skills/dev-browser $SKILLS_DIR/dev-browser
rm -rf /tmp/dev-browser-skill

</details>

Script API

Scripts run in a sandboxed QuickJS runtime (not Node.js). Available globals:

// Browser control
browser.getPage(nameOrId)    // Get/create named page, or connect to tab by targetId
browser.newPage()            // Create anonymous page (cleaned up after script)
browser.listPages()          // List all tabs: [{id, url, title, name}]
browser.closePage(name)      // Close a named page

// File I/O (restricted to ~/.dev-browser/tmp/)
await saveScreenshot(buf, name)   // Save screenshot buffer, returns path
await writeFile(name, data)       // Write file, returns path
await readFile(name)              // Read file, returns content

// Output
console.log/warn/error/info       // Routed to CLI stdout/stderr

Pages are full Playwright Page objects — goto, click, fill, locator, evaluate, screenshot, and everything else, including page.snapshotForAI({ track?, depth?, timeout? }), which returns { full, incremental? } for AI-friendly page snapshots.

Every page also exposes two computer-use toolsets:

• •page.cua.* — pixel/vision tier: screenshot() saves a JPEG whose pixels map 1:1 onto CSS coordinates at any DPR and returns { path, width, height }; click, doubleClick, drag, move, scroll, keypress, and type act at those coordinates.
• •page.domCua.* — DOM-id tier: getVisibleDom() snapshots visible interactive elements as pseudo-HTML lines with node_id=N; click, doubleClick, and scroll act by node id (ids are only valid against the latest snapshot of the current document), plus type and keypress for the focused element.

Benchmarks

_See dev-browser-eval for methodology._

License

MIT

Author

Sawyer Hood