What happens when a vibium CLI call is sent

Traced live from a session of this project's own session-isolation and timing investigations (2026-08-04) — not documentation, direct observation: ps -eww process inspection, daemon status checks, and round-trip timing measurements. Companion: the MCP-driven version.

The path, one command

sequenceDiagram
    participant B as Bash
    participant C as vibium CLI process
    participant D as vibium daemon
    participant X as Chrome for Testing
    participant P as Page (live site)

    B->>C: vibium click "button"
    activate C
    Note over C: fresh OS process,
spawned per call
    C->>D: connect via Unix socket
~/Library/Caches/vibium/vibium.sock
    activate D
    alt daemon not running
        C-->>D: lazy-launch daemon
    end
    alt no browser session yet
        D->>X: spawn Chrome, fresh temp
--user-data-dir profile
        activate X
    end
    D->>X: forward command over BiDi
(WebSocket)
    X->>P: dispatch the actual action
(click / eval / navigate)
    P-->>X: DOM state / JS return value
    X-->>D: BiDi response
    D-->>C: Unix socket response
    deactivate D
    C-->>B: print result, exit code
    deactivate C
    Note over X: browser process stays alive —
persists for the next command

Stage by stage

The CLI process is ephemeral, per call.

Every vibium <command> spawns a brand-new OS process. It does not persist between calls — that's the daemon's job. This is why per-call overhead exists at all: process spawn + connect + round-trip, every single time.

It talks to one shared daemon over a Unix socket.

Confirmed via vibium daemon status: one background process, one socket at ~/Library/Caches/vibium/vibium.sock. Both the CLI and an MCP server connect to the same daemon PID — but the daemon is a dispatcher, not a shared browser.

The daemon lazily launches itself and the browser.

Confirmed directly: stopping both, then running vibium go <url> cold, launches the daemon and a browser automatically — no explicit start required.

Each session gets its own Chrome process, own profile.

Confirmed via ps -eww: every vibium start (or MCP browser_start) launches a distinct Chrome-for-Testing process with a freshly-named temp --user-data-dir. Two concurrent sessions never share cookies, localStorage, or state — verified by setting a cookie in one and reading it from the other (empty).

Daemon ↔ browser speaks BiDi, not raw CDP.

Vibium is a WebDriver BiDi client (see vibium bidi-test) — the daemon relays the parsed command to Chrome over a BiDi WebSocket session, and Chrome executes it against the real page (click dispatch, JS evaluate, navigation).

The result retraces the same path back.

Page state / return value → Chrome → BiDi response → daemon → Unix socket → the waiting CLI process → stdout. The CLI process then exits; the daemon and the browser stay running for the next call.

What this costs, measured

170–250ms

round-trip for one CLI call, warm daemon+browser — measured directly this session with a loop of vibium eval 'performance.now()'.

~3,000ms

typical fixed setup cost (navigate + dismiss + fill + arm) before any timed action in a multi-step flow — several of these 170–250ms round trips stacked.

This is exactly why the CLI's own single-eval timing fix mattered (see timing-methodology.md): splitting "read the clock" and "fire the click" across two of these round trips left one full trip's worth of latency unaccounted for inside a window only ~500ms wide.