agent-browser-cli Control

Skill by ara.so — Devtools Skills collection.

agent-browser-cli is a browser control CLI built in Rust that connects to a real Chrome session via a Chrome extension. It enables AI agents to scan tabs, execute JavaScript, manage cookies, capture screenshots, and perform CDP operations while preserving the user's login state and session.

Key difference from Selenium/Playwright: This tool works with an existing Chrome session (not headless), preserving all user login states and cookies. Perfect for AI agents that need to work with authenticated web sessions.

Installation

Via npm (recommended)

bash

npm install -g @sleepinsummer/agent-browser-cli

Via source

bash

git clone https://github.com/sleepinginsummer/agent-browser-cli.git
cd agent-browser-cli
cargo build --release
# Binary will be at ./target/release/agent-browser-cli

Chrome Extension Setup

Critical: The Chrome extension must be loaded for the CLI to work.

Download
```
chrome-extensions.zip
```
from the latest release
Extract the zip file
Open Chrome and navigate to
```
chrome://extensions
```
Enable "Developer mode"
Click "Load unpacked extension"
Select the extracted
```
tmwd_cdp_bridge
```
directory
Ensure at least one normal web page tab is open (not
```
about:blank
```
or
```
chrome://
```
)

The extension will show a small indicator on the right side of the page when connected.

Architecture

agent-browser-cli runs as a daemon service that:

Listens on port
```
18765
```
for Chrome extension WebSocket connections
Listens on port
```
18767
```
for CLI HTTP API calls
Maintains persistent browser connection to avoid re-initialization overhead

Performance reference (with daemon running):

Simple page read / JS execution: 40-120ms
DOM query operations: 270-360ms
Page monitoring with change summary: 720-880ms

Core Commands

Daemon Management

bash

# Start daemon (auto-starts if not running)
agent-browser-cli start

# Stop daemon
agent-browser-cli stop

# Restart daemon
agent-browser-cli restart

# Check daemon status
agent-browser-cli status

Tab Management

bash

# List all tabs
agent-browser-cli tabs

# Switch to tab by index
agent-browser-cli switch 0

# Open new URL
agent-browser-cli open https://example.com

# Close current tab
agent-browser-cli close

# Get active tab info
agent-browser-cli active

Page Content Extraction

bash

# Scan current page (simplified HTML)
agent-browser-cli scan

# Get text-only content (faster)
agent-browser-cli scan --text-only

# Get full page DOM
agent-browser-cli scan --full

# Scan specific tab
agent-browser-cli scan --tab 0

# Get page with screenshots of visible elements
agent-browser-cli scan --screenshot

JavaScript Execution

bash

# Execute JavaScript and return result
agent-browser-cli exec 'return document.title'

# Execute with page monitoring (detects changes)
agent-browser-cli exec --monitor 'document.querySelector("#search").value = "test"'

# Multi-line JS execution
agent-browser-cli exec 'const btn = document.querySelector("button");
btn.click();
return "clicked";'

# Execute in specific tab
agent-browser-cli exec --tab 0 'return window.location.href'

Screenshots

bash

# Capture full page screenshot
agent-browser-cli screenshot

# Screenshot specific tab
agent-browser-cli screenshot --tab 0

# Output to specific file
agent-browser-cli screenshot --output /path/to/screenshot.png

Cookie Management

bash

# Get all cookies for current page
agent-browser-cli cookies

# Get cookies for specific domain
agent-browser-cli cookies --domain example.com

# Set cookie
agent-browser-cli cookies --set 'name=value; domain=.example.com; path=/'

Configuration

bash

# Change extension WebSocket port (default: 18765)
agent-browser-cli set-extension-port 18766

# View current config
cat ~/.agent-browser-cli/config.json

Real-World Examples

Example 1: Search Automation

bash

# Open search engine
agent-browser-cli open "https://www.google.com"

# Wait a moment for page load, then input search query
sleep 1
agent-browser-cli exec 'document.querySelector("textarea[name=q]").value = "rust programming"'

# Submit search
agent-browser-cli exec --monitor 'document.querySelector("textarea[name=q]").form.submit()'

# Extract search results
agent-browser-cli scan --text-only

Example 2: Form Filling

bash

# Navigate to form page
agent-browser-cli open "https://example.com/contact"

# Fill form fields
agent-browser-cli exec '
const form = {
  name: document.querySelector("#name"),
  email: document.querySelector("#email"),
  message: document.querySelector("#message")
};
form.name.value = "AI Agent";
form.email.value = "agent@example.com";
form.message.value = "Hello from agent-browser-cli";
return "Form filled";
'

# Submit and monitor changes
agent-browser-cli exec --monitor 'document.querySelector("form").submit()'

Example 3: Multi-Tab Workflow

bash

# Get list of all tabs
TABS=$(agent-browser-cli tabs)
echo "$TABS"

# Switch to first tab
agent-browser-cli switch 0

# Get current page title
agent-browser-cli exec 'return document.title'

# Open new tab
agent-browser-cli open "https://example.com"

# Work with new tab
agent-browser-cli scan --text-only

Example 4: Data Extraction with Cookies

bash

