Architecture

reins is three small pieces with one narrow contract between them. Everything runs on your machine, and everything binds 127.0.0.1.

The CLI

The CLI is the entire interface: reins tabs, reins click, reins screenshot, and the rest of the command set. Agents use it because they already have a shell — no MCP server to register, no per-agent setup. A skill (npx skills add karnstack/reins) teaches agents the loop.

The daemon

The daemon is invisible plumbing. Any CLI command spawns it on demand; it exposes an HTTP /rpc endpoint for the CLI and holds the WebSocket that extensions dial into. One daemon serves any number of browsers. reins kill stops it, and logs live in ~/.reins/logs/.

The extension

A Manifest V3 extension. Its service worker executes commands against tabs through chrome.debugger — the Chrome DevTools Protocol — and an offscreen document holds the persistent WebSocket to the daemon, because MV3 service workers are suspended when idle and can't keep long-lived sockets.

The extension discovers the daemon by probing a small set of candidate localhost ports and authenticates itself by its chrome-extension://<id> origin — a header the browser stamps itself, which web pages and other extensions cannot forge.

Multiple browsers

Install the extension in several Chromium browsers — Chrome, Brave, Edge, Arc, Dia — and each connects to the same daemon. reins tabs lists every tab with a browser id; pass --browser <id> only when more than one browser is connected. reins never guesses which browser you meant.

Element refs

reins snapshot assigns stable refs (e5: button "Submit") to interactive elements. Commands act by ref, which survives page repaints better than hand-written selectors — and a CSS --selector fallback exists for everything else.