vibesurfer

name: vibesurfer version: 0.1.14 binary: vs description: Agent-native headless browser. 20 primitives over a Unix-socket wire protocol. Real WKWebView (macOS), WebKitGTK 6 (Linux), or WebView2 (Windows) — all three engines CI-verified by 48 integration cells per platform. Optimistic concurrency via state tokens; tree-delta wire format; durable session/page/auth state in SQLite.

vibesurfer (binary: vs)

vs is a stateless CLI that talks to a daemon (vs serve, auto-spawned on first call) over a Unix socket. The daemon owns one long-lived browser engine on the OS main thread and a SQLite store at ~/.vibesurfer/state.db. Every primitive writes one audit row before returning — there's no opt-out, no untracked operation.

Short forms are the default in agent contexts

Every primitive has a short alias. Long forms exist for human-readable documentation; agent invocations should use the shorter form to save tokens. vs o https://... is the canonical shape for vs open https://..., not the other way around. The 19-primitive tables below lead with the short form and show the long form in parens; both work identically.

Frequent flags also have short forms: -S (--session), -j (--json), -F (--full), -s (--since), -n (--limit), -P (--page). The --token flag stays verbose because it's never typed by hand — you paste it from the previous read.

Use this tool when

• You need to drive a real browser to read or interact with a web app (login, scrape behind auth, click through SPA state).
• You need stable refs across snapshots so you can plan a multi-step interaction without scraping coordinates.
• You want persistent auth (cookies + storage) that survives across sessions, encrypted at rest.
• You want every action audited automatically — for replay, debugging, or compliance.

Don't use this tool for

• One-shot HTTP fetches with no DOM (use curl).
• Anything where you'd be parsing the rendered HTML by string matching — vs_view already gives you a typed accessibility tree with stable refs.
• Headless screenshots of fixed URLs with no interaction (overkill — though you can; see vs capture).

The 25 primitives

Wire form is vs_<name> (over the socket); CLI subcommand is <name> with hyphens. Each call returns a state envelope (@<token> success, ! CODE error, ? warning lines before the envelope).

Lifecycle (1–4)

Read (5–6, 13–14)

Mutate (7, 9–12, 17)

Cursor coordinates (20–23, v0.1.8+; trusted on all platforms in v0.1.11+)

Coordinate-addressed input with native trusted dispatch on every backend. macOS uses NSEvent, Linux uses XTest via the pure-Rust x11rb client (or libei via xdg-desktop-portal RemoteDesktop on pure Wayland), Windows uses SendMouseInput on ICoreWebView2CompositionController. Every resulting MouseEvent carries isTrusted = true in JS — Cloudflare / Google / hCaptcha can't tell the click from a real cursor. All four primitives take --mode={human,careful,robotic} (short -M), default human.

human synthesizes a Bezier path from the last known cursor position with Fitts-law arrival timing; the visible motion is indistinguishable from a real cursor reaching the target before the click. careful is a single-shot move. robotic is a teleport (no path).

Human-in-loop (24–25, v0.1.9+; MCP-aware in v0.1.12+)

For credentials, TANs, and any other value the agent must not see. The CLI reads from the local terminal the user is sitting at; the agent never receives the bytes.

When you need credentials, never call vs act fill with the value. Always call vs prompt-input <PAGE> <REF> --message="<label-from-snapshot>" --secret --token=<TOK> and let the user type. Include enough context in the message that they know which field they're filling (the field label from the snapshot is usually enough).

MCP / Claude Desktop / Codex (v0.1.12+): vs mcp has no tty, so the MCP version of vs_prompt_input enqueues a pending entry on the daemon and parks waiting for the value. The local user runs vs pending list (alias pe ls) to see what's queued and vs pending fulfill [<id>] (pe f) to type the value at their local tty — vs pending fulfill with no id auto-picks the single pending entry. vs pending cancel <id> (pe c) aborts. Once fulfilled, the agent's MCP tool call returns the new state token exactly as it would have for the local-CLI path.

Search / extract (8, 10, 18)

Capture / persist (15–16, 19)

Optimistic concurrency

Every read returns a state token. Mutations require the token in --token=<TOK>. Stale token → ! STALE_TOKEN <new> <reason>; you re-read and retry. There is no manual locking primitive. Don't bash-batch mutations against the same page without re-reading between them.

Idempotency

If you re-issue the exact same vs act (same ref, same op, same value, same before-token, same group) within ~5 seconds, the daemon recognizes the replay and returns ? idempotent_hit followed by the original success envelope — no double-click, no double-fill.

Auth flow

# First time (browser, real human)
vs session-open
PAGE=$(vs open https://app.example.com)
# ...log in via the page...
vs auth save "$PAGE" example-prod    # persists cookies + localStorage

# Tomorrow
vs session-open
PAGE=$(vs open https://app.example.com)
vs auth load "$PAGE" example-prod    # restores the session
# you're logged in

vs auth save runs an injected JS that snapshots document.cookie, localStorage, sessionStorage to JSON, then encrypts it with the master key (keyring entry, or a fallback file). On load, the daemon re-runs the JS in the inverse direction.

How the wire stays cheap

• Tree deltas, not re-dumps. First vs view after open returns the full tree. Subsequent calls return only what changed since the last token the agent saw.
• Stable refs. Every interesting element gets a sticky data-vs-ref integer that survives across snapshots — you can plan multi-step flows without re-discovering elements.
• Tab-separated lines, not JSON. Hot-path reads cost a fraction of equivalent JSON. Use --json only when you're inspecting by hand.

Common mistakes to avoid

• Don't omit --token on mutations. It's not optional — the daemon will reject with BAD_REQUEST if missing.
• Don't forget the session. vs --session=<id> overrides; otherwise it reads ~/.vibesurfer/active-session.
• Don't run multiple vs serve instances. Auto-spawn picks up the existing socket; if you kill it manually, restart by running vs serve directly.
• Don't expect engine-side timeouts to be exact. --timeout=5000 is a budget, not a deadline; the daemon may overshoot by a runloop tick (~50ms on macOS, ~10ms on Linux).

Capabilities by platform

All three engines are verified in CI by the same 48-cell integration suite; the matrix below tracks the few axes where engine behavior differs in observable ways.

Trusted clicks (v0.1.11+): every backend routes vs act click and the cursor primitives through native OS input dispatch so the resulting MouseEvent carries isTrusted = true — anti-bot fingerprinters (Cloudflare, Google, hCaptcha) cannot distinguish from a real cursor. The Linux libei path requires the user's compositor to support the RemoteDesktop portal and the user to grant a one-time consent prompt at process startup; detection falls through to XTest (X11 / Xwayland) and finally to untrusted JS el.click() if neither is reachable.

vs status reports the active backend's capabilities; the CLI surfaces the protocol error ENGINE_UNSUPPORTED if you try a primitive the active backend doesn't implement.

Where things live