agent-tbrowser

agent-tbrowser

Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.

Installation

npm (recommended)

npm install -g agent-tbrowser
agent-tbrowser install  # Download Chromium

From Source

git clone https://github.com/kokouaserge/custom-agent-browser
cd agent-tbrowser
pnpm install
pnpm build
pnpm build:native   # Requires Rust (https://rustup.rs)
pnpm link --global  # Makes agent-tbrowser available globally
agent-tbrowser install

Linux Dependencies

On Linux, install system dependencies:

agent-tbrowser install --with-deps
# or manually: npx playwright install-deps chromium

Quick Start

agent-tbrowser open example.com
agent-tbrowser snapshot                    # Get accessibility tree with refs
agent-tbrowser click @e2                   # Click by ref from snapshot
agent-tbrowser fill @e3 "[e-mail]" # Fill by ref
agent-tbrowser get text @e1                # Get text by ref
agent-tbrowser screenshot page.png
agent-tbrowser close

Traditional Selectors (also supported)

agent-tbrowser click "#submit"
agent-tbrowser fill "#email" "[e-mail]"
agent-tbrowser find role button click --name "Submit"

Commands

Core Commands

agent-tbrowser open <url>              # Navigate to URL (aliases: goto, navigate)
agent-tbrowser click <sel>             # Click element
agent-tbrowser dblclick <sel>          # Double-click element
agent-tbrowser focus <sel>             # Focus element
agent-tbrowser type <sel> <text>       # Type into element
agent-tbrowser fill <sel> <text>       # Clear and fill
agent-tbrowser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-tbrowser keydown <key>           # Hold key down
agent-tbrowser keyup <key>             # Release key
agent-tbrowser hover <sel>             # Hover element
agent-tbrowser select <sel> <val>      # Select dropdown option
agent-tbrowser check <sel>             # Check checkbox
agent-tbrowser uncheck <sel>           # Uncheck checkbox
agent-tbrowser scroll <dir> [px]       # Scroll (up/down/left/right)
agent-tbrowser scrollintoview <sel>    # Scroll element into view (alias: scrollinto)
agent-tbrowser drag <src> <tgt>        # Drag and drop
agent-tbrowser upload <sel> <files>    # Upload files
agent-tbrowser screenshot [path]       # Take screenshot (--full for full page)
agent-tbrowser pdf <path>              # Save as PDF
agent-tbrowser snapshot                # Accessibility tree with refs (best for AI)
agent-tbrowser eval <js>               # Run JavaScript
agent-tbrowser close                   # Close browser (aliases: quit, exit)

Get Info

agent-tbrowser get text <sel>          # Get text content
agent-tbrowser get html <sel>          # Get innerHTML
agent-tbrowser get value <sel>         # Get input value
agent-tbrowser get attr <sel> <attr>   # Get attribute
agent-tbrowser get title               # Get page title
agent-tbrowser get url                 # Get current URL
agent-tbrowser get count <sel>         # Count matching elements
agent-tbrowser get box <sel>           # Get bounding box

Check State

agent-tbrowser is visible <sel>        # Check if visible
agent-tbrowser is enabled <sel>        # Check if enabled
agent-tbrowser is checked <sel>        # Check if checked

Find Elements (Semantic Locators)

agent-tbrowser find role <role> <action> [value]       # By ARIA role
agent-tbrowser find text <text> <action>               # By text content
agent-tbrowser find label <label> <action> [value]     # By label
agent-tbrowser find placeholder <ph> <action> [value]  # By placeholder
agent-tbrowser find alt <text> <action>                # By alt text
agent-tbrowser find title <text> <action>              # By title attr
agent-tbrowser find testid <id> <action> [value]       # By data-testid
agent-tbrowser find first <sel> <action> [value]       # First match
agent-tbrowser find last <sel> <action> [value]        # Last match
agent-tbrowser find nth <n> <sel> <action> [value]     # Nth match

Actions: click, fill, check, hover, text

Examples:

agent-tbrowser find role button click --name "Submit"
agent-tbrowser find text "Sign In" click
agent-tbrowser find label "Email" fill "[e-mail]"
agent-tbrowser find first ".item" click
agent-tbrowser find nth 2 "a" text

Wait

agent-tbrowser wait <selector>         # Wait for element to be visible
agent-tbrowser wait <ms>               # Wait for time (milliseconds)
agent-tbrowser wait --text "Welcome"   # Wait for text to appear
agent-tbrowser wait --url "**/dash"    # Wait for URL pattern
agent-tbrowser wait --load networkidle # Wait for load state
agent-tbrowser wait --fn "window.ready === true"  # Wait for JS condition

Load states: load, domcontentloaded, networkidle

Mouse Control

