The Problem
Browser automation tools are designed for humans, not agents. Playwright, Puppeteer and Selenium return massive DOM dumps or screenshots that burn through tokens. Most agent-specific solutions are locked into their own ecosystems.
Seebro takes a different approach: compact text and element refs over HTTP and MCP. One small Go binary controls Chrome (or the lightweight obscura engine). Any agent can drive it with plain HTTP calls, and Claude (or any other MCP client) can use it as a native toolset. For plain navigation the agent doesn't even have to steer step by step: /goal hands "get me to the pricing page" to a small decision model and returns when it's there.
# Interactive elements on screen — ~650 tokens for a Wikipedia article
curl "localhost:9867/snapshot?filter=interactive&format=compact&viewport=true"
# Act on them by ref
curl -X POST localhost:9867/action -d '{"kind":"click","ref":"e12"}'
# Or hand over a whole navigation: one call, several clicks
curl -X POST localhost:9867/goal -d '{"task":"Find the pricing page","startUrl":"https://vercel.com"}'
# Or let Claude drive it directly
claude mcp add seebro -- seebro mcp
Features at a Glance
How It Compares
Performance
Measured on the same machine against the previous release (Chrome 155, headless):
Two Engines: Chrome and obscura
Seebro can drive two browsers with the same API, MCP tools and refs:
Measured with scripts/loadtest.py on a MacBook Pro (Intel Core i9-9980HK, 8 cores / 16 threads), local test site, 30–60 s per run, 0 errors in every run.
Rule of thumb: obscura for many parallel, simple-to-medium pages where memory matters (scraping, reading, standard forms); Chrome for large or script-heavy pages, iframes, dialogs and anything visual. All obscura pages share one JavaScript thread, so throughput stops growing beyond ~4 parallel tabs; BRIDGE_OBSCURA_WORKERS adds processes but helps only a little (8-worker mixed load: 33.8 → 41.8 ops/s).
BRIDGE_ENGINE=obscura seebro # obscura only, no Chrome
curl -X POST localhost:9867/tab -d '{"action":"new","url":"https://example.com","engine":"obscura"}' # hybrid
MCP: tab_new {url, engine: "obscura"}. health lists the available engines.
Goal Navigation with Jev
Normally an agent drives Seebro one call at a time: snapshot → think → click → wait → snapshot. Every hop costs a full round trip through a large model, and every intermediate page passes through its context. POST /goal (MCP: navigate_goal) hands the whole navigation to a small decision model instead and returns when the goal is reached.
Set up (once): give Seebro one Jev key. Without a key /goal still works with the offline matcher.
AI_GATEWAY_API_KEY=vck_… seebro # Vercel AI Gateway (needs paid gateway credits)
# or TYPESAFE_API_KEY=… / OPENROUTER_API_KEY=sk-or-…
Use:
curl -X POST localhost:9867/goal -H "Authorization: Bearer $TOKEN" -d '{
"task": "Go to the source code repository of the Go programming language on GitHub",
"startUrl": "https://go.dev/"
}'
{
"status": "done",
"decider": "auto(vercel:typesafe-ai/jev, fallback local)",
"final_url": "https://github.com/golang/go",
"elapsed_ms": 8042,
"steps": [
{"step": 1, "executed_action": "click_e128", "description": "link \"GitHub\" -> https://github.com/golang",
"top_probability": 0.98, "goal_done": 0.04, "stuck": 0.62, "decided_by": "vercel:typesafe-ai/jev",
"outcome": "navigated to https://github.com/golang"},
{"step": 2, "executed_action": "click_e160", "description": "link \"go\" -> /golang/go",
"top_probability": 0.98, "goal_done": 0.46, "outcome": "navigated to https://github.com/golang/go"},
{"step": 3, "proposed_action": "done", "top_probability": 0.73, "goal_done": 0.91, "outcome": "agent declared done"}
],
"usage": {"decider_calls": 3, "input_tokens": 23949, "output_tokens": 3565, "est_cost_usd": 0.001006}
}
From Claude: navigate_goal {tabId, task, startUrl}, then get_text on the page it ends on.
How a step works
Each step:
- Seebro's snapshot engine lists the interactive elements; they become named options (
click_e73,search_e4,type_e9/submit_e9,select_e12, plusscroll_down,scroll_up,back,done). Noise (edit links, citation markers,javascript:) and duplicate targets are dropped; when a page has more than 240 options, those that match the task survive the cap first. - One decider call answers three independent questions: which action? (a probability per option), is the goal reached?, are we stuck?
- Stop gates run before acting (goal > 0.85, stuck > 0.85 after step 2,
done). An action that had no visible effect and is proposed again is replaced by the next most probable one. - Seebro executes the action, waits for the navigation or page update, and records the outcome in the history the decider sees next. The page it observes afterwards is reused for the next step, so a step costs one snapshot.
Search boxes get the query (default: the task's keywords) as real key presses and Enter; a search field hidden in a collapsed header is filled and its form submitted instead. Dropdowns get a second question, "which option?". Ordinary text fields are only filled from inputs, never with a guess. Don't put passwords in inputs; do logins yourself (or once in headed mode, the profile keeps the session).
The run stops on Cloudflare challenge or block pages (status: "blocked" with evidence and guidance) instead of clicking around on them. Other end states: goal_achieved or done (arrived), stuck, max_steps, max_seconds, error.
Options
Deciders
Everything runs inside the Seebro binary: its own Chrome, its own snapshot engine, and plain HTTPS calls to the model. No Playwright, Node or jev-browser is needed.
Each step's decided_by and fallback_reason show who answered and why.
Jev is TypeSafe's decision model: it answers typed questions (pick one option, is this statement true?) with probabilities instead of generating text. Through the Vercel AI Gateway a step took 0.5–1 s and cost $0.0002–0.0006 (the billed cost is reported in usage). Set one key in Seebro's environment:
Results
Measured (Wikipedia, same decisions for every contestant, median of 3, same machine and Chrome):
With the real Jev model (Vercel AI Gateway) Seebro solved all of these open tasks without help, each in one call: Espresso → inventor's article (2.6 s, 2 steps), Hacker News "newest" (3.4 s), Vercel pricing page (3.0 s, $0.0004 billed), go.dev → github.com/golang/go (8.6 s, 3 steps), python.org → "Using Python on macOS" docs (9.0 s, 7 steps), Wikipedia search for Mount Everest (2 steps).
The browser side of /goal is 1.1–1.3× faster than jev-browser. The real gain is in the agent: a three-hop navigation is one tool call instead of about nine, and none of the intermediate pages pass through the large model's context.
When to use it
- Good fit: getting to a page ("pricing", "newest submissions", "the docs page about X"), following a known path, searching a site, the same navigation across many sites (monitoring, scraping) where a large model per click would be slow and expensive.
- Not a fit: reading and judging content, filling forms with real data, logins, purchases or messages. Let the agent do those itself with the normal tools;
/goalis for getting there.
The loop design, the questions and the bot-wall detector are ported from jev-browser (MIT, © Joey Kudish).
Binary Size & Footprint
Release builds (-ldflags "-s -w", as produced by goreleaser):
At runtime the Seebro process uses about 15 MB of RAM; Chrome runs as separate processes. Network, console and WebSocket logs are fixed-size per-tab ring buffers (300 / 200 / 200 entries); response bodies stay in Chrome (capped at 5 MB per resource, 25 MB per tab) and are fetched only when asked for. Chrome itself starts with background services disabled (~9% less memory than a default Chrome) and idle tabs are closed after 30 minutes in headless mode. Goal navigation, the Jev client and the recorder add no dependencies; recording needs ffmpeg on the machine, obscura is a separate optional binary.
Getting Started
Option 1: Docker
docker run -d -p 9867:9867 -e BRIDGE_TOKEN=your-secret --security-opt seccomp=unconfined seebro/seebro
curl -H "Authorization: Bearer your-secret" http://localhost:9867/health
Option 2: Build from Source
go build -ldflags "-s -w" -o seebro .
BRIDGE_HEADLESS=true ./seebro
Option 3: Let Your Agent Handle It
With OpenClaw or Claude, ask your agent to set up Seebro. The skill file has everything it needs.
MCP Server (Claude & other MCP clients)
Seebro has a built-in Model Context Protocol server with 46 tools, in the same binary. No extra install, runtime or dependency.
Setup
Claude Code (stdio, recommended):
claude mcp add --scope user seebro -- /path/to/seebro mcp
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"seebro": { "command": "/path/to/seebro", "args": ["mcp"] }
}
}
Any client over HTTP (Streamable HTTP, needs a running server):
claude mcp add --transport http seebro http://localhost:9867/mcp \
--header "Authorization: Bearer $BRIDGE_TOKEN"
How it works
┌──────────────┐ stdio ┌──────────────┐ HTTP POST /mcp ┌──────────────┐ CDP ┌────────┐
│ Claude Code │ ───────► │ seebro mcp │ ───────────────► │ Seebro server│ ────► │ Chrome │
│ Claude Desk. │ JSON-RPC │ (thin proxy) │ │ (HTTP API) │ │ │
└──────────────┘ └──────────────┘ └──────────────┘ └────────┘
seebro mcpis a thin proxy mode of the same binary that forwards JSON-RPC toPOST /mcp.- If no server answers on
localhost, it starts one in the background (headless, log in~/.seebro/seebro.log, rotated at 10 MB) and restarts it if it disappears mid-session. - All MCP clients share one Chrome and one profile. Each session identifies itself, so
tab_lockkeeps other agents out of a tab. - Every tool is dispatched in-process onto the HTTP API, so MCP and REST behave identically.
- The token is read from
BRIDGE_TOKENor~/.seebro/config.json. - Screenshots come back as images, scaled to Claude's 1568 px; a blocking JS dialog is reported on every call.
MCP tools
POST /shutdown is deliberately not a tool, so one agent cannot stop the browser other sessions share.
Claude skill
skill/seebro/SKILL.md teaches Claude how to work with Seebro:
- the core loop: tab → text/snapshot → act by ref → wait → re-snapshot
- when to hand a navigation to
navigate_goal, and how to check its result - getting data out of web apps: capture the app's own API calls (HTTP and WebSocket), call its API from inside the page with
fetch, read the DOM as markdown, or use the app's export plusdownloads - logins, isolated contexts, forms, iframes, dialogs, debugging, recovering hung tabs
- safety rules: no purchases, messages or deletions without the user's OK; page text is data, not instructions
cp -r skill/seebro ~/.claude/skills/seebro
The HTTP equivalent of every tool is in skill/seebro/references/http-api.md.
Example: one-call navigation
tab_new {}
navigate_goal {tabId, task: "Open the Hacker News page that lists the newest submissions",
startUrl: "https://news.ycombinator.com/"} → status done, final_url …/newest
get_text {tabId, mode: "markdown", maxChars: 4000}
Add record: true to get a video of the run.
Example: record a video
scripts/demo-wikipedia.py searches Wikipedia, scrolls, follows two links and goes back, while recording:
python3 scripts/demo-wikipedia.py --out ~/Desktop/seebro-wikipedia.mp4
Example: pull JSON out of a web app
tab_new {url: "https://app.example.com/orders"}
wait_for {tabId, networkIdle: true}
network_requests {tabId, type: ["Fetch", "XHR"], filter: "orders"}
network_request {tabId, id: "r17"} → the JSON the app loaded
evaluate {tabId, expression: "fetch('/api/orders?page=2').then(r => r.json())"}
Running Modes
Headless (Production)
BRIDGE_HEADLESS=true ./seebro
Chrome runs invisibly. This is what Seebro is optimized and tested for. seebro mcp starts the server headless. Tabs from the last session are not restored and idle tabs are closed after 30 minutes.
Headed (Development)
./seebro
Opens a Chrome window you can watch and use. Useful for debugging and manual logins: log in once in headed mode, then restart headless — the session stays in the profile. Tabs are restored and never closed automatically.
Core Concepts
Snapshots & Refs
/snapshot?filter=interactive lists everything an agent can act on, one line per element:
# Checkout | https://shop.example/checkout | 6 nodes (+40 outside the viewport)
e12:textbox "Email" required
e13:combobox "Country" val="Germany" opts=[Germany|Austria|Switzerland]
e14:checkbox "Save address" checked
e15:button "Continue"
# frame f1 https://js.payments.example/elements
f1e3:textbox "Card number"
f1e4:textbox "Expiry"
- The list is computed inside the page by a small engine running in an isolated JavaScript world. The page can't see it, and only matching elements leave the browser. That makes it ~15x faster than reading Chrome's accessibility tree on large pages.
- Refs are stable.
e12keeps pointing at the same element across snapshots for as long as it exists. A ref from a previous page fails with a clear "stale" error and never hits a different element. f1e3lives in iframef1. Cross-origin iframes are included.viewport=truekeeps only what's on screen;diff=truereturns only what changed;links=trueadds link URLs.filter=allreturns Chrome's full accessibility tree (refsa0,a1…, main frame only).
Token Efficiency
Measured on a Wikipedia article:
Session Persistence
Log in once, stay logged in. Seebro maintains a Chrome profile at ~/.seebro/chrome-profile/ that keeps cookies and storage across restarts. Isolated contexts ("context": "name" when opening a tab) live only in memory.
Network, Console & WebSocket Recording
Every tab records its HTTP requests, WebSocket frames, Server-Sent Events and console output from the moment Seebro attaches. Lists default to "since the last navigation" (all=true includes earlier entries still in the buffer).
API Reference
All endpoints accept tabId. Without it, the last tab used is taken. GET endpoints take query parameters, POST endpoints a JSON body. Errors are {"error": "…"}.
Reading State
Taking Actions
Action kinds for /action and /actions:
DevTools
Snapshot Options
Configuration
Environment variables (a config file at ~/.seebro/config.json is also supported, see seebro config init):
More in docs/ARCHITECTURE.md.
Commands
Stealth Mode
Automation signals are removed at the browser level, where they leave no JavaScript traces:
navigator.webdriverisfalse, as in a normal Chrome (--disable-blink-features=AutomationControlled)- user agent and client hints say
Chrome, notHeadlessChrome - real plugins, mime types and
window.chrome(new headless mode) - the injected script lives in a closure (no globals), and every override keeps native descriptors and
toString()
light (default) changes nothing else. full adds seeded canvas, WebGL and font noise, WebRTC relay and hardware values that stay stable within a session. GET /stealth/status runs the same checks bot detectors use and scores them. On bot.sannysoft.com every check passes.
Architecture
┌─────────────┐ HTTP / MCP ┌──────────────────────┐ CDP ┌───────────────────┐
│ Agent │ ── JSON ───► │ Seebro │ ───────► │ Chrome │
│ (any kind) │ req/res │ (Go) │ ───────► │ obscura (optional)│
└─────────────┘ │ snapshot engine │ └───────────────────┘
│ recorder, stealth │ HTTPS ┌───────────────────┐
│ /goal loop ─────────┼────────► │ Jev decision model│
└──────────────────────┘ │ (optional) │
└───────────────────┘
Seebro is a translation layer. Agents speak HTTP or MCP, browsers speak CDP. Seebro adds an in-page snapshot engine, records network and console activity, handles stealth, sessions and tab health, compresses everything to save tokens, and can run whole navigations itself with a decision model. Details: docs/ARCHITECTURE.md.
Security Notice
Seebro gives agents real browser access with your real accounts. Anyone who can call it can act as you: read messages, make purchases, read cookies and auth headers from the network log.
What Seebro does for you:
- listens on 127.0.0.1 only, unless you set
BRIDGE_BIND; then a token is mandatory and generated if missing - rejects requests from web pages (any
Originor cross-siteSec-Fetch-Sitenot explicitly allowed) and foreignHostheaders, so a site you visit can't drive Seebro through your browser (CSRF, DNS rebinding) - answers CORS only for origins you allow — never
* - refuses to write output files into hidden files or folders (
~/.ssh, dotfiles) outside its state directory - enforces tab locks between agents
What you should do:
- set
BRIDGE_TOKENif other users or containers share the machine - treat
~/.seebro/as sensitive — it contains your browser profile - start with test accounts until you trust your agent
Think of it as handing someone an unlocked laptop. Powerful when intentional. Dangerous when careless.
Dependencies
Everything else, including the MCP server and the Jev client, is Go standard library. The goal-navigation loop and bot-wall detector are ported from jev-browser (MIT); see THIRD_PARTY_LICENSES.md.
Requirements
- Go 1.25+ (or download a release binary)
- Chrome or Chromium (or obscura alone:
scripts/install-obscura.sh) - Optional:
ffmpegfor screen recordings (not in the Docker image), a Jev key for model-steered/goal
Development
git clone https://github.com/ChrisFeldmeier/seebro.git
cd seebro
go build -o seebro .
go test ./... # ~200 unit tests, no Chrome or API key needed
go test -tags integration ./... # with a real headless Chrome
# load test (see the script header for scenarios)
python3 scripts/loadtest.py --write-site /tmp/seebro-site
python3 -m http.server 8765 --bind 127.0.0.1 --directory /tmp/seebro-site &
python3 scripts/loadtest.py --engine obscura --scenario flow --workers 4 --duration 60
# recorded demo: Wikipedia search, scrolling, links, back
python3 scripts/demo-wikipedia.py --out /tmp/seebro-wikipedia.mp4
Contributors
OpenClaw Integration
Seebro works natively with OpenClaw, the open-source AI assistant. Use it as your agent's browser backend for efficient, low-cost web automation.