SkillFoxx

Surf CLI

Surf drives your own Chrome from the command line: an agent opens pages, reads the accessibility tree, clicks and logs requests

  • 689 ★ on the repository
  • Last commit
  • MIT
CLI

Broad access

Why this level

  • Sees and changes any open page under your logins: mail, bank, admin panels
  • The network log records page requests, including headers with tokens
  • Remote mode hands browser control to any client holding an Ed25519 credential
All reasons and checks

nicobailon/surf-cliAuthor:nicobailon

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add cli/surf

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • Sees and changes any open page under your logins: mail, bank, admin panels
  • The network log records page requests, including headers with tokens
  • Remote mode hands browser control to any client holding an Ed25519 credential

This is third-party code. Review the repository files before installing.

What it does

Surf is a CLI through which an AI agent controls a browser on your machine. A Chrome extension connects to a native host, and the `surf` command talks to it over a Unix socket. The agent needs no MCP server: any program that can run commands will do. `surf go`, `surf read`, `surf click e5` and `surf snap` open a page, return an accessibility tree with element references, press an element and take a screenshot. Screenshots shrink to 1200 pixels automatically to save tokens, and actions return a screenshot on their own. Network traffic is logged while Surf is active, so the page's requests can be filtered and replayed. There is device emulation, animation and video recording, performance audits and semantic commands such as `locate.role` and `locate.text`. A separate feature queries ChatGPT, Gemini, Perplexity, Grok and AI Studio through logins already open in the browser, with no API keys. Several agents work in parallel through `session.ensure` sessions, and a browser on another Tailnet machine is reachable in remote mode with Ed25519 keys. A `surf` skill for agents installs together with the CLI.

Who it is for. Developers whose Claude Code, Codex or home-grown agent has to work in a browser that is already logged in, and people who would rather not configure an MCP server just to automate pages.

Good fit when

  • The agent has to walk a site under your login: a personal account, an admin panel, an internal service
  • The page exposes no API, so data has to come from the accessibility tree or network requests
  • You are building a layout and need mobile screenshots through device emulation without leaving the terminal
  • Several agents run at once and each needs its own tab without collisions
  • A social thread or feed is easier to fetch as records than to make an agent scroll through

Not a fit when

  • You need browser automation with no graphical shell: on a server without Xvfb and VNC the first login cannot be set up
  • The task runs on `chrome://` pages or in the Chrome Web Store, which Chrome does not expose
  • You want an isolated browser without your logins and cookies, since Surf works inside your own profile

Example request

Open the orders page in my Chrome, collect the numbers and totals from the table and save them as CSV

Limitations

Surf cannot drive `chrome://` pages or the Chrome Web Store, a Chrome restriction. The first CDP operation on a new tab takes 100 to 500 ms for the debugger attach. Linux support is marked experimental and untested in production, and a server needs Xvfb and VNC for the first login. The extension has to be loaded by hand in developer mode, and developer mode must stay on, otherwise Chrome disables a self-reloading extension. Queries to ChatGPT, Gemini and other services go through your own browser logins and follow their terms of use.

How to disable. `surf uninstall` removes the native host for Chrome and `surf uninstall --all` does it for every browser plus the wrappers. Remove the extension on `chrome://extensions` and the skill link in `~/.claude/skills/surf` by hand.

FAQ

How do I install Surf for Claude Code?

Run `npm install -g surf-cli` and `surf install`, load the extension from the printed folder in `chrome://extensions` and restart Chrome. The install command creates the skill link in `~/.claude/skills/surf` itself.

Does Surf need an MCP server?

No. The agent calls plain `surf` commands, so anything that can run a shell works: Claude Code, Cursor, scripts.

Which browsers are supported?

Chrome by default, plus Chromium, Brave, Edge, Arc and Helium. The `surf install --browser` flag picks one and `--browser all` installs every one.

How do I reach the browser from another machine?

Use remote mode over Tailscale: on the browser machine run `surf remote authorize` and `surf install --listen`, then give the client the Ed25519 credential file. Each client needs its own credential.

What does Surf do with ChatGPT and Gemini?

Commands such as `surf chatgpt`, `surf gemini` and `surf perplexity` send the question to the service site under your browser login and return the answer, with no API key.

Discussion

No questions or reviews yet.

CLI tools

An agent drives your real logged-in Chrome: a CLI, MCP and an extension with a separate tab group per session

CLIBroad access257

A CLI and MCP server that lets an agent drive your real Chrome with its logged-in sessions: 103 commands across 36 platforms plus browser automation

CLIBroad access6.3K
Official

A local browser automation platform: MCP server, CLI and skills so an agent can drive Chrome, fill forms and pull data from pages

MCP serverBroad access1.4K

A skill connects an agent to your Chrome through an extension and CLI for reading pages, managing tabs and verifying actions.

SkillBroad access649

A CLI and skill for driving Chrome from an agent: page snapshots, clicks, console, network and audits in compact output

CLIExtended access454
Official

Chrome control for AI agents: a local Go HTTP server with a CLI, MCP, profiles and a skill for Claude Code

CLIBroad access10.6K

README in short

The README opens with a comparison of Surf against other ways to drive a browser: a CLI instead of MCP, zero configuration, any agent. It then covers installation for several browsers and WSL2, remote access over Tailscale, a command reference by group, AI service queries, network capture, workflows and sessions. The end of the page lists environment variables, native host diagnostics and the socket protocol.

README badge

Report a problem