agent-tbrowser mouse move <x> <y>      # Move mouse
agent-tbrowser mouse down [button]     # Press button (left/right/middle)
agent-tbrowser mouse up [button]       # Release button
agent-tbrowser mouse wheel <dy> [dx]   # Scroll wheel

Browser Settings

agent-tbrowser set viewport <w> <h>    # Set viewport size
agent-tbrowser set device <name>       # Emulate device ("iPhone 14")
agent-tbrowser set geo <lat> <lng>     # Set geolocation
agent-tbrowser set offline [on|off]    # Toggle offline mode
agent-tbrowser set headers <json>      # Extra HTTP headers
agent-tbrowser set credentials <u> <p> # HTTP basic auth
agent-tbrowser set media [dark|light]  # Emulate color scheme

Cookies & Storage

agent-tbrowser cookies                 # Get all cookies
agent-tbrowser cookies set <name> <val> # Set cookie
agent-tbrowser cookies clear           # Clear cookies

agent-tbrowser storage local           # Get all localStorage
agent-tbrowser storage local <key>     # Get specific key
agent-tbrowser storage local set <k> <v>  # Set value
agent-tbrowser storage local clear     # Clear all

agent-tbrowser storage session         # Same for sessionStorage

Network

agent-tbrowser network route <url>              # Intercept requests
agent-tbrowser network route <url> --abort      # Block requests
agent-tbrowser network route <url> --body <json>  # Mock response
agent-tbrowser network unroute [url]            # Remove routes
agent-tbrowser network requests                 # View tracked requests
agent-tbrowser network requests --filter api    # Filter requests

Tabs & Windows

agent-tbrowser tab                     # List tabs
agent-tbrowser tab new [url]           # New tab (optionally with URL)
agent-tbrowser tab <n>                 # Switch to tab n
agent-tbrowser tab close [n]           # Close tab
agent-tbrowser window new              # New window

Frames

agent-tbrowser frame <sel>             # Switch to iframe
agent-tbrowser frame main              # Back to main frame

Dialogs

agent-tbrowser dialog accept [text]    # Accept (with optional prompt text)
agent-tbrowser dialog dismiss          # Dismiss

Debug

agent-tbrowser trace start [path]      # Start recording trace
agent-tbrowser trace stop [path]       # Stop and save trace
agent-tbrowser console                 # View console messages
agent-tbrowser console --clear         # Clear console
agent-tbrowser errors                  # View page errors
agent-tbrowser errors --clear          # Clear errors
agent-tbrowser highlight <sel>         # Highlight element
agent-tbrowser state save <path>       # Save auth state
agent-tbrowser state load <path>       # Load auth state

Navigation

agent-tbrowser back                    # Go back
agent-tbrowser forward                 # Go forward
agent-tbrowser reload                  # Reload page

Setup

agent-tbrowser install                 # Download Chromium browser
agent-tbrowser install --with-deps     # Also install system deps (Linux)

Sessions

Run multiple isolated browser instances:

# Different sessions
agent-tbrowser --session agent1 open site-a.com
agent-tbrowser --session agent2 open site-b.com

# Or via environment variable
AGENT_BROWSER_SESSION=agent1 agent-tbrowser click "#btn"

# List active sessions
agent-tbrowser session list
# Output:
# Active sessions:
# -> default
#    agent1

# Show current session
agent-tbrowser session

Each session has its own:

• Browser instance
• Cookies and storage
• Navigation history
• Authentication state

Snapshot Options

The snapshot command supports filtering to reduce output size:

agent-tbrowser snapshot                    # Full accessibility tree
agent-tbrowser snapshot -i                 # Interactive elements only (buttons, inputs, links)
agent-tbrowser snapshot -c                 # Compact (remove empty structural elements)
agent-tbrowser snapshot -d 3               # Limit depth to 3 levels
agent-tbrowser snapshot -s "#main"         # Scope to CSS selector
agent-tbrowser snapshot -i -c -d 5         # Combine options

Option	Description
-i, --interactive	Only show interactive elements (buttons, links, inputs)
-c, --compact	Remove empty structural elements
-d, --depth <n>	Limit tree depth
-s, --selector <sel>	Scope to CSS selector

Options

Option	Description
--session <name>	Use isolated session (or AGENT_BROWSER_SESSION env)
--headers <json>	Set HTTP headers scoped to the URL's origin
--executable-path <path>	Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH env)
--json	JSON output (for agents)
--full, -f	Full page screenshot
--name, -n	Locator name filter
--exact	Exact text match
--headed	Show browser window (not headless)
--cdp <port>	Connect via Chrome DevTools Protocol
--debug	Debug output

Selectors

Refs (Recommended for AI)

Refs provide deterministic element selection from snapshots:

# 1. Get snapshot with refs
agent-tbrowser snapshot
# Output:
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

