Agent‑Browser: A Lightweight Headless‑Browser CLI for AI Agents

Introduction

When the wave of AI‑driven development hits, the tooling around it must keep up. I’ve been building and testing a new headless‑browser CLI that lets agents—Claude, Gemini, Copilot, you name it—control a Chromium instance purely from the terminal. The project is called agent‑browser and it’s built by a single Vercel engineer over a weekend. It’s small, fast, and designed to be the simplest bridge between an LLM and a browser.

In this post I’ll walk through how to install it, pull an accessibility‑snapshot, drive interactions, and even compare it to the more heavyweight browser‑use ecosystem and the Playwright MCP server. By the end, you’ll know whether this lightweight tool is a good fit for your agent workflows.

Table of contents

## Table of contents

Quick Install

The binary ships with a pre‑built Rust executable for macOS, Linux, and Windows.

npm install -g agent-browser

After that the agent-browser command is immediately available. If you prefer to use it as a library in Node, the same NPM package exposes an API, but the CLI is what most agents use.

Tip – The Rust CLI is compiled for the most common architectures, so you don’t have to worry about cargo build. The Node.js fallback is only for platforms where Rust isn’t available.

Core Commands

The @ref notation comes from the snapshot output; we’ll explain that next.

Snapshot & References

The snapshot command returns a tree where each element is annotated with a unique reference ID (@e1, @e2, …).

{
  "type": "heading",
  "text": "Example Domain",
  "ref": "@e1"
},
{
  "type": "link",
  "text": "More information...",
  "ref": "@e2"
}

Because the snapshot is deterministic, agents can parse it and interact with exactly the same element without re‑querying the DOM. This is a huge win when agents need to reliably click or fill a form.

Why refs?

1. Deterministic – the same snapshot always returns the same refs.
2. Fast – no need to search the DOM again.
3. LLM‑friendly – the text representation is easy to feed to a language model.

The following screenshot shows a typical snapshot output with reference tags.

Sessions & Isolation

Each open spawns a fresh Chromium instance under its own Node.js daemon. That daemon stays alive across multiple commands until you close it. If you need multiple concurrent agents, just run multiple agent-browser instances—they will run in parallel and won’t interfere with each other.

A diagram illustrating how the Rust CLI talks to a Node.js daemon, which in turn drives a Chromium browser.

Demo: Fixing Dark Mode & Validation

I used a simple React login page to show off two common agent tasks:

1. Dark Mode – The page was only in light mode, so I asked an agent to toggle it.

   agent-browser open https://login.example.com
   agent-browser snapshot -i
   agent-browser click @e3   # the dark mode toggle
   agent-browser screenshot dark-mode.png
   

   The agent ran the above commands, took a screenshot, and confirmed the mode had switched.

2. Login Validation – The form accepted any input, so the agent added client‑side validation.

   agent-browser click @e5   # submit button
   agent-browser eval 'document.querySelector("input[name=email]").value = "bademail"'
   agent-browser click @e5
   agent-browser screenshot validation-error.png
   

   The agent then scripted a bash test that tried an invalid email, received an error, then corrected it and logged in.

Screenshot of the page before and after the dark mode fix, side by side.

Under the Hood

The tool’s architecture is intentionally minimal:

1. Rust CLI – Parses the user’s command line input into a JSON payload.
2. Node.js Daemon – Listens on a Unix socket, owns a Playwright instance, and forwards actions.
3. Chromium – Runs headless by default, but can be swapped out for a custom binary path.

Because the Rust binary stays running, command parsing is instant; the only latency comes from the IPC to the Node daemon and the actual browser action. This keeps the overall loop below 200 ms for most actions—a sweet spot for agent workloads.

Comparing to Other Toolchains

Browser‑Use

Browser‑Use is a full‑featured agent ecosystem with a marketplace of skills and an MCP server. It supports both Python and TypeScript SDKs, offers stealth browsing, and handles proxies, cookies, and file downloads automatically. However:

• It runs the entire Plan‑Action‑Observe loop inside its own runtime; the agent has to be wrapped in browser‑use’s SDK.
• It supports multiple browsers (Chromium, Firefox, Safari).
• The learning curve is steeper for simple “run a command” use cases.

When to use it – If you need advanced stealth, cloud‑managed sessions, or a unified marketplace of reusable skills.

Playwright MCP Server

The Playwright MCP server exposes a language‑agnostic protocol that agents can hit over HTTP. It’s great for:

• Distributed execution across many nodes.
• Fine‑grained Playwright features.
• Integration with existing CI pipelines.

But it requires setting up and managing the server, which can be overkill for a quick prototyping agent.

When to use it – When you’re already invested in Playwright and need a scalable, networked solution.

Agent‑Browser

• Pros

  • One‑line installation.
  • Zero runtime overhead; just a local CLI.
  • Deterministic refs for element targeting.
  • Fast (sub‑200 ms latency).
  • Works with any LLM via plain text commands.

• Cons

  • Only Chromium (no Firefox/Safari).
  • No built‑in stealth or proxy support.
  • Requires the agent to manage the command loop.

When to use it – When you need a lightweight, deterministic bridge between an LLM and a headless browser, especially for prototyping or local automation.

Use Cases

Final Thoughts

I’ve spent the last few weeks letting a handful of LLMs drive a React login form entirely through agent-browser. The deterministic ref system saved me a lot of trial‑and‑error, and the Rust‑backed CLI kept the loop tight. While it lacks some of the ecosystem niceties of Browser‑Use or the scalability of Playwright MCP, its simplicity makes it a compelling choice for local experimentation, rapid prototyping, and as a teaching tool for how agents can talk to a browser.

If you’re looking for a “drop‑in, run it, and watch the agent do the heavy lifting” experience, I highly recommend giving agent‑browser a spin. Install it, run a snapshot, and let your LLM ask a question like “Click the submit button” – the CLI will do it in a fraction of a second, returning a screenshot you can feed back into the agent for verification.

Happy hacking!