Horse Browser 🐴

A browser where your agents live. Log in once; every agent you point at it inherits the session — and you watch them all on one live wall.

Every other tool hands each agent a throwaway browser. But you don't want throwaway — you want your browser, logged into your stuff, that agents quietly borrow. The catch: on macOS, every CDP command yanks the browser to the foreground (a known open sore across the big tools). Horse Browser fixes that — agents open tabs in the background, each in their own colored group, in a dedicated browser that coexists with your daily one and never steals your focus.

Why "horse"? Browse meant a horse grazing — nibbling shoots — long before it meant clicking links. A horse that browses is the original browser. And it rides in browser-harness: you harness a horse. 🐴

Setup

Install (macOS, Node 18+):

horse-browser is driven through browser-harness (a small Python tool it wraps), so install that first — the horse-browser install fails loudly without it:

uv tool install browser-harness      # or: pipx install browser-harness
npm install -g @pa1nd/horse-browser

The npm install fetches a dedicated Chrome for Testing (lives alongside your daily browser, never fights it for the dock), puts the horse-browser launcher on your PATH, and wires in the extension. Then start it and sign into your apps once — those logins persist for every agent:

horse-browser        # launches the dedicated browser, no focus steal

Prefer your own Chromium? export HORSE_BROWSER_BIN=/path/to/chromium before installing.

You don't have to install by hand. Paste into Claude Code or Codex:

Set up https://github.com/pA1nD/horse-browser for me.

Clone it, run ./install.sh, then add SKILL.md to my CLAUDE.md so you always use
bh_open to open tabs from now on.

install.sh does the same setup as the npm install, and additionally wires SKILL.md into your CLAUDE.md (the npm install prints that import line for you to add — see below).

Teaching agents the discipline

SKILL.md isn't an optional skill — it's a guardrail (open tabs with bh_open, never bare goto_url) that must be in context before the first browser call. So you register it by importing it into a CLAUDE.md, not as a load-on-demand skill.

Recommended — let claude-md.sh manage a small, marked block in your global ~/.claude/CLAUDE.md:

./claude-md.sh apply     # write/refresh the block (idempotent)
./claude-md.sh print     # just print it — to compare, or copy by hand
./claude-md.sh check     # is CLAUDE.md up to date? (exit 1 if drifted — good for a cron)

It imports both playbooks via stable paths that don't rot across reinstalls: browser-harness's through a symlink kept aimed at the current install (survives a different Python), and horse-browser's own — when installed via npm — through a Node-independent copy in ~/.config (the package dir sits under your Node-version manager and moves when Node changes; a checkout imports its SKILL.md live). install.sh refreshes both.

By hand — or just add the import yourself (global ~/.claude/CLAUDE.md, or a single repo's CLAUDE.md):

@~/path/to/horse-browser/SKILL.md

(Codex users: ~/.codex/AGENTS.md works the same way.) Either way, the agent loads the bh_open discipline automatically from then on.

Installed via npm? Don't import the package dir directly — it lives under your Node-version manager (…/fnm/node-versions/vX/…) and vanishes when Node changes. The installer prints a stable path to paste instead: @~/.config/horse-browser/skill.md (a Node-independent copy it keeps current).

How it stays out of your way

Sign into Gmail, GitHub, your dashboards, whatever — once — and every agent you point at :9223 inherits those sessions. No re-auth dance, no cookie juggling, no "paste your token" on every run. The catch with one shared browser is everyone trips over everyone, so three things keep it civil:

• Coexists with your daily browser. A separate browser (Chrome for Testing) — launching it never hijacks your everyday Chrome/Brave, and clicking yours never lands you in the agents' window.
• Focus-safe by construction. Tabs open in the background and activate through the extension instead of Target.activateTarget (which calls [NSApp activate] and yanks the browser over whatever you're doing). The page is told it's foregrounded via focus emulation, so nothing misbehaves.
• Per-session tab groups. Each agent's tabs live in their own colored group; you see whose-is-whose at a glance, humans and agents in one window.

(Browserbase, Steel, Hyperbrowser & co. solve scale by giving each agent its own throwaway browser. Great for the cloud; useless when you want one real browser, on your machine, that stays logged in. That's this.)

Watch them all — the Agent Monitor

Click the 🐴 toolbar button for a live 2×2 / 3×3 wall of screencasts — one tab per cell — so you can watch every agent browse at once on a big screen.

Built around stable slots: a tab keeps its cell, so the picture never shuffles under you. Activity lights up in place (a green pulse on the tab an agent just acted on) instead of reordering everything; the wall only changes membership when a tab has gone idle and a busier one is waiting. A theme-aware sidebar groups every tab by session — coloured Chrome-style groups (emoji + code), favicon rows, and a slot number on each on-wall tab so a row maps straight to its preview. Click any pane to jump to that tab. Pure read-only over CDP (a second client alongside whatever's driving), so it costs the agents nothing.

How agents drive it

horse-browser is a drop-in for browser-harness that brings the dedicated browser up first (launching if down, self-healing a frozen GPU after sleep) and points the harness at it — so agents never touch a port:

horse-browser <<'PY'
bh_open("https://example.com")   # own colored tab group, no focus steal
print(page_info())
PY

It owns the CDP endpoint, so the port lives in exactly one place (its config) — change it there and every agent follows. Under the hood it's just a dedicated browser speaking CDP, so any other CDP client can still attach the classic way:

horse-browser && export BU_CDP_URL=http://127.0.0.1:9223   # for an arbitrary CDP client

Agents open tabs with bh_open(url) (their own colored group, no focus steal) rather than bare goto_url (which clobbers whoever's focused). The discipline lives in SKILL.md — import it into a CLAUDE.md (see Setup) and agents follow it automatically.

What's inside

• extension/ — MV3 extension: the tab grouper, the Agent Monitor (sidebar collapsed by default), and a first-run welcome page.
• bin/horse-browser — the launcher and a browser-harness drop-in: ensures the browser is up (self-heals a GPU wedge after sleep), then runs your script against it. Also horse-browser status (versions + state) and horse-browser update (fetch the latest Chrome for Testing — it has no auto-updater — and restart onto it).
• install.sh — one-time setup; fetches the browser, registers the launcher + helpers.
• claude-md.sh — registers horse-browser's guidance in your ~/.claude/CLAUDE.md (apply/print/check), via a version-proof symlink to the browser-harness SKILL.
• SKILL.md — the agent's playbook (the bh_open discipline + a helper recipe it self-installs).

A thin, self-contained setup — browser-harness (or anything else speaking CDP) is just a consumer on port 9223.

License

MIT © pa1nd