# 2. Use refs to interact
agent-tbrowser click @e2                   # Click the button
agent-tbrowser fill @e3 "[e-mail]" # Fill the textbox
agent-tbrowser get text @e1                # Get heading text
agent-tbrowser hover @e4                   # Hover the link

Why use refs?

• Deterministic: Ref points to exact element from snapshot
• Fast: No DOM re-query needed
• AI-friendly: Snapshot + ref workflow is optimal for LLMs

CSS Selectors

agent-tbrowser click "#id"
agent-tbrowser click ".class"
agent-tbrowser click "div > button"

Text & XPath

agent-tbrowser click "text=Submit"
agent-tbrowser click "xpath=//button"

Semantic Locators

agent-tbrowser find role button click --name "Submit"
agent-tbrowser find label "Email" fill "[e-mail]"

Agent Mode

Use --json for machine-readable output:

agent-tbrowser snapshot --json
# Returns: {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

agent-tbrowser get text @e1 --json
agent-tbrowser is visible @e2 --json

Optimal AI Workflow

# 1. Navigate and get snapshot
agent-tbrowser open example.com
agent-tbrowser snapshot -i --json   # AI parses tree and refs

# 2. AI identifies target refs from snapshot
# 3. Execute actions using refs
agent-tbrowser click @e2
agent-tbrowser fill @e3 "input text"

# 4. Get new snapshot if page changed
agent-tbrowser snapshot -i --json

Headed Mode

Show the browser window for debugging:

agent-tbrowser open example.com --headed

This opens a visible browser window instead of running headless.

Authenticated Sessions

Use --headers to set HTTP headers for a specific origin, enabling authentication without login flows:

# Headers are scoped to api.example.com only
agent-tbrowser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# Requests to api.example.com include the auth header
agent-tbrowser snapshot -i --json
agent-tbrowser click @e2

# Navigate to another domain - headers are NOT sent (safe!)
agent-tbrowser open other-site.com

This is useful for:

• Skipping login flows - Authenticate via headers instead of UI
• Switching users - Start new sessions with different auth tokens
• API testing - Access protected endpoints directly
• Security - Headers are scoped to the origin, not leaked to other domains

To set headers for multiple origins, use --headers with each open command:

agent-tbrowser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-tbrowser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

For global headers (all domains), use set headers:

agent-tbrowser set headers '{"X-Custom-Header": "value"}'

Custom Browser Executable

Use a custom browser executable instead of the bundled Chromium. This is useful for:

• Serverless deployment: Use lightweight Chromium builds like @sparticuz/chromium (~50MB vs ~684MB)
• System browsers: Use an existing Chrome/Chromium installation
• Custom builds: Use modified browser builds

CLI Usage

# Via flag
agent-tbrowser --executable-path /path/to/chromium open example.com

# Via environment variable
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-tbrowser open example.com

Serverless Example (Vercel/AWS Lambda)

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-tbrowser';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... use browser
}

SDK (Programmatic API)

The SDK provides natural language browser automation. Describe elements in plain language, and the SDK finds them using LLM + cache.

Quick Start

import { createRunner } from 'agent-tbrowser/sdk';

// Create LLM client (e.g., Anthropic)
const llm = {
  complete: async (prompt: string) => {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }],
    });
    return {
      text: response.content[0].type === 'text' ? response.content[0].text : '',
      usage: {
        input: response.usage.input_tokens,
        output: response.usage.output_tokens,
      },
    };
  },
};

// Local browser
const runner = await createRunner({
  llm,
  local: { headless: false },
});

// Natural language automation
await runner.open('https://example.com');
await runner.click('the login button');
await runner.fill('email input', '[e-mail]');
await runner.fill('password field', 'secret123');
await runner.click('submit button');

await runner.close();

Cloud Browsers

// TBrowser
const runner = await createRunner({
  mode: 'cloud',
  cloud: {
    provider: 'tbrowser',
    apiKey: process.env.TBROWSER_API_KEY,
    apiUrl: process.env.TBROWSER_API_URL,
  },
  llm,
});

// Browserbase
const runner = await createRunner({
  mode: 'cloud',
  cloud: {
    provider: 'browserbase',
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
  },
  llm,
});

// Hyperbrowser
const runner = await createRunner({
  mode: 'cloud',
  cloud: {
    provider: 'hyperbrowser',
    apiKey: process.env.HYPERBROWSER_API_KEY,
  },
  llm,
});

// Get session info
console.log('Session:', runner.getSessionId());
console.log('Provider:', runner.getCloudProvider());

SDK Actions

The SDK provides 70+ actions organized by category:

