agentleFS
theredsixtheredsix/agent-browser-protocol/CLAUDE.md

agent-browser-protocol

CLAUDE.md491 starsChanged 10 months agoBSD-3-ClauseView on GitHub

A Chromium fork implementing the Agent Browser Protocol (ABP) - a REST-based API for AI agent browser control at the C++ engine level. Unlike CDP or browser extensions, ABP operates directly in the browser engine for lower latency and greater capability.

  • Sends data out
  • In this repositoryOne other file it gives its agents.

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Test the MCP endpoint:

    line 241
  2. Very specific:

    Use autoninja (not ninja) for automatic parallelism

    line 345
  3. Very specific:

    Run gclient sync after pulling changes to update dependencies

    line 346

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Agent Browser Protocol - Chromium Fork

A Chromium fork implementing the Agent Browser Protocol (ABP) - a REST-based API for AI agent browser control at the C++ engine level. Unlike CDP or browser extensions, ABP operates directly in the browser engine for lower latency and greater capability.

Current Implementation Status

Working Features

  • Tab Management: List, create, close, get info, activate, stop loading
  • Navigation: Navigate to URL, back, forward, reload
  • Screenshots: Capture viewport with optional element markup overlays (GET binary or POST with action envelope)
  • Mouse Input: Click, move, scroll (native mouse wheel events via RenderWidgetHost)
  • Keyboard Input: Type text, press/down/up key events with modifier support
  • JavaScript Execution: Execute scripts and get results (via CDP Runtime.evaluate)
  • Text Extraction: Get page text or text from a CSS selector
  • Dialogs: Get pending dialog info, accept, dismiss (alert/confirm/prompt/beforeunload)
  • Downloads: List, get status, cancel
  • File Chooser: Provide files to native file picker dialogs
  • Native Pickers: Intercept <select> dropdowns (cross-platform, incl. Linux/Windows via use_external_popup_menu) and date/time pickers (date/time/datetime-local/month/week, via a ShowDateTimePopup mojo → AbpDateTimeChooser), surfacing a select_open/datetime_picker_open event; respond via /select/{id} and /datetime-picker/{id} (ISO values, applied by Blink)
  • Permissions: Intercept permission prompts, grant/deny with type validation (geolocation grant accepts lat/lng/accuracy, auto-deny non-geolocation)
  • Execution Control: Pause/resume JS execution with virtual time for deterministic state
  • Wait: Duration-based wait with action envelope
  • History: Session, action, and event history with SQLite storage
  • Input Mode: Toggle between agent (ABP-controlled), human (user-controlled), and cdp (remote debugging) input modes via API or toolbar icon. Human mode allows direct user interaction (e.g., for authentication), suspends execution control, and shows a yellow gradient border overlay.
  • Browser Management: Status check, graceful shutdown
  • Console Capture: In-memory 5000-entry FIFO buffer capturing console.log/warn/error, CORS errors, CSP violations, uncaught exceptions via WebContentsObserver (non-fingerprintable, no CDP)
  • MCP Server: Embedded MCP (JSON-RPC over HTTP) with 21 tools at /mcp

Architecture

