dev-browser-go

Token-light browser automation via Playwright-Go. CLI-first design for LLM agent workflows.

Uses ref-based interaction: get a compact accessibility snapshot, then click/fill by ref ID. Keeps context small. Single Go binary with embedded daemon.

Acknowledgments

Inspired by SawyerHood/dev-browser. ARIA snapshot extraction is vendored from that project. Thanks to Sawyer Hood for the original work and ref-based model.

Thanks to Daniel van Dorp (@djvdorp) for early contributions (pip packaging, console logs) and legacy MCP cleanup work.

Comparison

Why CLI (no MCP)

• Lower latency: direct subprocess, no JSON-RPC framing
• Easier debugging: run commands yourself, see stdout/stderr
• Simpler integration: any agent that can shell out works
• Persistent sessions: daemon keeps browser alive between calls

Install

Playwright browsers are required. The Nix package wraps PLAYWRIGHT_BROWSERS_PATH to the packaged Chromium; dev shell includes the driver/browsers. Outside Nix, Playwright-Go will download on first run.

Nix (flake)

nix run github:joshp123/dev-browser-go#dev-browser-go -- goto https://example.com
nix profile install github:joshp123/dev-browser-go#dev-browser-go

Go build

go build ./cmd/dev-browser-go
./dev-browser-go goto https://example.com
./dev-browser-go snapshot

CLI Usage

dev-browser-go --help              # Full usage
dev-browser-go --version           # Version

dev-browser-go goto https://example.com
dev-browser-go snapshot            # Get refs (e1, e2, ...)
dev-browser-go click-ref e3        # Click ref
dev-browser-go fill-ref e5 "text"  # Fill input
dev-browser-go screenshot          # Capture
dev-browser-go press Enter         # Keyboard

The daemon starts automatically on first command and keeps the browser session alive.

Global Flags

--profile <name>    Browser profile (default: "default", env DEV_BROWSER_PROFILE)
--headless          Run headless (default)
--headed            Disable headless
--window-size WxH   Viewport size (default 7680x2160 ultrawide)
--window-scale S    Viewport scale preset (1, 0.75, 0.5)
--output <format>   Output format: summary|json|path (default: summary)
--out <path>        Write output to file (with --output=path)

Environment Variables

Commands

Run dev-browser-go <command> --help for command-specific options.

Integration with AI Agents

Add to your project's agent docs (or use SKILL.md directly):

## Browser Automation

Use `dev-browser-go` CLI for browser tasks. Keeps context small via ref-based interaction.

Workflow:
1. `dev-browser-go goto <url>` - navigate
2. `dev-browser-go snapshot` - get interactive elements as refs (e1, e2, etc.)
3. `dev-browser-go click-ref <ref>` or `dev-browser-go fill-ref <ref> "text"` - interact
4. `dev-browser-go screenshot` - capture state if needed

Element-level capture:

dev-browser-go bounds ".vault-panel" --nth 1
dev-browser-go screenshot --selector ".vault-panel" --padding-px 10

For detailed workflow examples, see SKILL.md.

Integration with Codex

Codex can use the CLI directly via its shell access. Example prompt:

Use dev-browser-go to navigate to example.com and find all links on the page.

Available commands:
- dev-browser-go goto <url>
- dev-browser-go snapshot [--no-interactive-only] [--no-include-headings]
- dev-browser-go click-ref <ref>
- dev-browser-go fill-ref <ref> "text"
- dev-browser-go screenshot
- dev-browser-go press <key>
- dev-browser-go console [--since <id>] [--limit <n>] [--level <lvl> ...]

Tools

• goto <url> - navigate
• snapshot - accessibility tree with refs
• click-ref <ref> - click element
• fill-ref <ref> "text" - fill input
• press <key> - keyboard input
• screenshot - save screenshot
• bounds - get element bounds (selector/ARIA)
• console - read page console logs (default levels: info,warning,error; repeatable --level)
• save-html - save page HTML
• wait - wait for page state
• list-pages - show open pages
• close-page <name> - close named page
• call <tool> - generic tool call with JSON args
• actions - batch tool calls from JSON
• status / start / stop - daemon management

Versioning & Releases

• Simple SemVer tags (v0.y.z for fast moves; bump to v1.0.0 once stable).
• GitHub Release on each tag with the single Go binary (dev-browser-go) and checksums.
• Nix flake outputs follow the tag; no extra artifacts.

License

AGPL-3.0-or-later. See LICENSE.

Vendored code from SawyerHood/dev-browser is MIT licensed. See THIRD_PARTY_NOTICES.md.