GitHub - cosinusalpha/webctl: Browser automation via CLI — for humans and agents · GitHub

Source: original

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

pip install webctl webctl setup # Downloads Chromium webctl init # Generate skills/prompts for your agents webctl init --global # Or install globally (works across all projects)

webctl init creates on-demand skills for Claude Code and Goose, and lean prompts for Gemini, Copilot, and Codex.

Supported agents and file locations Agent | Format | Location (project) | Location (global)

claude | Skill | .claude/skills/webctl/SKILL.md | ~/.claude/skills/webctl/SKILL.md goose | Skill | .agents/skills/webctl/SKILL.md | ~/.config/agents/skills/webctl/SKILL.md gemini | Prompt | GEMINI.md | ~/.gemini/GEMINI.md copilot | Prompt | .github/copilot-instructions.md | - codex | Prompt | AGENTS.md | ~/.codex/AGENTS.md claude-noskill | Prompt | CLAUDE.md (legacy) | ~/.claude/CLAUDE.md

Why skills? Skills are loaded on-demand — your agent only reads webctl instructions when actually doing web automation. This keeps your context clean for other tasks.

Select specific agents:

webctl init --agents claude,gemini # Only Claude and Gemini webctl init --agents claude-noskill # Legacy CLAUDE.md format

If your agent doesn't auto-detect the generated files, add this to your system prompt:

For web browsing, use webctl CLI. Run webctl agent-prompt for instructions.

Note: If a browser MCP is already configured, disable it to avoid conflicts.

Commands

Navigation & Observation

webctl navigate "https://..." # Structured data + page summary webctl navigate "https://..." --snapshot # Full a11y snapshot with @refs webctl navigate "https://..." --read # Readable markdown content webctl navigate "https://..." --search "query" # Find search box, type, submit webctl navigate "https://..." --grep "price" # Filtered a11y snapshot webctl back / forward / reload webctl snapshot --interactive-only # Buttons, links, inputs only webctl snapshot --within "role=main" # Scope to container webctl query "role=button name~=Submit" # Debug query webctl screenshot --path shot.png

Interaction

webctl click "Submit" # By text description webctl click @e3 # By @ref from snapshot webctl click "Submit" --snapshot # Click + return updated page state webctl type "Email" "user@example.com" # Smart targeting webctl type "Country" "Germany" # Auto-detects dropdowns webctl type "Search" "query" --submit # Type + press Enter webctl press Enter webctl do '[[...],[...]]' --snapshot # Batch multiple actions

Wait Conditions

webctl wait network-idle webctl wait 'exists:role=button name~="Continue"' webctl wait 'url-contains:"/dashboard"'

Session & Console

webctl status # Current state & error counts webctl save # Persist cookies now webctl console --count # Just counts by level (LLM-friendly) webctl console --level error # Filter to errors only

Core Concepts

Sessions

Browser stays open across commands. Cookies persist to disk.

webctl start # Visible browser webctl start --mode unattended # Headless (invisible) webctl -s work start # Named profile (separate cookies)

Element Queries

Semantic targeting based on ARIA roles — stable across CSS refactors:

role=button # Any button role=button name="Submit" # Exact match role=button name~="Submit" # Contains text (preferred)

Output Control

webctl snapshot # Human-readable webctl --quiet navigate "..." # Suppress events webctl --result-only --format jsonl navigate "..." # Pure JSON

Architecture

┌─────────────┐ Unix Socket ┌─────────────┐ │ CLI │ ◄────────────► │ Daemon │ │ (webctl) │ JSON-RPC │ (browser) │ └─────────────┘ └─────────────┘ │ │ ▼ ▼ Agent/User Chromium + Playwright

• CLI : Stateless, sends commands to daemon
• Daemon : Manages browser, auto-starts on first command
• Socket : $WEBCTL_SOCKET_DIR or OS default (see below)
• Profiles : ~/.local/share/webctl/profiles/

Socket paths Platform | Default

Linux | /run/user/<uid>/webctl-<session>.sock macOS | /tmp/webctl-<session>.sock Windows | %TEMP%\webctl-<session>.sock

