Chrome Devtools Axi Browser Automation

chrome-devtools-axi Browser Automation

Skill by ara.so — Devtools Skills collection.

Overview

chrome-devtools-axi is an AXI-compliant CLI wrapper around chrome-devtools-mcp that provides token-efficient browser automation. It uses TOON-encoded output to reduce token usage by ~40% compared to raw JSON, combines operations (navigate + snapshot + suggestions in one command), and includes contextual next-step hints in every response.

Key features:

• Accessibility tree snapshots with uid= refs for precise element targeting
• Generation-based staleness detection prevents silent no-ops when page state changes
• Persistent bridge process keeps Chrome session alive across commands
• Combined operations reduce round-trips for agents

Installation

For agents to install automatically:

npx -y chrome-devtools-axi

For manual installation:

npm install -g chrome-devtools-axi

Tell your agent:

Execute `npx -y chrome-devtools-axi` to get browser automation tools.

Architecture

The CLI communicates with a persistent bridge server (localhost:9224 by default) that maintains an MCP session with Chrome via DevTools Protocol. The bridge auto-starts on first command and writes state to ~/.chrome-devtools-axi/.

Core Commands

Navigation and Snapshot

# Navigate to a URL and capture accessibility tree
chrome-devtools-axi open https://example.com

# Capture current page state
chrome-devtools-axi snapshot

# Navigate back
chrome-devtools-axi back

# Scroll page
chrome-devtools-axi scroll down
chrome-devtools-axi scroll top

# Wait for time or content
chrome-devtools-axi wait 2000
chrome-devtools-axi wait "Welcome"

Element Interaction

Elements in snapshots are marked with uid=g<generation>:<id> refs. Always use refs exactly as printed:

# Click an element
chrome-devtools-axi click @g1:1

# Fill a form field
chrome-devtools-axi fill @g2:5 "user@example.com"

# Fill multiple fields at once
chrome-devtools-axi fillform @g2:5=john @g2:6=doe @g2:7=john@example.com

# Type text at current focus
chrome-devtools-axi type "search query"

# Press keyboard key
chrome-devtools-axi press Enter
chrome-devtools-axi press Tab

# Hover over element
chrome-devtools-axi hover @g1:3

# Drag and drop
chrome-devtools-axi drag @g1:4 @g1:8

# Upload file
chrome-devtools-axi upload @g1:2 /path/to/file.pdf

# Handle browser dialogs
chrome-devtools-axi dialog accept
chrome-devtools-axi dialog dismiss

Screenshots

# Save screenshot to file
chrome-devtools-axi screenshot output.png

# Capture specific element
chrome-devtools-axi screenshot element.png --uid @g1:5

# Full-page screenshot
chrome-devtools-axi screenshot full.png --full-page

# Specify format
chrome-devtools-axi screenshot output.jpg --format jpeg

JavaScript Evaluation

# Evaluate expression (auto-wrapped)
chrome-devtools-axi eval "document.title"

# Execute function
chrome-devtools-axi eval "() => document.querySelectorAll('a').length"

# Multi-statement logic
chrome-devtools-axi eval "() => {
  const rows = [...document.querySelectorAll('tr')];
  return rows.map(row => row.textContent.trim());
}"

Multi-Step Scripts

# Execute script from stdin
cat << 'EOF' | chrome-devtools-axi run
open https://example.com
wait "Example Domain"
click @g1:1
snapshot
EOF

Page Management

# List all tabs
chrome-devtools-axi pages

# Open new tab
chrome-devtools-axi newpage https://google.com

# Open in background
chrome-devtools-axi newpage https://github.com --background

# Switch tab
chrome-devtools-axi selectpage <id>

# Close tab
chrome-devtools-axi closepage <id>

# Resize viewport
chrome-devtools-axi resize 1920 1080

Device Emulation

# Emulate mobile viewport
chrome-devtools-axi emulate --viewport "390x844x3,mobile"

# Set color scheme
chrome-devtools-axi emulate --color-scheme dark

