chrome-devtools-axi

The most agent-ergonomic browser automation

chrome-devtools-axi wraps chrome-devtools-mcp with an AXI-compliant CLI.

• Token-efficient — TOON-encoded output cuts token usage ~40% vs raw JSON
• Combined operations — one command navigates, captures, and suggests next steps
• Contextual suggestions — every response includes actionable next-step hints

Benchmarks

Agent ergonomics is measurable. The axi benchmark runs the same 14 real-world browsing tasks (Wikipedia research, GitHub navigation, multi-site comparison, and more) through 7 browser automation setups - 5 repeats each, with claude-sonnet-4-6 as the agent and an LLM judge scoring task success.

chrome-devtools-axi posts the lowest input tokens, cost, duration, and turn count of all 7 conditions, with 100% task success:

Condition	Avg Input Tokens	Avg Cost/Task	Avg Duration	Avg Turns	Success
chrome-devtools-axi	79,141	$0.074	21.5s	4.5	100%
dev-browser	82,532	$0.078	28.6s	4.9	99%
agent-browser (Vercel)	93,074	$0.088	24.6s	4.8	99%
chrome-devtools-mcp + compressor CLI	130,779	$0.091	29.7s	7.6	100%
chrome-devtools-mcp + ToolSearch	133,712	$0.096	29.4s	7.5	99%
chrome-devtools-mcp (raw MCP)	184,711	$0.101	26.0s	6.2	99%
chrome-devtools-mcp code execution	129,606	$0.120	36.2s	6.4	100%

Against raw chrome-devtools-mcp - the very server this CLI wraps - that is 57% fewer input tokens, 26% lower cost, and 27% fewer agent turns.

Quick Start

Install the chrome-devtools-axi skill in the Agent Skills format with npx skills:

npx skills add kunchenguid/chrome-devtools-axi --skill chrome-devtools-axi -g

That is the entire setup - no npm install needed. The skill teaches your agent to run chrome-devtools-axi through npx -y chrome-devtools-axi, so the CLI comes along on demand.

The skill is not a user-facing slash command (user-invocable: false). Just ask for anything that needs a real browser - opening a page, clicking through a flow, extracting page content, debugging console or network, auditing performance - and the agent loads the skill on its own when it recognizes the task. For ordinary web search, curl-able pages, or static extraction, the skill tells agents to skip Chrome and use simpler fetch/curl-style tooling. The skill frontmatter also includes Hermes Agent metadata (author plus metadata.hermes tags/category) so Hermes can list it as a first-class browser automation skill; other harnesses ignore those extra fields.

-g installs the skill for all projects (~/.claude/skills/, for example); drop it to install for the current project only (.claude/skills/).

What Agent Sees

$ chrome-devtools-axi open https://example.com
page: {title: "Example Domain", url: "https://example.com", refs: 1}
snapshot:
RootWebArea "Example Domain"
  heading "Example Domain"
  paragraph "This domain is for use in illustrative examples..."
  uid=g1:1 link "More information..."
help[1]:
  Run `chrome-devtools-axi click @g1:1` to click the "More information..." link

$ chrome-devtools-axi click @g1:1
page: {title: "IANA — IANA-Managed Reserved Domains", refs: 12}
snapshot:
...

Refs in snapshot output carry a g<N>: generation prefix that bumps every time a new accessibility tree is captured. Pass refs back exactly as printed - if the page re-rendered between snapshot and action, the action fails loudly with STALE_REF instead of silently no-op'ing, so the agent re-snapshots and retries. The skill also instructs agents to verify state-changing actions with a fresh snapshot, eval, or screenshot before reporting success, because a current ref can still produce no visible page change.

Other Ways to Install

The skill is the recommended path, but it is not the only one.

Zero setup

chrome-devtools-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all. Just tell your agent:

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

Session hook

Want ambient browser context - including the live page state of an active session - fed into every agent session instead of loading on demand? Install the CLI globally and opt into the hook:

npm install -g chrome-devtools-axi
chrome-devtools-axi setup hooks

This installs a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces the current browser session and usage guidance at the start of each session. Restart your agent session after running this so the new hook takes effect.

Development entrypoints such as pnpm run dev and bin/chrome-devtools-axi.ts are guarded from accidental hook installation.

From source

git clone https://github.com/kunchenguid/chrome-devtools-axi.git
cd chrome-devtools-axi
pnpm install --frozen-lockfile
pnpm run build
pnpm link

How It Works

┌───────────────────────┐
│  chrome-devtools-axi  │  CLI — parse args, format output
└──────────┬────────────┘
           │ HTTP (localhost:9224)
           ▼
