--- slug: "chrome-devtools-axi" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/kunchenguid/chrome-devtools-axi@main/README.md" repo: "https://github.com/kunchenguid/chrome-devtools-axi" source_file: "README.md" branch: "main" ---

chrome-devtools-axi

npm CI Release Platform X Discord

The most agent-ergonomic browser automation

`chrome-devtools-axi` wraps [chrome-devtools-mcp](https://www.npmjs.com/package/chrome-devtools-mcp) with an [AXI](https://axi.md)-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](https://axi.md) 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](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills): ```sh 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 ```sh $ 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:` 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: ```sh 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 ```sh 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](https://www.npmjs.com/package/@toon-format/toon) for compact, token-efficient output ## CLI Reference ### Navigation | Command | Description | | ----------------- | -------------------------------------------- | | `open ` | Navigate to URL and snapshot | | `snapshot` | Capture current page state | | `screenshot

` | Save a screenshot to a file | | `scroll

` | Scroll: up, down, top, bottom | | `back` | Navigate back | | `wait ` | Wait for time or text to appear | | `eval ` | Evaluate a JavaScript expression or function | | `run` | Execute a multi-step script from stdin | `eval` wraps plain input as `() => ()` 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. ```sh 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 @` | Click an element by ref | | `fill @ ` | Fill a form field | | `type ` | Type text at current focus | | `press ` | Press a keyboard key | | `hover @` | Hover over an element | | `drag @ @` | Drag an element onto another | | `fillform @=...` | Fill multiple form fields | | `dialog ` | Handle a browser dialog | | `upload @ ` | Upload a file through an input | ### Page Management | Command | Description | | ----------------- | --------------------------- | | `pages` | List all open tabs | | `newpage ` | Open a new tab | | `selectpage ` | Switch to a tab by ID | | `closepage ` | Close a tab by ID | | `resize ` | Resize the browser viewport | ### Emulation | Command | Description | | --------- | ------------------------------- | | `emulate` | Emulate device/network/viewport | ### DevTools Debugging | Command | Description | | ------------------ | ------------------------------ | | `console` | List console messages | | `console-get ` | 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 --response-file ` or `--request-file ` 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 ` | Analyze a performance insight | | `heap ` | 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 @` | Target a specific element (screenshot) | | `--full-page` | Capture entire scrollable page (screenshot) | | `--format ` | Image format: png, jpeg, webp (screenshot) | | `--viewport ` | Viewport like "390x844x3,mobile" (emulate) | | `--color-scheme ` | dark, light, or auto (emulate) | | `--network ` | Network throttle: Slow 3G, etc. (emulate) | | `--cpu ` | CPU throttling rate 1-20 (emulate) | | `--geolocation x` | Set geolocation (emulate) | | `--user-agent ` | Custom user agent (emulate) | | `--type ` | Filter by type (console, network) | | `--limit ` | Max items to return (console, network) | | `--page ` | Pagination (console, network) | | `--device ` | desktop or mobile (lighthouse) | | `--mode ` | navigation or snapshot (lighthouse) | | `--output-dir ` | Directory for reports (lighthouse) | | `--no-reload` | Skip page reload (perf-start) | | `--no-auto-stop` | Disable auto-stop (perf-start) | | `--file ` | Save trace data to file (perf-start/stop) | | `--response-file ` | Save response body (network-get) | | `--request-file ` | 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: ```sh export CHROME_DEVTOOLS_AXI_PORT=9225 ``` Connect to an existing Chrome instance instead of launching one: ```sh 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`: ```sh 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`: ```sh 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: ```sh 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//`): | File | Purpose | | --------------------- | ------------------------------------- | | `bridge.pid` | PID and port of the running bridge | | `snapshot-generation` | Counter used to detect stale uid refs | ## Development ```sh 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.