Category	Actions
Navigation	open, back, forward, reload
Interactions	click, dblclick, fill, type, select, check, uncheck, hover, focus, drag, dropFiles
Keyboard	press, keyDown, keyUp
Mouse	mouseMove, mouseDown, mouseUp, mouseWheel, scroll, scrollToElement
Getters	getText, getHtml, getValue, getAttribute, getTitle, getUrl, getCount, getBoundingBox
State	isVisible, isEnabled, isChecked, isHidden, isEditable
Wait	waitForElement, waitForTimeout, waitForUrl, waitForPageLoad
Tabs/Frames	newTab, switchTab, closeTab, listTabs, switchToFrame, switchToMainFrame
Storage	getCookies, setCookie, clearCookies, getLocalStorage, setLocalStorageItem, clearLocalStorage
Network	startRequestTracking, getRequests, mockRoute, blockRoute, setExtraHeaders, setOffline
Debug	startTracing, stopTracing, highlight, getSnapshot, getDebugInfo, pdf
Config	setViewport, setGeolocation, setColorScheme, setTimezone, setLocale

See SDK Documentation for complete API reference.

CDP Mode

Connect to an existing browser via Chrome DevTools Protocol:

# Connect to Electron app
agent-tbrowser --cdp 9222 snapshot

# Connect to Chrome with remote debugging
# (Start Chrome with: google-chrome --remote-debugging-port=9222)
agent-tbrowser --cdp 9222 open about:blank

This enables control of:

• Electron apps
• Chrome/Chromium instances with remote debugging
• WebView2 applications
• Any browser exposing a CDP endpoint

Streaming (Browser Preview)

Stream the browser viewport via WebSocket for live preview or "pair browsing" where a human can watch and interact alongside an AI agent.

Enable Streaming

Set the AGENT_BROWSER_STREAM_PORT environment variable:

AGENT_BROWSER_STREAM_PORT=9223 agent-tbrowser open example.com

This starts a WebSocket server on the specified port that streams the browser viewport and accepts input events.

WebSocket Protocol

Connect to ws://localhost:9223 to receive frames and send input:

Receive frames:

{
  "type": "frame",
  "data": "<base64-encoded-jpeg>",
  "metadata": {
    "deviceWidth": 1280,
    "deviceHeight": 720,
    "pageScaleFactor": 1,
    "offsetTop": 0,
    "scrollOffsetX": 0,
    "scrollOffsetY": 0
  }
}

Send mouse events:

{
  "type": "input_mouse",
  "eventType": "mousePressed",
  "x": 100,
  "y": 200,
  "button": "left",
  "clickCount": 1
}

Send keyboard events:

{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "Enter",
  "code": "Enter"
}

Send touch events:

{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{ "x": 100, "y": 200 }]
}

Programmatic API

For advanced use, control streaming directly via the protocol:

import { BrowserManager } from 'agent-tbrowser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// Start screencast
await browser.startScreencast((frame) => {
  // frame.data is base64-encoded image
  // frame.metadata contains viewport info
  console.log('Frame received:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
}, {
  format: 'jpeg',
  quality: 80,
  maxWidth: 1280,
  maxHeight: 720,
});

// Inject mouse events
await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
});

// Inject keyboard events
await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
});

// Stop when done
await browser.stopScreencast();

Architecture

agent-tbrowser uses a client-daemon architecture:

• Rust CLI (fast native binary) - Parses commands, communicates with daemon
• Node.js Daemon - Manages Playwright browser instance
• Fallback - If native binary unavailable, uses Node.js directly

The daemon starts automatically on first command and persists between commands for fast subsequent operations.

Browser Engine: Uses Chromium by default. The daemon also supports Firefox and WebKit via the Playwright protocol.

Platforms

Platform	Binary	Fallback
macOS ARM64	Native Rust	Node.js
macOS x64	Native Rust	Node.js
Linux ARM64	Native Rust	Node.js
Linux x64	Native Rust	Node.js
Windows x64	Native Rust	Node.js

Usage with AI Agents

Just ask the agent

The simplest approach - just tell your agent to use it:

Use agent-tbrowser to test the login flow. Run agent-tbrowser --help to see available commands.

The --help output is comprehensive and most agents can figure it out from there.

AGENTS.md / CLAUDE.md

For more consistent results, add to your project or global instructions file:

## Browser Automation

Use `agent-tbrowser` for web automation. Run `agent-tbrowser --help` for all commands.

Core workflow:
1. `agent-tbrowser open <url>` - Navigate to page
2. `agent-tbrowser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-tbrowser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes

Claude Code Skill

For Claude Code, a skill provides richer context:

cp -r node_modules/agent-tbrowser/skills/agent-tbrowser .claude/skills/

Or download:

mkdir -p .claude/skills/agent-tbrowser
curl -o .claude/skills/agent-tbrowser/SKILL.md \
  https://raw.githubusercontent.com/kokouaserge/custom-agent-browser/main/skills/agent-tbrowser/SKILL.md

License

Apache-2.0