# 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](/docs/tools) and the TUI [browser feature plugin](/docs/tui). 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](/docs/computer-use) and [@nikcli-ai/terminal-control](/docs/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
```

$ shell · paste into your terminal

`--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](/docs/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."
```

$ shell · paste into your terminal

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](/docs/tools) (`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](/docs/permissions) 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/` |

---

Source: https://nikcli-ai.dev/docs/browser-control