┌───────────────────────┐
│     Bridge Server     │  Persistent process, manages MCP session
└──────────┬────────────┘
           │ stdio
           ▼
┌───────────────────────┐
│  chrome-devtools-mcp  │  Headless Chrome via DevTools Protocol
└───────────────────────┘

• Persistent bridge — a detached process keeps the MCP session alive across commands, so Chrome doesn't restart every invocation
• Auto-lifecycle — the bridge starts on first command, writes a PID file to ~/.chrome-devtools-axi/bridge.pid, recycles stale CDP targets after a deep health check, and reaps child processes on stop
• Snapshot parsing — accessibility tree snapshots are extracted and analyzed for interactive elements (uid= refs)
• TOON encoding — structured metadata uses TOON format for compact, token-efficient output

CLI Reference

Navigation

Command	Description
open <url>	Navigate to URL and snapshot
snapshot	Capture current page state
screenshot <p>	Save a screenshot to a file
scroll <dir>	Scroll: up, down, top, bottom
back	Navigate back
wait <ms|text>	Wait for time or text to appear
eval <js>	Evaluate a JavaScript expression or function
run	Execute a multi-step script from stdin

eval wraps plain input as () => (<expr>) before sending it to DevTools. For multi-statement logic, pass an arrow function or function. No-arg IIFE form (...)() is accepted too and unwrapped automatically.

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

Interaction

Command	Description
click @<uid>	Click an element by ref
fill @<uid> <text>	Fill a form field
type <text>	Type text at current focus
press <key>	Press a keyboard key
hover @<uid>	Hover over an element
drag @<from> @<to>	Drag an element onto another
fillform @<uid>=<val>...	Fill multiple form fields
dialog <accept|dismiss>	Handle a browser dialog
upload @<uid> <path>	Upload a file through an input

Page Management

Command	Description
pages	List all open tabs
newpage <url>	Open a new tab
selectpage <id>	Switch to a tab by ID
closepage <id>	Close a tab by ID
resize <w> <h>	Resize the browser viewport

Emulation

Command	Description
emulate	Emulate device/network/viewport

DevTools Debugging

Command	Description
console	List console messages
console-get <id>	Get a specific console message
network	List network requests
network-get [id]	Get a specific network request

For large request or response bodies, prefer network-get <id> --response-file <path> or --request-file <path> so the body goes to disk instead of flooding agent context.

Performance

Command	Description
lighthouse	Run a Lighthouse audit
perf-start	Start a performance trace
perf-stop	Stop the performance trace
perf-insight <set> <name>	Analyze a performance insight
heap <path>	Capture a heap snapshot

Bridge

Command	Description
start	Start the bridge server
stop	Stop the bridge server
setup hooks	Install or repair agent hooks

Maintenance

Command	Description
update	Upgrade the installed CLI to the latest npm version
update --check	Report current vs latest version without installing it

Running with no command shows the CLI home view. It prepends bin and description metadata, then includes the current snapshot when a browser session is active or the no-session status/help block when one is not.

Flags

Flag	Description
--help	Show usage information
-v, -V, --version	Show the installed CLI version
--check	Check for available updates (update)
--full	Show complete output without truncation
--background	Open new page in background (newpage)
--uid @<uid>	Target a specific element (screenshot)
--full-page	Capture entire scrollable page (screenshot)
--format <fmt>	Image format: png, jpeg, webp (screenshot)
--viewport <spec>	Viewport like "390x844x3,mobile" (emulate)
--color-scheme <value>	dark, light, or auto (emulate)
--network <condition>	Network throttle: Slow 3G, etc. (emulate)
--cpu <rate>	CPU throttling rate 1-20 (emulate)
--geolocation <lat>x<lon>	Set geolocation (emulate)
--user-agent <string>	Custom user agent (emulate)
--type <type>	Filter by type (console, network)
--limit <n>	Max items to return (console, network)
--page <n>	Pagination (console, network)
--device <device>	desktop or mobile (lighthouse)
--mode <mode>	navigation or snapshot (lighthouse)
--output-dir <path>	Directory for reports (lighthouse)
--no-reload	Skip page reload (perf-start)
--no-auto-stop	Disable auto-stop (perf-start)
--file <path>	Save trace data to file (perf-start/stop)
--response-file <path>	Save response body (network-get)
--request-file <path>	Save request body (network-get)

Local output paths for screenshot, heap, network-get --response-file/--request-file, lighthouse --output-dir, and perf-start/perf-stop --file resolve against the directory where you invoke the CLI. Saved-path output uses the resolved absolute path.