# Network throttling
chrome-devtools-axi emulate --network "Slow 3G"

# CPU throttling (1-20)
chrome-devtools-axi emulate --cpu 4

# Set geolocation
chrome-devtools-axi emulate --geolocation "37.7749x-122.4194"

# Custom user agent
chrome-devtools-axi emulate --user-agent "CustomBot/1.0"

# Combine options
chrome-devtools-axi emulate --viewport "390x844x3,mobile" --color-scheme dark --network "Fast 3G"

DevTools Debugging

Console Messages

# List all console messages
chrome-devtools-axi console

# Filter by type
chrome-devtools-axi console --type error
chrome-devtools-axi console --type warn

# Pagination
chrome-devtools-axi console --limit 10 --page 2

# Get specific message
chrome-devtools-axi console-get <id>

Available types: log, debug, info, error, warn, dir, dirxml, table, trace, clear, assert, all

Network Requests

# List network requests
chrome-devtools-axi network

# Filter by type
chrome-devtools-axi network --type xhr
chrome-devtools-axi network --type fetch

# Get specific request
chrome-devtools-axi network-get <id>

# Save response body
chrome-devtools-axi network-get <id> --response-file response.json

# Save request body
chrome-devtools-axi network-get <id> --request-file request.json

Available types: document, stylesheet, image, media, font, script, xhr, fetch, websocket, manifest, other, all

Performance

Lighthouse Audits

# Run Lighthouse audit
chrome-devtools-axi lighthouse

# Mobile device
chrome-devtools-axi lighthouse --device mobile

# Snapshot mode (current state)
chrome-devtools-axi lighthouse --mode snapshot

# Save reports to directory
chrome-devtools-axi lighthouse --output-dir ./reports

Performance Tracing

# Start trace
chrome-devtools-axi perf-start

# Start without reload
chrome-devtools-axi perf-start --no-reload

# Stop and save trace
chrome-devtools-axi perf-stop --file trace.json

# Analyze performance insight
chrome-devtools-axi perf-insight lcp "Largest Contentful Paint"

Heap Snapshots

# Capture heap snapshot
chrome-devtools-axi heap memory.heapsnapshot

Configuration

Environment Variables

# Change bridge server port (default: 9224)
export CHROME_DEVTOOLS_AXI_PORT=9225

# Connect to existing Chrome instance (HTTP/HTTPS)
export CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222

# Connect via WebSocket directly
export CHROME_DEVTOOLS_AXI_BROWSER_URL=wss://cluster.example/launch

# WebSocket authentication headers (JSON)
export CHROME_DEVTOOLS_AXI_WS_HEADERS='{"Authorization":"Bearer token"}'

# Disable session hook auto-install
export CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1

State Files

State stored in ~/.chrome-devtools-axi/:

• bridge.pid — Running bridge PID and port
• snapshot-generation — Staleness detection counter

Common Patterns

Login Flow

# Navigate and fill login form
chrome-devtools-axi open https://app.example.com/login
chrome-devtools-axi fillform @g1:1=user@example.com @g1:2=password
chrome-devtools-axi click @g1:3
chrome-devtools-axi wait "Dashboard"
chrome-devtools-axi snapshot

Form Scraping

# Extract form data with JavaScript
chrome-devtools-axi eval "() => {
  const form = document.querySelector('form');
  const data = new FormData(form);
  return Object.fromEntries(data.entries());
}"

Multi-Page Workflow

// In TypeScript/Node.js
import { execSync } from 'child_process';

function runCommand(cmd: string): string {
  return execSync(`chrome-devtools-axi ${cmd}`, { encoding: 'utf-8' });
}

// Navigate and extract data
runCommand('open https://example.com');
const title = runCommand('eval "document.title"');

// Take screenshot
runCommand('screenshot page.png');

// Fill and submit form
runCommand('fill @g1:1 "search term"');
runCommand('press Enter');
runCommand('wait 2000');

// Extract results
const results = runCommand('eval "() => [...document.querySelectorAll('.result')].map(el => el.textContent)"');

