bunwv
Headless browser automation CLI for Bun, powered by Bun.WebView. Cross-platform: WebKit on macOS (default, zero dependencies), Chrome on macOS/Linux/Windows.
A persistent daemon keeps a browser instance alive so page state — DOM, modals, forms, auth, cookies — survives across commands. Designed agent-first: every action verb is silent on success, errors are JSON on stderr with stable exit codes, and event/console buffers are cursor-pulled. Built for AI coding assistants (Claude Code, Cursor, etc.) driving the browser through discrete tool calls.
Install
bun install -g @naticha/bunwv
Requires Bun v1.3.14+. On macOS, uses the native WebKit engine by default (zero dependencies). On Linux and Windows, automatically uses Chrome/Chromium (must be installed).
AI Coding Assistant Skill
bunx skills add naticha/bunwv
# or
npx skills add naticha/bunwv
Or install directly in Claude Code:
/plugin marketplace add naticha/bunwv
/plugin install bunwv@bunwv
This installs the skill file that teaches AI assistants how to use bunwv for browser testing.
Quick Start
bunwv start # start the daemon
bunwv navigate http://localhost:3000 # go to a page
bunwv screenshot # writes /tmp/bunwv-screenshot-<session>.jpg (JPEG @ q80), prints the path
bunwv screenshot --max-width 1024 # bound the longest side; aspect preserved
bunwv screenshot --metadata # {"width","height","format"} instead of pixels
bunwv click --selector "button.submit" # click an element (auto-waits)
bunwv type "hello world" # type into focused element
bunwv evaluate "document.title" # run JS in the page, JSON-literal result
bunwv close # stop the daemon
Agent-first contract
- Successful action verbs print nothing on stdout and exit 0.
click, type, navigate, press, scroll, scroll-to, clear, submit, resize, back/forward/reload, close, exists, wait-for, wait-for-gone, cdp-subscribe, cdp-unsubscribe are all silent. Read verbs (status, evaluate, events, console, cdp, cdp-subscriptions, screenshot, sessions) print their result.
- Stable exit codes:
0 ok, 1 generic, 2 usage, 3 timeout, 4 element-not-found, 5 daemon-unreachable, 6 batch-partial.
- Errors are JSON on stderr:
{ok:false, error, exitCode}. Branch on the exit code, not stderr text.
- Error-level console auto-surfaces. If the page logs
console.error/console.warn while a verb runs, {"console":[…]} is written to stderr alongside the verb's response.
--json global flag wraps any command's output as {ok, data?, error?, exitCode}.- Flexible flags:
--flag value, --flag=value, repeated flags (e.g. --mod Shift --mod Control), and flags before or after the command all work.
BUNWV_SESSION env var replaces --session <name> when set.
Commands
Session
| Command | Description |
|---|
start [--width N] [--height N] [--data-store PATH] [--idle-timeout ms] [--backend webkit|chrome] [--chrome-path PATH] [--chrome-argv '[json]'] [--chrome-url <ws>] [--chrome-stdout inherit|ignore] [--chrome-stderr inherit|ignore] [--webkit-stdout inherit|ignore] [--webkit-stderr inherit|ignore] [--url <initial>] | Start the daemon (default 1920x1080, 30min idle timeout) |
close [--all] | Stop this session, or every running session with --all |
status | Terse: <url> | <title> | <idle|loading> | pending=<n>. --json for loading, pendingEvents, cursor, cdpSubscriptions |
sessions | List all running sessions |
Navigation
| Command | Description |
|---|
navigate <url> | Navigate to a URL (silent) |
back / forward / reload | History + refresh (silent) |
Interaction