console --type accepts log, debug, info, error, warn, dir, dirxml, table, trace, clear, startGroup, startGroupCollapsed, endGroup, assert, profile, profileEnd, count, timeEnd, verbose, issue, and all. network --type accepts document, stylesheet, image, media, font, script, texttrack, xhr, fetch, prefetch, eventsource, websocket, manifest, signedexchange, ping, cspviolationreport, preflight, fedcm, other, and all. For both commands, all or an omitted --type returns every item.

Configuration

The bridge server port defaults to 9224. Override it with an environment variable:

export CHROME_DEVTOOLS_AXI_PORT=9225

Connect to an existing Chrome instance instead of launching one:

export CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222

CHROME_DEVTOOLS_AXI_BROWSER_URL accepts both http:// or https:// URLs and ws:// or wss:// endpoints:

• http(s):// uses --browserUrl and fetches /json/version to discover the WebSocket URL.
• ws(s):// uses --wsEndpoint directly.

For authenticated ws:// or wss:// endpoints, pass JSON headers with CHROME_DEVTOOLS_AXI_WS_HEADERS:

export CHROME_DEVTOOLS_AXI_BROWSER_URL=wss://cluster.example/launch
export CHROME_DEVTOOLS_AXI_WS_HEADERS='{"Authorization":"Bearer token"}'

Pick which installed Chrome release channel to target with CHROME_DEVTOOLS_AXI_CHANNEL - stable (the default), beta, canary, or dev:

export CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1
export CHROME_DEVTOOLS_AXI_CHANNEL=beta

This selects which Chrome --autoConnect attaches to, and which one is launched in the default and CHROME_DEVTOOLS_AXI_USER_DATA_DIR modes. It is ignored when CHROME_DEVTOOLS_AXI_BROWSER_URL is set, since that connects to an explicit endpoint regardless of channel.

Run multiple isolated bridges at once with CHROME_DEVTOOLS_AXI_SESSION - one per agent session, worktree, or test worker:

CHROME_DEVTOOLS_AXI_SESSION=worker-1 chrome-devtools-axi open https://example.com
CHROME_DEVTOOLS_AXI_SESSION=worker-2 chrome-devtools-axi open https://example.org

Each session name gets its own bridge process, port (auto-derived from the name, or pinned with CHROME_DEVTOOLS_AXI_PORT), and on-disk state. In the default --isolated and CHROME_DEVTOOLS_AXI_USER_DATA_DIR launch modes each bridge also launches its own Chrome, so concurrent sessions share neither browser state nor each other's stale-ref tracking. Sessions that attach to the same external browser - multiple CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1 sessions on one running Chrome, or the same CHROME_DEVTOOLS_AXI_BROWSER_URL/wsEndpoint - drive that shared browser and are isolated only at the bridge level, where the per-session generation counter does not prevent cross-talk. A session only isolates the bridge - the connection mode and profile are unchanged; combine with CHROME_DEVTOOLS_AXI_USER_DATA_DIR for a persistent per-session profile. The default (unset) session keeps port 9224 and the legacy state paths below.

Do not export CHROME_DEVTOOLS_AXI_PORT globally when running concurrent sessions: it overrides the per-session derived port and forces every session onto the same port, so the second session fails to start - its bridge cannot bind the already-taken port, and the first session's bridge is rejected as a mismatch rather than silently shared. Rely on the per-session default ports instead, or set CHROME_DEVTOOLS_AXI_PORT only inline per command.

State is stored in ~/.chrome-devtools-axi/ (named sessions nest under sessions/<name>/):

File	Purpose
bridge.pid	PID and port of the running bridge
snapshot-generation	Counter used to detect stale uid refs

Development

pnpm run build       # Compile TypeScript to dist/
pnpm run build:skill # Regenerate skills/chrome-devtools-axi/SKILL.md from shared CLI guidance and SDK built-ins
pnpm run dev         # Run CLI directly with tsx
pnpm test            # Run tests with vitest
pnpm run test:watch  # Run tests in watch mode

The committed skills/chrome-devtools-axi/SKILL.md is generated by pnpm run build:skill; pnpm test fails if it drifts from the shared CLI guidance or documented SDK built-ins. The generated skill frontmatter includes Hermes Agent metadata from src/skill.ts; update the generator instead of hand-editing the committed SKILL.md. The npm package includes skills/chrome-devtools-axi/, so published releases ship the same installable Agent Skill documented in Quick Start. Prettier intentionally ignores generator-owned files listed in .prettierignore; use their generator checks instead of formatting them by hand.