bunwv

bunwv operates using a client-server model designed for high-performance browser automation via Bun:

1. CLI Client: The bunwv CLI sends HTTP requests to a background daemon via a Unix socket (located at /tmp/bunwv-*.sock, restricted to chmod 0600).
2. Daemon: A background process that manages a single Bun.WebView instance. It listens for requests and manages the browser lifecycle.
3. Browser Engine: Uses Bun.WebView to drive WebKit on macOS, Chrome on Linux, or the native Windows engine.

Key Technical Features:

• Native Events: All selector and coordinate-based inputs are dispatched as native events (isTrusted: true).
• Auto-waiting: Selector-based methods automatically wait for elements to be attached, visible, stable, and unobscured before acting.
• Event Buffering: Navigation and CDP (Chrome DevTools Protocol) events are buffered using monotonic seq cursors, allowing agents to poll for new events since their last interaction.

bunwv is optimized for AI agents using discrete tool calls. Key contracts include:

• Success/Failure Signaling: Successful verbs (e.g., click, type, navigate) print nothing to stdout and exit with code 0. Errors are emitted as JSON on stderr with specific exit codes.
• Exit Codes:
  • 0: OK
  • 1: Generic error
  • 2: Usage error
  • 3: Timeout
  • 4: Element not found
  • 5: Daemon unreachable
  • 6: Batch partial failure (only in batch --keep-going)
• Automatic Console Capture: If the page logs an error while a verb is running, bunwv automatically prints {"console":[...]} to stderr.
• Uniform JSON Envelopes: Use the --json flag with any command to receive a consistent {ok, data?, error?, exitCode} JSON object.
• Flexible Flag Syntax: Supports --flag value, --flag=value, and repeated flags (e.g., --mod Shift --mod Control). Flags can appear before or after the command.
• Session Persistence: Use the BUNWV_SESSION environment variable to avoid passing --session <name> in every command.

The bunwv CLI is designed for AI agents with a specific communication contract:

• Silent Success: Action verbs (e.g., click, type, navigate, scroll, submit, close) print nothing to stdout and exit with code 0 on success. This reduces noise for agents.
• JSON Errors on stderr: When an action fails, stderr contains a JSON object: {ok:false, error, exitCode}. Agents should branch on the exitCode, not the error text.
• Stable Exit Codes:
  • 0: OK
  • 1: Generic error
  • 2: Usage error
  • 3: Timeout
  • 4: Element not found
  • 5: Daemon unreachable
  • 6: Batch partial failure
• Auto-surfacing Console Errors: If a page logs console.error or console.warn while a command is running, the error is automatically written to stderr alongside the command's response as {"console":[...]}.
• Global --json flag: Wrapping any command with --json ensures the output is a JSON object: {ok, data?, error?, exitCode}.
• Session Context: Use the BUNWV_SESSION environment variable to replace the --session <name> flag.

To eliminate the startup cost of running multiple commands, use bunwv batch. This mode runs a sequence of commands within a single Bun process.

Input Format: Each line of stdin must be a JSON array of arguments. Output Format: Each response is an NDJSON envelope sent to stdout.

Error Handling:

• Use the --keep-going flag to ensure the full list of commands runs even if one fails. If any command fails in this mode, the process exits with code 6 (batch-partial).
• Without --keep-going, the batch process stops immediately at the first failure and returns that specific command's exit code.
• A successful batch returns exit code 0.

cat <<'EOF' | bunwv batch --session staging --keep-going
["navigate","http://localhost:3000/login"]
["click","--selector","input[name='email']"]
["type","me@example.com"]
["press","Tab"]
["type","hunter2"]
["submit","--button","Sign In"]
["wait-for","--url","/dashboard"]
["screenshot"]
EOF