browser-companion

Browser Companion

A zero-dependency Node.js HTTP + WebSocket server that turns a directory of HTML fragments into a live-reloading preview, with browser→agent click event capture.

The skill ships a public CLI arkhe-preview placed in plugins/devtools/bin/. Any plugin's skill can invoke it as a bare bash command — no need to know the devtools install path.

Quick Start

# Start a server scoped to the current project
arkhe-preview start --project-dir "$(pwd)"

# Output (one JSON line on stdout):
#   {"type":"server-started","port":54123,"url":"http://localhost:54123",
#    "screen_dir":".../<id>/content","state_dir":".../<id>/state",
#    "session_dir":".../<id>","pid":12345}

# Tell the user to open the URL. Then write HTML to screen_dir:
echo '<h2>Hello</h2><button data-event="ok">OK</button>' > "$SCREEN/content.html"

# Browser auto-reloads. User clicks. Read events:
tail -f "$STATE/events.jsonl"

# When done:
arkhe-preview stop "$SESSION_DIR"

When to Use This

• Design / mockup loops — write HTML to screen_dir, browser shows it
• Multi-select / variant selection — give the user clickable options, read events.jsonl to learn what they picked
• Iteration on generated UI — overwrite fragment → instant reload
• Cross-plugin — any plugin's skill can call arkhe-preview directly; it lives in devtools but its CLI is on PATH whenever devtools is enabled

Core Commands

arkhe-preview start [options]      # Print {url, screen_dir, state_dir, session_dir, pid} JSON
arkhe-preview stop <session-dir>   # Graceful SIGTERM, falls back to SIGKILL
arkhe-preview status <session-dir> # {running, pid, url} JSON (always exits 0)
arkhe-preview --help               # Full option reference (USAGE.txt)

Common start options:

• --project-dir <path> — store under <path>/.claude/preview/<id>/ (default: /tmp/arkhe-preview-<id>/)
• --frame-template <path> — override default HTML frame
• --helper <path> — override default browser-side helper JS
• --port <N> — pin a specific port
• --owner-pid 0 — disable the watchdog (use idle timeout only)