nicobailon/surf-cli

What it solves

Surf solves the problem of clunky browser automation for AI agents. Most existing tools require complex setup, are tied to specific AI providers, or break on real-world pages. Surf provides a simple command-line interface that any AI agent (or shell script) can use to control Chrome, with zero configuration and no dependency on a particular AI vendor.

How it works

Surf installs as a global npm package plus a browser extension. The extension connects to a native messaging host, which communicates with the CLI over a Unix socket. Agents issue plain commands like surf go, surf read, surf click, and surf screenshot to navigate and interact with pages. The tool reads the page's accessibility tree to produce a stable set of element references, supports iframe switching, semantic locators (by role, text, or label), and automatically captures screenshots after actions to reduce round-trips. It also captures network requests for later filtering and replay. For remote use, Surf can work over Tailscale with mutual Ed25519 authentication, and it supports TLS via reverse proxies. No API keys are needed because it can use the browser's existing cookies to query services like ChatGPT, Gemini, and more.

Who it's for

Surf is designed for developers building AI agents, automation pipelines, or anyone who wants to give an LLM agent web-browsing capabilities. It works with Claude Code, GPT, Gemini, Cursor, custom agents, or even plain shell scripts—anything that can execute commands.

Highlights

• Agent-agnostic: works with any tool that can run command-line commands, no provider lock-in.
• Zero configuration: install extension, run commands; no MCP servers or relay processes.
• Smart defaults: automatic screenshot resizing to 1200px to save tokens, and auto-capture after actions.
• Network capture: logs all requests, with filtering, search, and replay capabilities.
• AI via browser cookies: query ChatGPT, Gemini, Perplexity, and Grok without API keys.
• Robust iframe and frame handling, including diagnosis of frame mismatches.
• Remote access over Tailscale with strong Ed25519 authentication and optional TLS.
• Multi-browser support: Chrome, Brave, Edge, Arc, Helium, and Chromium, including WSL2.