Docs / Plugins

🌐 Browser (`structupath.browser`)

A drivable browser pane for Herdr, built around agent-browser. When a coding agent drives Chrome in one pane, herdr-browser gives you a live, human-visible view of that same session in another — inspect the page, watch console output and page errors, click real browser coordinates, type, scroll, navigate, and record, without leaving Herdr.

Repo: StructuPath/herdr-browser · Full reference: the repo README

Session model

One browser session per Herdr workspace (herdr-ws-<workspace-id>), so browser state never leaks between workspaces. The exact session name appears in the viewer header. Two ways in:

Action	What
`open`	Viewer onto the shared agent browser session. With no URL = view-only attach.
`browse`	Personal interactive browser (separate Carbonyl Chromium — does not share the agent's session). Type the URL in its address bar.
`record-start` / `record-stop`	Record the workspace session to WebM
`close`	Close every browser pane in the workspace and end its session

Everyday: menu → Open (or Browse) → drive it keyboard-first. Close with the close action or q in the pane. Cmd/Ctrl+click a localhost URL printed in any Herdr pane to open it in the workspace browser.

Passing a URL

Action-invoke can't pass a URL (herdr 0.7.x actions get no argv), so open with no URL attaches view-only. Set the URL either with u inside the pane, via a localhost Cmd/Ctrl+click, or from the CLI against the session shown in the pane header:

agent-browser --session herdr-ws-<workspaceId> open https://example.com

Viewer controls

Input	Action
`u`	Address prompt (`https://` assumed when omitted)
Click the screenshot	Real Chrome mouse events at that page coordinate
`i`	Type into the focused page element
`b` / `f`	History back / forward
`r`	Reload
`j` / `k` / Space / wheel	Scroll
`q`	Close the viewer pane

Requirements

Herdr ≥ 0.7.0, Node ≥ 20 (Node 22+ enables live WebSocket streaming)
npm install -g agent-browser && agent-browser install
Optional: chafa (ANSI rendering), carbonyl@next (the interactive Browse action)

Rendering auto-selects the strongest mode the terminal supports: Kitty graphics → ANSI symbols via chafa → text-only. Frames stream over WebSocket when available, with transparent polling fallback.

Troubleshooting quick hits

agent-browser is not installed — npm install -g agent-browser && agent-browser install
session … is not running — open a URL with u, click a localhost link, or start agent-browser with the session in the pane header
Text-only mode — install chafa or enable Kitty graphics ([experimental] kitty_graphics = true in config.toml, then herdr server reload-config)
Action failures — herdr plugin log list --plugin structupath.browser

See the README for configuration files, environment overrides, recording details, and the security model.