┌─────────────────────────────────────────────┐
│         HTTP Client (curl/agent/MCP)        │
└─────────────────┬───────────────────────────┘
                  │ GET/POST /api/v1/* or /mcp
                  ▼
┌─────────────────────────────────────────────┐
│  AbpHttpServer (IO thread)                  │
│  - net::HttpServer on localhost:8222        │
│  - Routes REST + MCP requests               │
└─────────────────┬───────────────────────────┘
                  │ PostTask to UI thread
                  ▼
┌─────────────────────────────────────────────┐
│  AbpController (UI thread)                  │
│  - Direct access to Browser, TabStripModel  │
│  - Uses DevToolsAgentHost for CDP commands  │
│  - AbpActionContext for action lifecycle    │
│  - AbpInputDispatcher for native input      │
│  - AbpEventObserver for CDP event streams   │
│  - AbpEventCollector for action events      │
├─────────────────────────────────────────────┤
│  AbpMcpHandler - Embedded MCP server        │
│  AbpHistoryController - Session/action log  │
│  AbpDownloadObserver - Download tracking    │
└─────────────────────────────────────────────┘

Project Structure

ABP Source Code

chrome/browser/abp/
├── BUILD.gn                     # Build configuration
├── abp_switches.h/cc            # --abp-port, --abp-session-dir flags
├── abp_http_server.h/cc         # HTTP server (IO thread)
├── abp_controller.h/cc          # Request handler + CDP client (UI thread)
├── abp_action_context.h/cc      # Action lifecycle (pause/resume/screenshot)
├── abp_input_dispatcher.h/cc    # Native input dispatch (click/scroll/keys)
├── abp_location_provider.h/cc   # Mock geolocation provider (coordinates set via permission grant)
├── abp_system_geolocation_source.h/cc # Bypasses macOS system location dialog
├── abp_permission_observer.h/cc # Permission prompt interception
├── abp_event_observer.h/cc      # CDP event client per tab
├── abp_event_collector.h/cc     # Collects events during actions
├── abp_mcp_handler.h/cc         # Embedded MCP server (JSON-RPC over HTTP)
├── abp_tool_builder.h/cc        # MCP tool schema builder
├── abp_history_controller.h/cc  # Session/action history API
├── abp_history_database.h/cc    # SQLite history storage
├── abp_download_observer.h/cc   # Download tracking
├── abp_console_capture.h/cc     # Console message capture (WebContentsObserver)
├── abp_config.h/cc              # Runtime configuration
└── abp_types.h                  # Shared type definitions

Design Documentation

plans/
├── README.md                    # Overview
├── agent-browser-protocol.md    # Core ABP architecture
├── API.md                       # Full REST API specification
├── mcp.md                       # MCP server specification
└── implementation.md            # Minimal implementation plan

Build Setup

Prerequisites

  1. depot_tools (Google's build toolchain):
    git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ~/depot_tools
    echo 'export PATH="$HOME/depot_tools:$PATH"' >> ~/.bashrc
    source ~/.bashrc
  2. Build dependencies (Ubuntu/Debian):
    sudo ./build/install-build-deps.sh --no-prompt

Directory Structure

/home/paladin/src/
├── .gclient           # gclient configuration
├── src -> chromium    # symlink required by gclient
└── chromium/          # source code
    ├── out/Default/   # build output
    ├── chrome/browser/abp/  # ABP implementation
    ├── tools/abp-mcp-server/  # MCP server
    └── plans/         # Design docs

Sync Dependencies

cd /home/paladin/src
gclient sync --no-history

Configure Build

Debug component build (faster incremental builds):

cd /home/paladin/src/src
gn gen out/Default --args='is_debug=true is_component_build=true symbol_level=1 dcheck_always_on=true'

Build Chromium

cd /home/paladin/src/src
autoninja -C out/Default chrome

First build: ~4-6 hours. Incremental builds: seconds to minutes.

Running ABP

Start ABP

./out/Default/ABP.app/Contents/MacOS/ABP --abp-session-dir=sessions/$(date +%Y%m%d_%H%M%S)

Session data (database and screenshots) will be stored in sessions/<timestamp>/.

To use the default /tmp/abp-<UUID>/ directory instead:

./out/Default/ABP.app/Contents/MacOS/ABP

REST API Examples

# Check browser readiness
curl http://localhost:8222/api/v1/browser/status

# List all tabs
curl http://localhost:8222/api/v1/tabs

# Create new tab
curl -X POST http://localhost:8222/api/v1/tabs \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Navigate existing tab
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Take screenshot with element markup
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/screenshot \
  -H "Content-Type: application/json" \
  -d '{"screenshot":{"markup":"interactive","format":"webp"}}'

# Binary screenshot (returns image/webp)
curl http://localhost:8222/api/v1/tabs/{tab_id}/screenshot?markup=interactive -o screenshot.webp

# Click at coordinates
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/click \
  -H "Content-Type: application/json" \
  -d '{"x":100,"y":200}'

# Type text
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/type \
  -H "Content-Type: application/json" \
  -d '{"text":"hello world"}'

# Press key combo (Ctrl+A)
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/keyboard/press \
  -H "Content-Type: application/json" \
  -d '{"key":"a","modifiers":["Control"]}'

# Scroll down at coordinates
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/scroll \
  -H "Content-Type: application/json" \
  -d '{"x":500,"y":400,"delta_y":300}'

# Execute JavaScript (note: parameter is "script", not "expression")
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/execute \
  -H "Content-Type: application/json" \
  -d '{"script":"document.title"}'

# Get page text
curl -X POST http://localhost:8222/api/v1/tabs/{tab_id}/text \
  -H "Content-Type: application/json" \
  -d '{}'

# Close tab
curl -X DELETE http://localhost:8222/api/v1/tabs/{tab_id}

MCP Server

The MCP server is embedded directly in Chrome—no separate process needed. It's available at /mcp on the same port as the REST API.

Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "transport": "streamable-http",
      "url": "http://localhost:8222/mcp"
    }
  }
}

Test the MCP endpoint:

# Initialize MCP session
curl -X POST http://localhost:8222/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}'

# List available tools
curl -X POST http://localhost:8222/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

API Reference

See plans/API.md for the complete REST API specification. All endpoints:

MethodPathDescription
Browser
GET/api/v1/browser/statusGet browser readiness status
GET/api/v1/browser/session-dataGet session data file paths
POST/api/v1/browser/shutdownGraceful shutdown
GET/api/v1/browser/input-modeGet current input mode (agent/human)
POST/api/v1/browser/input-modeSet input mode (toggles human/agent control)
POST/api/v1/browser/cdp-mode/enterEnter CDP mode (starts remote debugging server)
POST/api/v1/browser/cdp-mode/exitExit CDP mode (returns control to ABP)
Tabs
GET/api/v1/tabsList all tabs
GET/api/v1/tabs/{id}Get tab details
POST/api/v1/tabsCreate new tab
DELETE/api/v1/tabs/{id}Close tab
POST/api/v1/tabs/{id}/activateSwitch to tab
POST/api/v1/tabs/{id}/stopStop loading
Navigation
POST/api/v1/tabs/{id}/navigateNavigate to URL
POST/api/v1/tabs/{id}/reloadReload page
POST/api/v1/tabs/{id}/backGo back
POST/api/v1/tabs/{id}/forwardGo forward
Mouse
POST/api/v1/tabs/{id}/clickClick at coordinates
POST/api/v1/tabs/{id}/moveMouse move
POST/api/v1/tabs/{id}/scrollScroll (mouse wheel)
Keyboard
POST/api/v1/tabs/{id}/typeType text
POST/api/v1/tabs/{id}/keyboard/pressPress key combo
POST/api/v1/tabs/{id}/keyboard/downKey down
POST/api/v1/tabs/{id}/keyboard/upKey up
Screenshots
GET/api/v1/tabs/{id}/screenshotBinary WebP screenshot
POST/api/v1/tabs/{id}/screenshotScreenshot via action envelope
Content
POST/api/v1/tabs/{id}/executeExecute JavaScript
POST/api/v1/tabs/{id}/textGet page text
Wait
POST/api/v1/tabs/{id}/waitWait for duration
Dialogs
GET/api/v1/tabs/{id}/dialogGet pending dialog
POST/api/v1/tabs/{id}/dialog/acceptAccept dialog
POST/api/v1/tabs/{id}/dialog/dismissDismiss dialog
Execution Control
GET/api/v1/tabs/{id}/executionGet execution state
POST/api/v1/tabs/{id}/executionSet execution state
Downloads
GET/api/v1/downloadsList downloads
GET/api/v1/downloads/{id}Get download status
POST/api/v1/downloads/{id}/cancelCancel download
File Chooser
POST/api/v1/file-chooser/{id}Provide files to dialog
Popups
POST/api/v1/select/{id}Respond to select popup
POST/api/v1/datetime-picker/{id}Respond to date/time picker (ISO value or cancel)
Permissions
GET/api/v1/permissionsList pending permission requests
POST/api/v1/permissions/{id}/grantGrant permission (requires permission_type; geolocation requires lat/lng)
POST/api/v1/permissions/{id}/denyDeny permission (requires permission_type)
Console
GET/api/v1/consoleQuery console messages (level, pattern, tab_id, limit, after_id)
DELETE/api/v1/consoleClear console buffer (optional tab_id filter)
Network
GET/api/v1/networkQuery saved network calls with regex filters
POST/api/v1/network/saveRetroactively tag & persist in-memory buffer
DELETE/api/v1/networkClear saved calls (by tag or all)
POST/api/v1/tabs/{id}/curlExecute HTTP request using tab's session
History
GET/api/v1/history/sessionsList sessions
GET/api/v1/history/sessions/currentGet current session
GET/api/v1/history/sessions/{id}Get session by ID
GET/api/v1/history/sessions/{id}/exportExport session
GET/api/v1/history/actionsList actions
GET/api/v1/history/actions/{id}Get action by ID
GET/api/v1/history/actions/{id}/screenshotGet action screenshot
DELETE/api/v1/history/actionsDelete actions
GET/api/v1/history/eventsList events
GET/api/v1/history/events/{id}Get event by ID
DELETE/api/v1/history/eventsDelete events
DELETE/api/v1/historyDelete all history
MCP
POST/mcpMCP JSON-RPC endpoint (21 tools, includes cdp_mode)

Development Notes

  • Source is at /home/paladin/src/chromium (symlinked as src for gclient)
  • Build output at out/Default/
  • Use autoninja (not ninja) for automatic parallelism
  • Run gclient sync after pulling changes to update dependencies
  • ABP uses CDP (Chrome DevTools Protocol) internally for JS evaluation and debugger control
  • Mouse/keyboard input is dispatched natively via RenderWidgetHost (bypasses CDP)
  • Screenshots use ForceRedraw + GrabViewSnapshot (not CDP Page.captureScreenshot)
  • Tab IDs are DevToolsAgentHost IDs (stable for the session)
  • Execution control uses Debugger.pause/resume + Emulation.setVirtualTimePolicy for deterministic state
  • Session history is stored in SQLite via AbpHistoryDatabase

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.