# Navigate to authenticated page
agent-browser-cli open "https://example.com/dashboard"

# Extract cookies (user is already logged in)
COOKIES=$(agent-browser-cli cookies --domain example.com)
echo "$COOKIES"

# Extract protected content
agent-browser-cli scan --text-only

# Take screenshot of dashboard
agent-browser-cli screenshot --output dashboard.png

Example 5: Page Monitoring

bash

# Execute action and monitor DOM changes
RESULT=$(agent-browser-cli exec --monitor '
document.querySelector("#load-more").click();
return "Clicked load more";
')

# The result includes a change summary
echo "$RESULT"

# Re-scan to get updated content
agent-browser-cli scan --text-only

Response Format

All commands return JSON:

json

{
  "ok": true,
  "result": {
    "status": "success",
    "data": "...",
    "metadata": {}
  }
}

Error format:

json

{
  "ok": false,
  "error": "Error message"
}

Common Patterns

Wait for Element

bash

agent-browser-cli exec '
return new Promise((resolve) => {
  const check = () => {
    const el = document.querySelector("#target");
    if (el) resolve("Found");
    else setTimeout(check, 100);
  };
  check();
});
'

Extract Structured Data

bash

agent-browser-cli exec '
return Array.from(document.querySelectorAll(".item")).map(item => ({
  title: item.querySelector(".title")?.textContent,
  link: item.querySelector("a")?.href,
  price: item.querySelector(".price")?.textContent
}));
'

File Upload

bash

agent-browser-cli exec '
const input = document.querySelector("input[type=file]");
const dt = new DataTransfer();
dt.items.add(new File(["content"], "test.txt"));
input.files = dt.files;
input.dispatchEvent(new Event("change", { bubbles: true }));
return "File set";
'

Dropdown Selection

bash

agent-browser-cli exec '
const select = document.querySelector("select#country");
select.value = "US";
select.dispatchEvent(new Event("change", { bubbles: true }));
return select.value;
'

Troubleshooting

Extension not connecting

Verify extension is loaded in
```
chrome://extensions
```
Check extension port matches config:
```
cat ~/.agent-browser-cli/config.json
```
Ensure at least one normal web page is open (not
```
chrome://
```
or
```
about:
```
)
Restart daemon:
```
agent-browser-cli restart
```

Command timeout

Check daemon status:
```
agent-browser-cli status
```
Verify Chrome is running and extension is active
Try simpler command first:
```
agent-browser-cli tabs
```
Check logs:
```
tail -f ~/.agent-browser-cli.log
```

Port conflicts

bash

# Change extension port
agent-browser-cli set-extension-port 18766

# Update extension popup to match new port
# Restart daemon
agent-browser-cli restart

WSL 2 connectivity issues

For WSL 2 users on Windows 11 22H2+:

Enable
```
networkingMode=mirrored
```
in
```
.wslconfig
```
Restart WSL
Ensure Chrome extension can connect to
```
localhost:18765
```

Slow performance

Use
```
--text-only
```
flag for faster content extraction
Avoid
```
--screenshot
```
unless needed
Use
```
--monitor
```
only when detecting page changes is necessary
Consider increasing system resources if Chrome is sluggish

Advanced: CDP Operations

The underlying Chrome extension uses Chrome DevTools Protocol (CDP). While most operations are abstracted by the CLI, you can execute raw CDP commands via JavaScript:

bash

agent-browser-cli exec '
return await chrome.debugger.sendCommand({tabId: chrome.tabs.getCurrent().id}, "Network.getCookies", {});
'

Environment Variables

The CLI uses a config file instead of environment variables:

Config location:

~/.agent-browser-cli/config.json

json

{
  "extension_port": 18765
}

Logs

Daemon logs are written to:

~/.agent-browser-cli.log

Monitor in real-time:

bash

tail -f ~/.agent-browser-cli.log

Integration with AI Agents

When called by AI coding agents, typical workflows:

Check tab state:
```
agent-browser-cli tabs
```

Navigate or switch:

agent-browser-cli open <url>

agent-browser-cli switch <index>

Extract content:
```
agent-browser-cli scan --text-only
```

Perform action:

agent-browser-cli exec --monitor '<js code>'

Verify result:

agent-browser-cli scan

agent-browser-cli screenshot

The tool is designed for high-frequency calls with minimal overhead (~40-120ms for simple operations).

agent-browser-cli-control

NPX Install

Tags

SKILL.md Content

agent-browser-cli Control

Installation

Via npm (recommended)

Via source

Chrome Extension Setup

Architecture

Core Commands

Daemon Management

Tab Management

Page Content Extraction

JavaScript Execution

Screenshots

Cookie Management

Configuration

Real-World Examples

Example 1: Search Automation

Example 2: Form Filling

Example 3: Multi-Tab Workflow

Example 4: Data Extraction with Cookies

Example 5: Page Monitoring

Response Format

Common Patterns

Wait for Element

Extract Structured Data

File Upload

Dropdown Selection

Troubleshooting

Extension not connecting

Command timeout

Port conflicts

WSL 2 connectivity issues

Slow performance

Advanced: CDP Operations

Environment Variables

Logs

Integration with AI Agents