bunwv: Instructions file for Claude Code

CLAUDE.md

This is bunwv — a headless browser automation CLI built on Bun.WebView (Bun v1.3.12+). Cross-platform: WebKit on macOS (default), Chrome on Linux/Windows (auto-detected).

Project Structure

bunwv.ts          # CLI entry point (shebang, arg parsing, commands)
lib/daemon.ts     # WebView daemon (Bun.serve on Unix socket, all routes)
skills/bunwv/     # Claude Code skill file (SKILL.md)
.claude-plugin/   # Marketplace plugin config
docs/             # Bun.WebView API reference notes

Development

bun bunwv.ts help                    # run locally during dev
bun bunwv.ts start                   # test the daemon
bun bunwv.ts close                   # stop it

Default to Bun for everything — no Node, no npm scripts, no external dependencies.

Architecture

• CLI (bunwv.ts) parses args into flags/positional, sends HTTP requests to the daemon via Unix socket
• Daemon (lib/daemon.ts) owns a Bun.WebView instance, exposes all WebView methods as HTTP routes on /tmp/bunwv-<session>.sock
• Sessions are isolated by name — each gets its own socket, PID file, and WebView instance
• Auto-shutdown after 30min idle (configurable via --idle-timeout)

Design principles (agent-first)

bunwv is designed for AI coding agents driving it via discrete tool calls. Humans are a secondary user. When the two conflict, agent UX wins.

• Statelessness over streams. Every command is one request, one response, exit. No long-lived connections, no background processes for the agent to manage. "Tail" patterns use snapshot + cursor (--since <seq>), never streaming.
• Token efficiency in the happy path. Successful verbs print only what's needed to continue. click, type, navigate, press, scroll, resize, back/forward/reload: empty stdout, exit 0. Don't spend tokens confirming success.
• Structure only where it earns its tokens. JSON is ~30–50% heavier than prose for small outputs. Use plain text for simple success; use JSON for (a) errors, (b) genuinely structured data (events, console buffer, multi-field status under --json), (c) anywhere the agent must distinguish types — evaluate prints JSON-literal values so strings keep their quotes and numbers don't.
• Reliability on the unhappy path. Errors are always JSON on stderr with nonzero exit. Exit codes are stable and documented. Agents branch on exit code, not on stderr parsing. (0 ok, 1 generic, 2 usage, 3 timeout, 4 element-not-found, 5 daemon-unreachable.)
• Error-level console auto-surfaces; everything else is pull. If console.error or console.warn fires during a verb, the daemon attaches X-Console-Errors to the HTTP response and the CLI forwards it to process stderr as {console:[…]}. Normal logs, CDP events, and navigation events stay in ring buffers, fetched on demand via bunwv console --since / bunwv events --since.
• File paths for binary outputs. Screenshots default to a file path on disk; the agent's file-reading tools handle the image. --encoding base64 and --out - (stdout) exist but are not the default.
• --json for opt-in uniformity. Agents that prefer one shape over terseness can force an envelope {ok, data?, error?, exitCode} on any command.
• 1:1 with Bun.WebView. Every capability of the Bun.WebView type is reachable from the CLI. No JS-API-only escape hatches.