.agents / browser

Ultra-fast, zero-Node Python CDP Browser MCP for AI coding agents.
Connects directly to your local Chrome, Edge, or Brave instance via native CDP. Headless by default.

Quickstart

1-Step Setup

pip install agents-browser && agents-browser init

Scaffolds ~/.agents/browser/, autowires MCP configurations into your installed IDEs, and registers assistant skills.

Source checkouts can also be installed and managed using vand.

Why .agents/browser?

Traditional browser automation MCPs (Playwright, Puppeteer) introduce massive friction:

• Download ~300MB Chromium binaries that hog disk space
• Spin up heavy Node.js runtimes that leave detached zombie processes
• Lack access to existing user sessions, cookies, and saved logins
• Dump 100k+ tokens of raw bloated HTML into LLM context windows

agents-browser connects directly to your installed browser via native CDP:

• Headless by Default: Silent --headless=new background automation. Visible window only on explicit ask.
• Zero Node.js / Zero 300MB Downloads: Pure lightweight Python (FastMCP + websockets).
• Indexed @ref Interactive Snapshots: Generates clean markdown with compact element references ([@1] Button: Login, [@2] Input: Search).
• High-Level Built-in Tools: Web search, clean reader-mode extraction, table scraping, batch form filling, dropdown selection, viewport scrolling, in-page search, and network/DOM stability detection.
• Persistent Sessions (~/.agents/browser): Preserves cookies, sessions, and saved logins across turns.
• Universal Multi-IDE Auto-Config: Plugs into Cursor, Antigravity, Claude Desktop, and Zed in 1 second.

Architecture & Flow

 ┌─────────────────────────────────────────────────────────────┐
 │                     CODING AGENT / IDE                      │
 │     Cursor · Antigravity · Claude Code · Windsurf · Zed     │
 └──────────────────────────────┬──────────────────────────────┘
                                │  FastMCP stdio
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                  AGENTS-BROWSER CDP CLIENT                  │
 │    Pure Python WebSocket · Port 9222 · Zero Node Runtime    │
 └──────────────────────────────┬──────────────────────────────┘
                                │  Direct CDP Commands
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │     LOCAL BROWSER (Chrome / Edge / Brave) — headless=new    │
 │    Persistent Profile: ~/.agents/browser                    │
 └──────────────┬───────────────────────────────┬──────────────┘
                │                               │
                ▼                               ▼
 ┌─────────────────────────────┐ ┌─────────────────────────────┐
 │    INDEXED SNAPSHOTS        │ │      HIGH-LEVEL TOOLS       │
 │  [@1] Button: Sign In       │ │  browser_search             │
 │  [@2] Input: Search         │ │  browser_read_article       │
 │  Compact Interactive Tokens │ │  browser_fill_form          │
 └─────────────────────────────┘ └─────────────────────────────┘

CLI Reference

MCP Tools Reference

Supported Ecosystem

• Claude Code: Bound via MCP server and .agents/skills/browser-browse.
• Google Antigravity: Integrated via .gemini/config rules and agents-browser MCP.
• Cursor: Automatically configures .cursor/mcp.json and agent rules.
• Zed: Configures context_servers and mirrors assistant skills.
• VS Code / Windsurf: Autowires Cline / Roo-Code MCP configuration.

Open ABI Specification

Detailed architectural specifications live in abi/:

• abi/WHY.md — Rationale & why CDP beats heavy Node.js frameworks.
• abi/LAYOUT.md — Storage taxonomy in ~/.agents/browser/.
• abi/MCP.md — Tool surface definitions and request/response contracts.
• abi/TOOLS.md — Exhaustive MCP tool reference & type signatures.
• abi/PLATFORM.md — Multi-platform browser binary & profile resolution.

Testing & Verification

Run the test suite:

python tests/run_all_tests.py

License

MIT License. See LICENSE for details.