Browser

🌐 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.