webctl

webctl

Browser automation for AI agents and humans, built on the command line.

pip install webctl
webctl navigate "https://example.com"   # Auto-starts browser, returns page data
webctl click "Sign in"                  # Click by text description
webctl snapshot                         # See all elements with @refs
webctl stop                             # Closes browser and daemon

Why CLI Instead of MCP?

MCP browser tools have a fundamental problem: the server controls what enters your context. With Playwright MCP, every response includes the full accessibility tree plus console messages. After a few page queries, your context window is full. This leads to degraded performance, lost context, and higher costs.

CLI flips this around: you control what enters context.

# Filter before context
webctl snapshot --interactive-only --limit 30      # Only buttons, links, inputs
webctl snapshot --within "role=main"               # Skip nav, footer, ads

# Pipe through Unix tools
webctl snapshot | grep -i "submit"                 # Find specific elements
webctl --format jsonl snapshot | jq '.data.role'   # Extract with jq

Beyond filtering, CLI gives you:

Capability	CLI	MCP
Filter output	Built-in flags + grep/jq/head	Server decides
Debug	Run same command as agent	Opaque
Cache & Cost	webctl snapshot > cache.txt	Every call hits server
Script	Save to .sh, version control	Ephemeral
Human takeover	Same commands	Different interface

See also: MCP Considered Suboptimal — a community knowledge base collecting CLI-over-MCP patterns and alternatives.

---

Benchmarks

Head-to-head comparison of webctl vs agent-browser (Vercel's browser cli) across 4 real-world web tasks. Both tools use Claude Opus as the driving agent.

Task	webctl				agent-browser
	Score	Turns	Tokens	Cost	Score	Turns	Tokens	Cost
Amazon product lookup	9/10	11	119k	$0.25	9/10	18	247k	$0.28
Spiegel.de headlines	9/10	7	62k	$0.14	8/10	5	47k	$0.12
Google Maps restaurants	8/10	9	106k	$0.22	7/10	13	185k	$0.29
DuckDuckGo search	8/10	4	29k	$0.11	4/10	17	253k	$0.36
Average	8.5/10	8	79k	$0.18	7.0/10	13	183k	$0.26

webctl achieves higher quality scores on all 4 tasks at lower cost. Landmark-aware snapshots collapse navigation/sidebars and prioritize content, while automatic fallbacks (cookie dismiss, scroll-to-find, overlay retry) handle complex sites without extra agent turns.

What makes it fast

• Structured data first: navigate extracts JSON-LD/Open Graph metadata (price, rating, author, etc.) before touching the accessibility tree — often enough to answer without a full snapshot
• Landmark-aware filtering: Collapses nav/footer/sidebar landmarks so agents see content, not chrome
• Smart network idle: Custom load detection that ignores media streams and websockets — pages with video/analytics don't block loading
• Act + observe in one turn: --snapshot flag on click/type returns the updated page state, saving a round-trip

Benchmark details

Setup: Each task runs Claude Opus with a single tool (webctl or agent-browser), a $1 budget cap, and no human intervention. Quality is scored 0–10 by a separate Claude evaluation call.

Tasks:

1. Amazon product lookup: Find price and shipping for a specific product on amazon.de
2. Spiegel.de headlines: Extract top 5 headlines from a German news site
3. Google Maps restaurants: Find vegan Chinese restaurants in Berlin rated >4 stars
4. DuckDuckGo search: Search for penguin fan sites and return top 3 results

Run benchmarks yourself: bash benchmarks/bench_run.sh

---

Agent Integration

Option A: Install the skill (works across Claude Code, Cursor, Codex, Gemini CLI, Copilot, Goose, Windsurf, and OpenCode)

npx skills add cosinusalpha/webctl

This installs the skill file. Your agent will install the webctl package automatically on first use.

Option B: Install via pip