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:

bash

npx -y chrome-devtools-axi

For manual installation:

bash

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

bash

# 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:

bash

# 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

bash

# 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

bash

# 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

bash

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

Page Management

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

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

Configuration

Environment Variables

bash

# 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

bash

# 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

bash

# 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

typescript

// 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

bash

# 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

bash

# 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:

Capture snapshot
Extract refs
Attempt action with ref
If
```
STALE_REF
```
error, re-snapshot and retry with new ref

bash

# 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

bash

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

Port Conflicts

bash

# 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

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

bash

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

Debugging JavaScript Eval

bash

# 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

bash

#!/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

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

chrome-devtools-axi-browser-automation

NPX Install

Tags

SKILL.md Content

chrome-devtools-axi Browser Automation

Overview

Installation

Architecture

Core Commands

Navigation and Snapshot

Element Interaction

Screenshots

JavaScript Evaluation

Multi-Step Scripts

Page Management

Device Emulation

DevTools Debugging

Console Messages

Network Requests

Performance

Lighthouse Audits

Performance Tracing

Heap Snapshots

Configuration

Environment Variables

State Files

Common Patterns

Login Flow

Form Scraping

Multi-Page Workflow

Handling Dynamic Content

Testing Responsive Design

Understanding Refs and Staleness

Troubleshooting

Bridge Not Starting

Port Conflicts

Stale Refs

Element Not Found

Full Output Needed

Debugging JavaScript Eval

Example: E2E Testing Workflow

Best Practices for Agents