Handling Dynamic Content

# Wait for element to appear, then interact
chrome-devtools-axi open https://spa.example.com
chrome-devtools-axi wait "Loading complete"
chrome-devtools-axi snapshot
chrome-devtools-axi click @g2:5

Testing Responsive Design

# Test mobile layout
chrome-devtools-axi emulate --viewport "390x844x3,mobile"
chrome-devtools-axi open https://example.com
chrome-devtools-axi screenshot mobile.png

# Test desktop layout
chrome-devtools-axi resize 1920 1080
chrome-devtools-axi snapshot
chrome-devtools-axi screenshot desktop.png

Understanding Refs and Staleness

Refs use a generation prefix (g<N>:) that increments with each snapshot. If you capture a snapshot at generation 1, get ref @g1:5, then the page re-renders and moves to generation 2, attempting to use @g1:5 will fail with STALE_REF error.

Agent pattern:

1. Capture snapshot
2. Extract refs
3. Attempt action with ref
4. If STALE_REF error, re-snapshot and retry with new ref

# First snapshot
chrome-devtools-axi snapshot
# Output shows: uid=g1:1 link "Click here"

# Page changes, generation bumps to g2
chrome-devtools-axi click @g1:1
# Error: STALE_REF

# Re-snapshot to get fresh refs
chrome-devtools-axi snapshot
# Output shows: uid=g2:3 link "Click here"

chrome-devtools-axi click @g2:3
# Success

Troubleshooting

Bridge Not Starting

# Manually stop and restart bridge
chrome-devtools-axi stop
chrome-devtools-axi start

Port Conflicts

# Use different port
export CHROME_DEVTOOLS_AXI_PORT=9999
chrome-devtools-axi open https://example.com

Stale Refs

Always use refs exactly as printed in snapshot output. If you get STALE_REF, capture a new snapshot.

Element Not Found

If uid is valid but element doesn't respond:

• Check if element is visible (scroll into view)
• Wait for page to finish loading
• Use chrome-devtools-axi wait before interaction

Full Output Needed

# Disable truncation for complete data
chrome-devtools-axi snapshot --full
chrome-devtools-axi console --full

Debugging JavaScript Eval

# Check for errors in console
chrome-devtools-axi console --type error

# Test simple eval first
chrome-devtools-axi eval "2 + 2"

# Use arrow function for complex logic
chrome-devtools-axi eval "() => { console.log('debug'); return 42; }"

Example: E2E Testing Workflow

#!/bin/bash

# Start fresh session
chrome-devtools-axi stop
chrome-devtools-axi start

# Navigate to app
chrome-devtools-axi open https://app.example.com

# Login
chrome-devtools-axi fillform @g1:1=$USER_EMAIL @g1:2=$USER_PASSWORD
chrome-devtools-axi click @g1:3
chrome-devtools-axi wait "Dashboard"

# Take baseline screenshot
chrome-devtools-axi screenshot baseline.png

# Navigate to feature
chrome-devtools-axi click @g2:10
chrome-devtools-axi wait "Feature Page"

# Interact with feature
chrome-devtools-axi fill @g3:5 "test data"
chrome-devtools-axi click @g3:6

# Verify result
chrome-devtools-axi wait "Success"
chrome-devtools-axi snapshot --full > result.txt

# Capture performance
chrome-devtools-axi lighthouse --output-dir ./reports

# Cleanup
chrome-devtools-axi stop

Best Practices for Agents

1. Always re-snapshot after page changes — Don't reuse refs across navigation or mutations
2. Use combined operations — open gives snapshot automatically, reducing round-trips
3. Check help hints — Every response includes suggested next steps
4. Use --full sparingly — Default truncation saves tokens; only expand when needed
5. Prefer fillform over multiple fill — Batch form operations when possible
6. Wait strategically — Use wait <text> instead of arbitrary timeouts when possible
7. Leverage eval for extraction — JavaScript eval is more efficient than scraping via snapshots