Surf CLI
A CLI that lets AI agents control Chrome — zero config, agent-agnostic, and battle-tested, so any agent that can run shell commands can drive the browser.
Security-conscious design is evident: default socket mode 600, Ed25519 mutual challenge-response for remote, revocable per-client credentials, opt-in group socket with warnings. However, any credentialed or local agent gets authority equal to a trusted user over the whole browser and host files, and sessions share the full Chrome profile (cookies, logins, history) by default — least privilege is only partial. No user confirmation mechanism for routine agent-driven browser actions; only playbooks require explicit --write and support --dry-run; deducted. Data flow transparency is good: transfer staging/cleanup, 256MiB limits, and remote: direct-path semantics are documented. Credential handling is solid (0600, revoke commands), but network capture automatically logs all requests and screenshots auto-save to /tmp with no redaction discussion; deducted to 2. Dependency security is supported by npm audit at critical level in CI and weekly CodeQL, but no lockfile or dependency policy is in evidence. External effects are well documented (FIFO lanes, exclusive browser-wide writers). Rollback is explicitly weak: the README states completed browser side effects are not rolled back; only cleanup has dry-run; deducted to 1. Attribution: author, MIT, repo and issue links are present; the unverified publisher is neither rewarded nor penalized per the publisher rule.
Self-consistency is good: uniform dot-command naming, shell tests assert migration hints for renamed commands, and README/package./tests agree. Dependency availability is documented: optional deps (magick/convert, ffmpeg on PATH), pinned Chrome for Testing and Node in CI. Failure messages are the standout: integration tests assert socket diagnostics ('Socket connect failed', surf doctor hint, SURF_SOCKET note) and recovery commands are printed verbatim (Recovery: surf session.reopen research) — full marks.
Audience and scenarios are thoroughly covered: AI agents and shell scripts, navigation, forms, iframes, multi-agent sessions, remote Tailnet, recording, performance audits. Capability boundaries are largely documented (50+ commands, restricted-page warnings, transfer boundary rejections, no remote on Windows native host), but mostly as prose lists without programmatic capability negotiation; 2. Trigger precision is high: required flags (--idle-after, --selector), precedence rules (--remote over SURF_REMOTE), and preconditions are precisely specified. Environment fit is excellent: macOS/Linux/Windows, WSL2 both directions, package-manager env vars, six supported browsers.
Information architecture is excellent: layered help (--help/--help-full/--help-topic/--find) and a README progressing from rationale to install to usage to remote operations. Install notes are exhaustive (WSL2, package-manager paths, uninstall variants) — full marks. Naming stability is backed by tests asserting migration hints. Examples are abundant and tested (help contains Examples). Known limitations are substantially disclosed (no rollback of side effects, POSIX-only remote listeners, shared-profile risk) but scattered rather than consolidated; 2. LICENSE is complete MIT and consistent with badge and package. — full marks. Version 2.18.0 in package. and CHANGELOG referenced, but the changelog content is not in evidence and versioning policy is unstated. Maintenance: single author with a complete CI matrix (lint/test/typecheck/real-Chrome E2E/audit), but no CONTRIBUTING, security policy, or governance; 2.
Output usability is strong: JSON modes, byte caps, compact/depth trimming, stderr metadata ([surf tab=42 window=7 queued=ms]), auto-capture screenshots reducing round-trips — corroborated by tests; full marks. Marginal value is clear: agent-agnostic CLI over Unix socket plus native messaging genuinely differs from MCP or relay approaches, and cookie-based AI queries without API keys are a distinctive capability. Cost-benefit: token-saving defaults are plausible but unquantified, and safe multi-agent use requires additional isolation setup; 2.
Claim traceability is moderate: protocol, error messages, and scheduling semantics cross-check against in-repo tests; but 'battle-tested' is an assertion and competitor claims in the comparison table are unverifiable from the repo. Cross-source consistency: README, package., CI workflows, and shell/e2e tests show no contradictions, though coverage of all 50+ commands is not demonstrated. Fact/inference separation: most statements are concrete, but marketing phrasing ('saves tokens') is mixed with specifications without distinction. This is a static review with no execution; confidence is low.
- Any agent holding a surf credential or local socket access has authority equal to a trusted user over the browser, including cookies from logged-in sessions; multi-agent sessions share profile state unless you set up separate profiles and native hosts.
- Completed browser side effects are not rolled back; use --dry-run and validate write playbooks in low-risk environments first.
- Network capture automatically logs all requests (potentially sensitive tokens) and screenshots auto-save to /tmp; assess on-disk and log-retention risk in sensitive environments.
- Publisher identity is unverified and maintenance depends on a single author; evaluate responsiveness and update path before enterprise adoption.
- This is a static source review with no executed tests; claims such as 'battle-tested' are not independently verified.
What does this agent do, and when should you use it?
Surf (npm package surf-cli) is a command-line tool that lets AI agents control Chrome via a Unix socket, a Chrome extension, and a native messaging host, executing most operations through the Chrome DevTools Protocol. It requires no MCP servers or relay processes: after loading the extension and running surf install, it works with Claude Code, GPT, Gemini, Cursor, or plain shell scripts. The CLI exposes 50+ commands covering navigation, accessibility-tree reading, clicking, form filling, screenshots, iframe switching, device emulation, network request capture, GIF/video recording, and performance auditing. A distinguishing feature is the ability to query ChatGPT, Gemini, Perplexity, Grok, Kimi, and AI Studio using existing browser logins, with no API keys. It also supports remote control over Tailscale secured by mutual Ed25519 challenge-response authentication, and the project is MIT-licensed.
Surf connects the CLI to a browser extension through Chrome native messaging, listening for JSON requests on /tmp/surf.sock (or //./pipe/surf on Windows). Core operations include: surf go for navigation, surf read to get the accessibility tree plus visible text (with --depth, --compact, --max-bytes to shrink output), surf click/type/scroll/select to interact via element refs (e5), CSS selectors, or semantic locators (locate.role/locate.text/locate.label), and surf screenshot/snap which auto-saves to /tmp resized to 1200px. It automatically captures all network requests, queryable via surf network filters, network.body for response bodies, and network.export for HAR files. surf do runs multi-step pipe-separated workflows (with JSON workflow files, loops, and step outputs), and the playbook system provides reusable site operations with fallbacks. surf chatgpt/gemini/perplexity/grok/kimi/aistudio invoke AI services through your browser login, and surf oracle manages durable, persistent ChatGPT consult jobs. It also offers session.ensure durable sessions for multi-agent concurrency, frame.switch for iframes, emulate.device, record for GIFs, and perf-audit for performance timelines.
- A developer using Claude Code or another AI coding agent who needs real-browser end-to-end verification (login, forms, clicks) without configuring an MCP server
- An engineer debugging web APIs who uses surf network and network.export to filter, inspect, and replay captured requests without manually setting up interception
- A user who wants AI answers via existing browser sessions without applying for API keys, using surf chatgpt/gemini/grok directly
- A team running multiple parallel agents, assigning each a dedicated tab via SURF_SESSION and session.ensure to avoid interference
- A researcher driving a browser on another Tailnet machine, configured with surf remote authorize and --listen for Ed25519-authenticated remote access
- A developer producing interaction demos with surf record (animated GIF) and surf video (WebM/VP9 via ffmpeg)
What are this agent's strengths and limitations?
- Agent-agnostic: pure CLI commands over a Unix socket, callable from Claude Code, GPT, Cursor, or shell scripts with no MCP setup or relay processes
- Battle-tested: built by reverse-engineering production browser extensions and methodically tested on agent-hostile pages like Discord settings, with graceful fallback from CDP to the chrome.scripting API
- Agent-optimized defaults: screenshots auto-resize to 1200px to save tokens, actions auto-capture screenshots to save round-trips, and errors on restricted pages warn instead of fail
- Unique capability: queries ChatGPT/Gemini/Perplexity/Grok/Kimi through browser cookies with no API keys, plus automatic network capture with HAR export built in
- Multi-agent ready: session.ensure provides durable sessions, per-tab FIFO scheduling, and browser-wide writer exclusion, with a Tailscale remote mode secured by mutual Ed25519 authentication
- Requires manually loading an unpacked Chrome extension and installing the native host, then restarting the browser — more setup friction than hosted alternatives
- Cannot automate chrome:// pages or the Chrome Web Store (Chrome restriction); first CDP operation on a new tab costs ~100-500ms for debugger attachment
- Cookie-based AI queries depend on provider website UI structure; the provided surf grok --validate troubleshooting command implies fragility when UIs change
- Linux support is explicitly experimental and untested in production; remote listeners are unsupported on Windows native-host wrappers and include no extra TLS/SSH tunnel, requiring Tailnet ACLs as defense in depth
- All sessions share one Chrome profile — cookies, authentication, and storage are visible across sessions, so hard isolation needs separate browser instances and SURF_SOCKET values
How do you install or deploy this agent?
- Install globally: npm install -g surf-cli
- Load the extension: open chrome://extensions, enable Developer mode, click 'Load unpacked', and paste the path printed by surf extension-path
- Install the native host (copy the extension ID from chrome://extensions): surf install <extension-id>; optionally --browser brave|helium etc. or --browser all; use --target linux in WSL2 for a WSLg Linux browser
- Restart Chrome and verify with surf tab.list
Troubleshooting: run surf doctor to check the socket path, native messaging manifest, and extension ID match.
How do you use this agent?
Basic flow: surf go "https://example.com" to navigate → surf read to get the page (returns stable refs like e1/e2/e3) → surf click e5 or surf type "text" --ref e12 to interact → surf snap for a screenshot (auto-saved to /tmp, resized to 1200px). Chain steps with surf do 'go "url" | click e5 | screenshot'. For shell-based agents, export SURF_SESSION="<unique-name>" and run surf session.ensure "$SURF_SESSION" about:blank before the first browser command to get a durable, isolated session. Run surf --help-full for all 50+ commands and surf --llm-context for a compact agent reference. AI queries require being logged into the respective service in Chrome (e.g., chatgpt.com, gemini.google.com), then e.g. surf chatgpt "summarize" --with-page.
How does this agent compare with similar options?
The README's own comparison table positions Surf against Manus (Manus-only, subscription, cloud), Claude Extension (Claude-only, subscription), DevTools MCP (requires MCP setup), and dev-browser (Claude skill, relay server). Surf's differentiators: it is the only option that is simultaneously agent-agnostic, zero-config, CLI-based, free, and able to invoke AI via browser cookies; Manus and Claude Extension lock into their ecosystems and charge, while DevTools MCP and dev-browser need extra setup and are tied or partial to specific agent ecosystems.