Documentation

Browser-control

@nikcli-ai/browser-control drives headless Chromium sessions, the way computer-use drives desktops and terminal-control drives PTYs.

Overview

@nikcli-ai/browser-control is the headless browser engine that powers nikcli's browser tool and the TUI browser feature plugin. It exposes a browser-control CLI binary and ships a per-workspace background daemon that keeps one shared Chromium process alive across separate CLI invocations. The daemon auto-spawns on first use and self-terminates after 10 idle minutes.

The package is one of three sibling engines — alongside @nikcli-ai/computer-use and @nikcli-ai/terminal-control — that share the same CLI grammar, the same per-workspace daemon pattern, and the same evidence-bundle output.

What it is not

@nikcli-ai/browser-control is not the Playwright or chromium-bidi bindings themselves — both are dependencies. The package is the daemon, the session manager, the recording pipeline, and the PR-ready evidence-bundle format that wraps them.

CLI surface

Every command except bundle and install-skill is a thin RPC call against the background daemon. The session lifecycle is: start → goto / click / fill / … → snapshot / recording → stop → remove.

Terminal

bash

browser-control start NAME --url URL [--viewport 1280x800] [--record]
      browser-control list
      browser-control goto       NAME URL
      browser-control send       NAME (text|keys) VALUE
      browser-control click      NAME SELECTOR
      browser-control fill       NAME SELECTOR VALUE
      browser-control hover      NAME SELECTOR
      browser-control scroll     NAME DX DY
      browser-control wait       NAME (--text VALUE | --selector SEL
                                       [--state visible|attached|hidden|detached]
                                       | --idle | --stable [--ms N]
                                       | --timeout MS [--timeout MS])
      browser-control resize     NAME WIDTHxHEIGHT
      browser-control snapshot   NAME [--out FILE] [--format png|text|json]
      browser-control stop       NAME   # keeps entry queryable for --record video
      browser-control remove     NAME
      browser-control restart    NAME
      browser-control close-all

--record starts a webm capture that finalises only on stop; videoPath NAME reads it back afterwards. The webm is only readable after the session stops — the same model as the computer-use webm pipeline.

Auto-start daemon

The first CLI call in a workspace spawns the daemon if it isn't already running; the daemon exits on its own after 10 idle minutes. There is no separate start command for the daemon itself.

Recording & evidence

The recording pipeline captures real screenshots at a chosen frame rate and emits a versioned JSON file (RECORDING_VERSION). The renderer converts that JSON into MP4, GIF preview, single-frame PNG, and PR-ready Markdown — all from the same bundle command.

Terminal

bash

browser-control start-recording NAME --fps 1
      browser-control marker          NAME LABEL
      browser-control stop-recording  NAME
      browser-control recording-data  NAME   # current state, without stopping
      browser-control videoPath       NAME   # path to the --record webm; only after stop

      browser-control bundle \
        --screenshot ./snap.png \
        --out ./artifacts/browser \
        --link-base artifacts/browser \
        --result passed \
        --title "Browser verification" \
        --summary "The browser action completed successfully."

Pass --recording ./recording.json instead of --screenshot when you want the bundle derived from a recorded run. The bundle accepts --at-marker NAME, --at-ms MS, --video FILE (webm from a --record session — takes priority over frames), --trace FILE, --include-trace, --no-preview, and --json.

Evidence manifest

Every bundle writes a manifest.json plus a pr.md ready to be appended to a pull request description. Use --json to print the bundle manifest without writing any files — useful when a test harness wants to consume the output programmatically.

Agent integration

The browser tool (packages/nikcli/src/tool/browser-control.ts) and the browser TUI feature plugin (packages/tui/src/feature-plugins/browser/) both delegate to the package — agents only need the tool name; humans only need the CLI. Permission gating for browser actions goes through the existing permission pipeline.

install-skill

Skill auto-registration

browser-control install-skill [--workspace DIR | --global] registers the bundled skill in .agents/skills. With --global the skill is installed into ~/.agents/skills so nikcli discovers it on every workspace on the machine.

pr.md

Bundle as PR evidence

The pr.md file embedded inside the bundle embeds an inline GIF preview and links the full MP4 — drop it straight into a pull request description. The local file:// preview line should never be pasted into the PR.

src/daemon.ts

Shared daemon

One Chromium process per workspace serves every active browser session; tearing the daemon down with close-all stops every session at once.

Source anchors

Concern	File
CLI binary	`packages/browser-control/src/cli.ts`
Background daemon	`packages/browser-control/src/daemon.ts` + `daemon-client.ts`
Session registry	`packages/browser-control/src/session.ts` + `manager.ts`
Recording	`packages/browser-control/src/recording.ts`
Evidence bundle	`packages/browser-control/src/evidence.ts`
Renderers	`packages/browser-control/src/render/json.ts`, `png.ts`, `text.ts`, `video.ts`
Tests	`packages/browser-control/test/evidence.test.ts`, `keys.test.ts`, `recording.test.ts`, `session.test.ts`
Agent tool wrapper	`packages/nikcli/src/tool/browser-control.ts`
TUI plugin	`packages/tui/src/feature-plugins/browser/`