Chrome DevTools AXI
When to use
Use this skill when the task specifically needs chrome-devtools-axi or a
Chrome DevTools Protocol browser controlled from the terminal:
- the user says
chrome-devtools-axi, chrome-devtools-mcp, AXI browser automation, or asks to run npx -y chrome-devtools-axi
- an agent needs a compact accessibility snapshot with actionable refs and command suggestions
- browser work needs console logs, network requests, screenshots, Lighthouse, heap snapshots, or performance traces in the same CLI surface
- the existing Hermes/browser stack is unavailable or the user explicitly prefers this tool
Do not use it for ordinary web search, curl-able pages, static extraction,
or stealth/anti-detection work. Use Camofox/Camoufox only when cloaking is
load-bearing. Use built-in browser tools when the task is already solved there
and the user did not name chrome-devtools-axi.
Mental model
chrome-devtools-axi is an npm CLI wrapper around chrome-devtools-mcp. The
first command starts a persistent local bridge, then later invocations reuse the
same Chrome/DevTools session. Output is AXI/TOON-style: page metadata,
accessibility snapshots, element refs, and next-step suggestions.
State lives under ~/.chrome-devtools-axi/, including the bridge PID and
snapshot-generation counter.
Setup and verification
The skill only teaches the agent how to use the tool. The actual CLI is the npm
package chrome-devtools-axi; source repo:
https://github.com/kunchenguid/chrome-devtools-axi
Prefer npx for one-off use so the CLI is installed on demand:
npx -y chrome-devtools-axi --help
npx -y chrome-devtools-axi
Use a global install only when repeated shell use matters:
npm install -g chrome-devtools-axi
chrome-devtools-axi --help
Before relying on the tool, verify the live CLI rather than assuming docs are
current:
npx -y chrome-devtools-axi --version
npx -y chrome-devtools-axi --help
If the home view says browser: no active session, open a page:
npx -y chrome-devtools-axi open https://example.com
Core workflow
-
Start from the current state or open a page:
npx -y chrome-devtools-axi
npx -y chrome-devtools-axi open https://example.com
-
Use the latest snapshot refs exactly as printed. They look like @g<N>:...
and may include underscores, for example @g4:1_3:
npx -y chrome-devtools-axi click @<uid>
npx -y chrome-devtools-axi fill @<uid> "search text"
npx -y chrome-devtools-axi press Enter
-
Re-snapshot after every state-changing action:
npx -y chrome-devtools-axi snapshot
-
Inspect browser diagnostics when debugging app behavior:
npx -y chrome-devtools-axi console --type error --limit 20
npx -y chrome-devtools-axi network --type fetch --limit 20
npx -y chrome-devtools-axi network-get <id> --response-file /tmp/response.json
-
Stop the bridge when preserving the browser session is not useful:
npx -y chrome-devtools-axi stop
Ref discipline
Refs include a generation prefix such as @g1:1_7. Treat refs as scoped to the
latest accessibility snapshot.
Hard rules:
- Pass refs back exactly as printed, including
@ and the generation prefix.
- Re-snapshot after navigation, click, form submit, scroll, dialog handling,
upload, drag, JS mutation, page selection, or resize.
- If a command fails with
STALE_REF, do not retry the same ref blindly.
Snapshot again, find the new ref, then retry.
- Prefer refs over CSS selectors or DOM guessing. Use
eval only when the
accessibility surface cannot expose the needed state.
Command usage policy
Do not treat this skill as the CLI reference. For exact flags and subcommands,
run the live help first:
npx -y chrome-devtools-axi --help
Use this skill for durable agent judgment: when to choose the tool, how to
sequence work, which commands are high leverage, how to verify actions, and
which modes are privacy-sensitive.
Best-practice scenarios
Explore or verify a page. Open the URL, snapshot it, then verify with URL,
title, DOM, or screenshot evidence before reporting success:
npx -y chrome-devtools-axi open https://example.com
npx -y chrome-devtools-axi snapshot
npx -y chrome-devtools-axi eval "document.title"
npx -y chrome-devtools-axi screenshot /tmp/page.png
Interact with a page or form. Use refs from the latest snapshot exactly as
printed, then re-snapshot after each state-changing action:
npx -y chrome-devtools-axi click @<uid>
npx -y chrome-devtools-axi fill @<uid> "value"
npx -y chrome-devtools-axi press Enter
npx -y chrome-devtools-axi snapshot
Debug a web app. Check console and network before guessing. Save large
request/response bodies to files instead of dumping them into chat:
npx -y chrome-devtools-axi console --type error --limit 20
npx -y chrome-devtools-axi network --type fetch --limit 20
npx -y chrome-devtools-axi network-get <id> --response-file /tmp/response.json
Use existing Chrome or logged-in state. Prefer a fresh isolated browser.
Connect to an existing browser/profile only when the task requires it and the
user has authorized that scope:
CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222 npx -y chrome-devtools-axi snapshot
CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1 npx -y chrome-devtools-axi snapshot
CHROME_DEVTOOLS_AXI_USER_DATA_DIR="$HOME/.chrome-devtools-axi/profile" npx -y chrome-devtools-axi open https://example.com
Handle slow cold starts. If repeated commands are slow because the bridge is
bootstrapping chrome-devtools-mcp through npx, use the CLI help's current
CHROME_DEVTOOLS_AXI_MCP_PATH recipe rather than inventing a path.
Use visual/GPU-sensitive pages. For WebGL/WebGPU/GPU debugging, use headed
mode and Chrome flags from the live help. Do not persist broad Chrome flags
globally.
For run, emulate, Lighthouse, performance traces, heap snapshots, or less
common flags, consult --help/upstream docs at the moment of use instead of
copying examples from memory.
Existing Chrome, headed mode, and profiles
Use environment variables inline for a single command or process when possible.
Do not persist them globally unless the user explicitly wants that behavior.
Treat persistent profiles as privacy-sensitive. Do not browse authenticated
accounts, export cookies, or inspect private content unless the user explicitly
authorizes that scope.
Diagnostics and performance
For app debugging, prefer the CLI's console/network commands before guessing.
Only run Lighthouse, traces, and heap snapshots when they materially help; they
are slower and noisier than simple snapshots, console checks, and network lists.
Safety and privacy
- Do not run
setup hooks unless the user explicitly asks to install ambient
agent hooks. It mutates local agent configuration.
- Do not print
CHROME_DEVTOOLS_AXI_WS_HEADERS; it may contain bearer tokens.
- Do not use a persistent
CHROME_DEVTOOLS_AXI_USER_DATA_DIR casually; it can
carry login state and browsing history.
- Do not claim a browser action succeeded until a fresh snapshot, URL/title,
screenshot, console/network result, or DOM evaluation verifies it.
- Close pages or stop the bridge when done unless keeping state is useful for
the user's next step.
Common failure handling
- No active session: run
open <url>.
- Stale ref: run
snapshot, find the new ref, retry once.
- Slow first command: the bridge may be bootstrapping
chrome-devtools-mcp
through npx. If repeated cold starts hurt, globally install
chrome-devtools-mcp and use CHROME_DEVTOOLS_AXI_MCP_PATH as described in
chrome-devtools-axi --help.
- Wrong tab: run
pages, then selectpage <id> and snapshot.
- Need the user's normal Chrome: use
CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1
only when remote debugging is enabled and connecting to that browser is
intentional.