Override directory with WEBCTL_SOCKET_DIR environment variable.

Security

webctl verifies that CLI commands come from the same user as the daemon:

Platform | Mechanism | Strength

Linux | SO_PEERCRED | Kernel-enforced UID check macOS | LOCAL_PEERCRED | Kernel-enforced UID check Windows | SIO_AF_UNIX_GETPEERPID + process token | Kernel-enforced SID check

All platforms use kernel-level credential verification. This prevents other users from controlling your browser session. Advanced Configuration

Custom Browser

Use a custom Chromium binary (skips managed installs):

webctl config set browser_executable_path /path/to/chrome

One-off override via environment:

WEBCTL_BROWSER_PATH=/path/to/chrome webctl start

Allow global Playwright even if versions mismatch (opt-in, use with care):

webctl config set use_global_playwright true

Clear overrides:

webctl config set browser_executable_path null webctl config set use_global_playwright false

Proxy Configuration

Configure HTTP/HTTPS proxy for corporate networks or CI environments.

Via environment variables (recommended for CI):

Standard proxy env vars (auto-detected)

export HTTPS_PROXY=http://proxy.corp.com:8080 export NO_PROXY=localhost,*.internal.com webctl start

Or use webctl-specific var (highest priority)

export WEBCTL_PROXY_SERVER=http://proxy.corp.com:8080

Via config file (persistent):

webctl config set proxy_server http://proxy.corp.com:8080 webctl config set proxy_bypass localhost,*.internal.com

For authenticated proxies

webctl config set proxy_username myuser webctl config set proxy_password mypass

Priority order : WEBCTL_PROXY_SERVER > HTTPS_PROXY > HTTP_PROXY > config file

Check and clear settings:

webctl config show # View all settings webctl config set proxy_server null # Clear proxy

Command Logging

Record all webctl commands and their output in shell-transcript format:

export WEBCTL_LOG=/tmp/webctl.log webctl navigate "https://example.com" webctl click "Submit" cat /tmp/webctl.log # Review transcript

Each command is logged with a $ prefix followed by its output, appended to the file.

Domain Policy

Restrict which domains the browser can navigate to. Edit your config file directly (webctl config show to find the path):

{ "domain_policy": { "enabled": true, "policy": { "mode": "allow", "allow": ["localhost", "*.mycompany.com", "github.com"], "deny": [] } } }

Modes:

Mode | Behavior

allow | Whitelist — only listed domains are permitted deny | Blacklist — all domains except listed ones are permitted both | Allow list checked first, then deny list

Domain patterns support glob wildcards (e.g., *.example.com). A built-in default deny list blocks known malicious patterns regardless of mode.

Container Deployment

Set WEBCTL_SOCKET_DIR to share the Unix socket between host and container (or between containers).

Daemon in Container, Client on Host:

mkdir -p /tmp/webctl-ipc

docker run -d --name webctl-daemon \ -u $(id -u):$(id -g) \ -v /tmp/webctl-ipc:/ipc \ -e WEBCTL_SOCKET_DIR=/ipc \ my-webctl-image python -m webctl.daemon.server

export WEBCTL_SOCKET_DIR=/tmp/webctl-ipc webctl start && webctl navigate "https://example.com"

-u $(id -u):$(id -g) ensures the socket file is owned by your host user.

Daemon and Client in Separate Containers:

docker volume create webctl-ipc

docker run -d --name webctl-daemon \ -v webctl-ipc:/ipc \ -e WEBCTL_SOCKET_DIR=/ipc \ my-webctl-image python -m webctl.daemon.server

docker run --rm \ -v webctl-ipc:/ipc \ -e WEBCTL_SOCKET_DIR=/ipc \ my-webctl-image webctl navigate "https://example.com"

No UID matching needed — both containers run as the same user.

Global installation with uv

uv tool install webctl uv tool run webctl

Linux system dependencies

playwright install-deps chromium

Or manually install libraries listed in Playwright documentation

License

MIT