Enable AI agents to control browsers via shell commands
The tool converts web pages into text for AI to read, then uses reference numbers within that text to click or fill specific elements. This turns the process of an AI agent navigating and interacting with a web page into a sequence of simple shell commands. Each command is handled as a short shell call, and the browser remains open between commands to allow for continuous tasks.
Reading pages as text and manipulating via reference numbers
The tool uses the snapshot command to return the current page as compressed text in the form of an accessibility tree. Each element is assigned a reference number such as @e1. The AI agent uses these reference numbers to execute commands like click or fill, then takes another snapshot to verify the results in a loop. If the page navigates or the DOM changes, the reference numbers become invalid, requiring a new snapshot. Clicking hidden elements or targets obscured by other elements will fail; to resolve this, the obscuring element must be removed first before retrying.
Background daemon and browser engine selection
Commands are passed to a background daemon that starts on the first execution, which controls the browser via the Chrome DevTools Protocol. Each --session has its own independent daemon and browser, and if no commands are issued for one hour, the headless browser is closed and terminated. The default browser is Chrome for Testing, but you can connect to a running Chrome instance using the --cdp option or select the Lightpanda or Obscura engines using --engine. It can also run Mobile Safari on the iOS simulator and integrate with cloud browser providers like Browserbase and Browserless.
Integration with agent harnesses
The CLI includes skills that match its version, allowing you to pass the core loop and reference number usage to the agent via the agent-browser skills get core command. Installing the skill into an agent harness with the npx skills add vercel-labs/agent-browser command ensures the installed skill always loads instructions for the current CLI version. If using an MCP client, you can also start a stdio-based MCP server with the agent-browser mcp command. This allows the agent to dynamically fetch the necessary instructions for browser automation tasks, preventing version mismatch issues.
Installation and platform support
You can install it globally via npm, use Homebrew, or run it immediately with npx. In Linux environments, you can install system libraries alongside it using the --with-deps option. Building from source requires Node.js 24 or higher, pnpm 11 or higher, and Rust.
Things to check before use
This tool is suitable for building an environment where AI agents interact with the web, and is particularly useful in scenarios requiring repetitive browser automation tasks. Before use, you should verify that Chrome for Testing downloads correctly and that the browser engine you intend to use is supported. Since reference numbers reflect the page state at the time of the snapshot, you should consider the snapshot update frequency for pages with dynamic content. The license is Apache-2.0, and security-related settings are managed through the authentication vault, domain allowlist, and action policies.
