chrome-devtools-axi

Use chrome-devtools-axi when you want Chrome DevTools automation from the shell with agent-friendly output and stable accessibility refs.

Why This CLI

chrome-devtools-axi is a thin CLI over chrome-devtools-mcp that keeps a persistent bridge alive between commands. Its default workflow is efficient for agents:

• open and snapshot return an accessibility tree with uid= refs you can reuse as @<uid> in later commands.
• Responses include compact structured metadata plus a readable page snapshot.
• Console, network, Lighthouse, performance tracing, and heap capture are available from the same session.

Safe Invocation

Always disable the CLI's hook auto-install behavior when invoking it from this repo:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi --help

Use the same prefix for every command unless you intentionally want its global hook side effects.

If the task needs a visible browser, also set headed mode:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 CHROME_DEVTOOLS_AXI_HEADED=1 \
  npx -y chrome-devtools-axi open https://example.com

Useful environment variables:

• CHROME_DEVTOOLS_AXI_HEADED=1 runs Chrome visibly instead of headless.
• CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222 connects to an existing Chrome instance.
• CHROME_DEVTOOLS_AXI_PORT=9225 changes the local bridge port.
• CHROME_DEVTOOLS_AXI_USER_DATA_DIR=/path/to/profile uses a persistent Chrome profile.

Core Workflow

Start with the smallest command that gives you the next useful handle.

1. Open or select a page.
2. Capture a snapshot.
3. Reuse uid= refs from the snapshot as @<uid> for interaction.
4. Re-snapshot after navigation or DOM-changing actions.
5. Inspect console or network only when the page behavior is unclear.

Example loop:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi open http://localhost:5173
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi snapshot
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi click @3
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi wait 1000
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi snapshot

Ref-Based Interaction

Prefer AX refs over CSS selectors whenever the snapshot already exposes the target.

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi click @7
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi fill @12 "user@example.com"
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi hover @18
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi drag @4 @9
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi upload @22 ./fixtures/avatar.png

For keyboard-driven flows:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi type "search text"
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi press Enter

For multi-field forms:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi fillform \
  @12='user@example.com' @13='secret'

Navigation And Page State

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi open https://example.com
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi back
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi wait "Dashboard"
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi scroll down
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi screenshot ./tmp/page.png --full-page

Use wait <text> when waiting on visible content, and wait <ms> for small fixed delays.

Tabs And Page Selection

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi pages
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi newpage https://example.com
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi selectpage 1
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi closepage 1

When debugging popup or multi-tab flows, list pages after the action and switch explicitly.

Eval

Use eval for quick DOM or app-state inspection.

Plain expressions are wrapped automatically:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi eval "document.title"

For multi-statement logic, pass an IIFE or function yourself:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi eval \
  "(() => Array.from(document.querySelectorAll('button')).map((button) => button.textContent?.trim()))()"

Console And Network

Use these when interaction alone does not explain failures.

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi console --type error --limit 20
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi console-get 3

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi network --type fetch --limit 20
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi network-get 12
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi network-get 12 \
  --request-file ./tmp/request.txt --response-file ./tmp/response.txt

Use --page to paginate when there are many results. Reach for console-get or network-get before rerunning broad list commands with much larger limits.

Emulation, Accessibility, And Visual Checks

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi emulate \
  --viewport 390x844x3,mobile --color-scheme light --network 'Fast 3G'

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi resize 1440 900
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi screenshot ./tmp/mobile.png --full-page

The accessibility snapshot is the default inspection surface. Use it first for structure, names, roles, and actionable targets before resorting to eval.

Lighthouse And Performance

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi lighthouse --mode navigation --device desktop

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi perf-start --file ./tmp/trace.json --no-auto-stop
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi perf-stop --file ./tmp/trace.json
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi perf-insight <set> LCPBreakdown

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi heap ./tmp/app.heapsnapshot

Use Lighthouse for a broad audit. Use perf tracing when you need to inspect a specific interaction or page load more closely.

Running Multi-Step Scripts

Use run when a longer interaction is easier to express as a script than as separate shell calls.

Feed commands on stdin and keep the script focused on one scenario.

Session Management

The CLI auto-starts its bridge on first use, but explicit control is available:

env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi start
env CHROME_DEVTOOLS_AXI_DISABLE_HOOKS=1 npx -y chrome-devtools-axi stop

State lives under ~/.chrome-devtools-axi/, including the bridge PID file.

Practical Guidance

• Prefer snapshot before guessing targets.
• Prefer @<uid> refs over brittle selectors.
• Re-snapshot after clicks, form submits, navigation, or dialog handling.
• Keep output small by using default limits first; add --full only when truncation hides needed detail.
• Use headed mode for visual debugging, hover states, or anything timing-sensitive.
• Use CHROME_DEVTOOLS_AXI_BROWSER_URL when a task needs to attach to an already-running Chrome session.