{ "markdown": "

chrome-devtools-axi

\n\n

\n \"npm\"\n \"CI\"\n \"Release\"\n \"Platform\"\n \"X\"\n \"Discord\"\n

\n\n

The most agent-ergonomic browser automation

\n\n`chrome-devtools-axi` wraps [chrome-devtools-mcp](https://www.npmjs.com/package/chrome-devtools-mcp) with an [AXI](https://axi.md)-compliant CLI.\n\n- **Token-efficient** — TOON-encoded output cuts token usage ~40% vs raw JSON\n- **Combined operations** — one command navigates, captures, and suggests next steps\n- **Contextual suggestions** — every response includes actionable next-step hints\n\n## Benchmarks\n\nAgent ergonomics is measurable.\nThe [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.\n\nchrome-devtools-axi posts the lowest input tokens, cost, duration, and turn count of all 7 conditions, with 100% task success:\n\n| Condition | Avg Input Tokens | Avg Cost/Task | Avg Duration | Avg Turns | Success |\n| ------------------------------------ | ---------------- | ------------- | ------------ | --------- | -------- |\n| **chrome-devtools-axi** | **79,141** | **$0.074** | **21.5s** | **4.5** | **100%** |\n| dev-browser | 82,532 | $0.078 | 28.6s | 4.9 | 99% |\n| agent-browser (Vercel) | 93,074 | $0.088 | 24.6s | 4.8 | 99% |\n| chrome-devtools-mcp + compressor CLI | 130,779 | $0.091 | 29.7s | 7.6 | 100% |\n| chrome-devtools-mcp + ToolSearch | 133,712 | $0.096 | 29.4s | 7.5 | 99% |\n| chrome-devtools-mcp (raw MCP) | 184,711 | $0.101 | 26.0s | 6.2 | 99% |\n| chrome-devtools-mcp code execution | 129,606 | $0.120 | 36.2s | 6.4 | 100% |\n\nAgainst raw chrome-devtools-mcp - the very server this CLI wraps - that is 57% fewer input tokens, 26% lower cost, and 27% fewer agent turns.\n\n## Quick Start\n\nInstall the chrome-devtools-axi skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):\n\n```sh\nnpx skills add kunchenguid/chrome-devtools-axi --skill chrome-devtools-axi -g\n```\n\nThat is the entire setup - no npm install needed.\nThe skill teaches your agent to run chrome-devtools-axi through `npx -y chrome-devtools-axi`, so the CLI comes along on demand.\n\nThe skill is not a user-facing slash command (`user-invocable: false`).\nJust 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.\nFor ordinary web search, curl-able pages, or static extraction, the skill tells agents to skip Chrome and use simpler fetch/curl-style tooling.\nThe 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.\n\n`-g` installs the skill for all projects (`~/.claude/skills/`, for example); drop it to install for the current project only (`.claude/skills/`).\n\n## What Agent Sees\n\n```sh\n$ chrome-devtools-axi open https://example.com\npage: {title: \"Example Domain\", url: \"https://example.com\", refs: 1}\nsnapshot:\nRootWebArea \"Example Domain\"\n heading \"Example Domain\"\n paragraph \"This domain is for use in illustrative examples...\"\n uid=g1:1 link \"More information...\"\nhelp[1]:\n Run `chrome-devtools-axi click @g1:1` to click the \"More information...\" link\n\n$ chrome-devtools-axi click @g1:1\npage: {title: \"IANA — IANA-Managed Reserved Domains\", refs: 12}\nsnapshot:\n...\n```\n\nRefs in snapshot output carry a `g:` generation prefix that bumps every time a new accessibility tree is captured. Pass refs back exactly as printed. UID actions also verify that the tracked page has not mutated since that snapshot; if freshness cannot be confirmed (including for a legacy untagged ref), they fail loudly with `STALE_REF` instead of silently no-op'ing, so the agent re-snapshots and retries.\nThe 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.\n\n## Other Ways to Install\n\nThe skill is the recommended path, but it is not the only one.\n\n### Zero setup\n\nchrome-devtools-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all.\nJust tell your agent:\n\n```\nExecute `npx -y chrome-devtools-axi` to get browser automation tools.\n```\n\n### Session hook\n\nWant ambient browser context - including the live page state of an active session - fed into every agent session instead of loading on demand?\nInstall the CLI globally and opt into the hook:\n\n```sh\nnpm install -g chrome-devtools-axi\nchrome-devtools-axi setup hooks\n```\n\nThis 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.\n**Restart your agent session after running this** so the new hook takes effect.\n\nDevelopment entrypoints such as `pnpm run dev` and `bin/chrome-devtools-axi.ts` are guarded from accidental hook installation.\n\n### From source\n\n```sh\ngit clone https://github.com/kunchenguid/chrome-devtools-axi.git\ncd chrome-devtools-axi\npnpm install --frozen-lockfile\npnpm run build\npnpm link\n```\n\n## How It Works\n\n```\n┌───────────────────────┐\n│ chrome-devtools-axi │ CLI — parse args, format output\n└──────────┬────────────┘\n │ HTTP (localhost:9224)\n ▼\n┌───────────────────────┐\n│ Bridge Server │ Persistent process, manages MCP session\n└──────────┬────────────┘\n │ stdio\n ▼\n┌───────────────────────┐\n│ chrome-devtools-mcp │ Headless Chrome via DevTools Protocol\n└───────────────────────┘\n```\n\n- **Persistent bridge** — a detached process keeps the MCP session alive across commands, so Chrome doesn't restart every invocation\n- **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\n- **Snapshot parsing** — accessibility tree snapshots are extracted and analyzed for interactive elements (`uid=` refs)\n- **TOON encoding** — structured metadata uses [TOON format](https://www.npmjs.com/package/@toon-format/toon) for compact, token-efficient output\n\n## CLI Reference\n\n### Navigation\n\n| Command | Description |\n| ----------------- | -------------------------------------------- |\n| `open ` | Navigate to URL and snapshot |\n| `snapshot` | Capture current page state |\n| `screenshot

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

` | Scroll: up, down, top, bottom |\n| `back` | Navigate back |\n| `wait ` | Wait for time or text to appear |\n| `eval ` | Evaluate a JavaScript expression or function |\n| `run` | Execute a multi-step script from stdin |\n\n`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.\n\n```sh\nchrome-devtools-axi eval \"document.title\"\nchrome-devtools-axi eval \"() => { const rows = [...document.querySelectorAll('tr')]; return rows.map((row) => row.textContent) }\"\n```\n\n### Interaction\n\n| Command | Description |\n| -------------------------- | ------------------------------ |\n| `click @` | Click an element by ref |\n| `fill @ ` | Fill a form field |\n| `type ` | Type text at current focus |\n| `press ` | Press a keyboard key |\n| `hover @` | Hover over an element |\n| `drag @ @` | Drag an element onto another |\n| `fillform @=...` | Fill multiple form fields |\n| `dialog ` | Handle a browser dialog |\n| `upload @ ` | Upload a file through an input |\n\n### Page Management\n\n| Command | Description |\n| ----------------- | --------------------------- |\n| `pages` | List all open tabs |\n| `newpage ` | Open a new tab |\n| `selectpage ` | Switch to a tab by ID |\n| `closepage ` | Close a tab by ID |\n| `resize ` | Resize the browser viewport |\n\n### Emulation\n\n| Command | Description |\n| --------- | ------------------------------- |\n| `emulate` | Emulate device/network/viewport |\n\n### DevTools Debugging\n\n| Command | Description |\n| ------------------ | ------------------------------ |\n| `console` | List console messages |\n| `console-get ` | Get a specific console message |\n| `network` | List network requests |\n| `network-get [id]` | Get a specific network request |\n\nFor large request or response bodies, prefer `network-get --response-file ` or `--request-file ` so the body goes to disk instead of flooding agent context.\n\n### Performance\n\n| Command | Description |\n| --------------------------- | ----------------------------- |\n| `lighthouse` | Run a Lighthouse audit |\n| `perf-start` | Start a performance trace |\n| `perf-stop` | Stop the performance trace |\n| `perf-insight ` | Analyze a performance insight |\n| `heap ` | Capture a heap snapshot |\n\n### Bridge\n\n| Command | Description |\n| ------------- | ----------------------------- |\n| `start` | Start the bridge server |\n| `stop` | Stop the bridge server |\n| `setup hooks` | Install or repair agent hooks |\n\n### Maintenance\n\n| Command | Description |\n| ---------------- | ------------------------------------------------------ |\n| `update` | Upgrade the installed CLI to the latest npm version |\n| `update --check` | Report current vs latest version without installing it |\n\nRunning with no command shows the CLI home view. It prepends `bin` and\n`description` metadata, then includes the current snapshot when a browser\nsession is active or the no-session status/help block when one is not.\n\n### Flags\n\n`--help`, `-v`, `-V`, and `--version` are top-level options. All other flags\nare command-specific; the CLI rejects a flag that is not listed by\n`chrome-devtools-axi --help`.\n\n| Flag | Description |\n| --------------------------- | ------------------------------------------- |\n| `--help` | Show usage information |\n| `-v`, `-V`, `--version` | Show the installed CLI version |\n| `--check` | Check for available updates (update) |\n| `--full` | Show complete output without truncation |\n| `--background` | Open new page in background (newpage) |\n| `--uid @` | Target a specific element (screenshot) |\n| `--full-page` | Capture entire scrollable page (screenshot) |\n| `--format ` | Image format: png, jpeg, webp (screenshot) |\n| `--viewport ` | Viewport like \"390x844x3,mobile\" (emulate) |\n| `--color-scheme ` | dark, light, or auto (emulate) |\n| `--network ` | Network throttle: Slow 3G, etc. (emulate) |\n| `--cpu ` | CPU throttling rate 1-20 (emulate) |\n| `--geolocation x` | Set geolocation (emulate) |\n| `--user-agent ` | Custom user agent (emulate) |\n| `--type ` | Filter by type (console, network) |\n| `--limit ` | Max items to return (console, network) |\n| `--page ` | Pagination (console, network) |\n| `--device ` | desktop or mobile (lighthouse) |\n| `--mode ` | navigation or snapshot (lighthouse) |\n| `--output-dir ` | Directory for reports (lighthouse) |\n| `--no-reload` | Skip page reload (perf-start) |\n| `--no-auto-stop` | Disable auto-stop (perf-start) |\n| `--file ` | Save trace data to file (perf-start/stop) |\n| `--response-file ` | Save response body (network-get) |\n| `--request-file ` | Save request body (network-get) |\n\nLocal 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.\nSaved-path output uses the resolved absolute path.\n\n`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`.\n`network --type` accepts `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `prefetch`, `eventsource`, `websocket`, `manifest`, `signedexchange`, `ping`, `cspviolationreport`, `preflight`, `fedcm`, `other`, and `all`.\nFor both commands, `all` or an omitted `--type` returns every item.\n\n## Configuration\n\nThe bridge server port defaults to `9224`. Override it with an environment variable:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_PORT=9225\n```\n\nConnect to an existing Chrome instance instead of launching one:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222\n```\n\n`CHROME_DEVTOOLS_AXI_BROWSER_URL` accepts both `http://` or `https://` URLs and `ws://` or `wss://` endpoints:\n\n- `http(s)://` uses `--browserUrl` and fetches `/json/version` to discover the WebSocket URL.\n- `ws(s)://` uses `--wsEndpoint` directly.\n\nFor authenticated `ws://` or `wss://` endpoints, pass JSON headers with `CHROME_DEVTOOLS_AXI_WS_HEADERS`:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_BROWSER_URL=wss://cluster.example/launch\nexport CHROME_DEVTOOLS_AXI_WS_HEADERS='{\"Authorization\":\"Bearer token\"}'\n```\n\nPick which installed Chrome release channel to target with `CHROME_DEVTOOLS_AXI_CHANNEL` - `stable` (the default), `beta`, `canary`, or `dev`:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1\nexport CHROME_DEVTOOLS_AXI_CHANNEL=beta\n```\n\nThis selects which Chrome `--autoConnect` attaches to, and which one is launched in the default and `CHROME_DEVTOOLS_AXI_USER_DATA_DIR` modes.\nIt is ignored when `CHROME_DEVTOOLS_AXI_BROWSER_URL` is set, since that connects to an explicit endpoint regardless of channel.\n\n### Keychain isolation\n\nWhen chrome-devtools-axi launches Chrome itself - the default `--isolated` mode and `CHROME_DEVTOOLS_AXI_USER_DATA_DIR` - it always passes `--use-mock-keychain` and `--password-store=basic`.\nAn automation browser has no business reading, writing, or offering to reset your OS password store, so it is kept off it entirely.\nPassword autofill and saved-password access are therefore intentionally unavailable inside browsers this tool launches.\nOn macOS this also means the browser can never raise the system \"Keychain Not Found ... Reset To Defaults\" panel, which Chrome triggers when it tries to store its `Chrome Safe Storage` key and no default keychain can be resolved for the process.\n\nYour own externally launched Chrome is unaffected: its saved passwords remain available and untouched because this tool does not read, write, move, or reset the login keychain or its `Chrome Safe Storage` item.\nThe isolation flags apply only to browsers this tool starts and are deliberately not sent in the `CHROME_DEVTOOLS_AXI_AUTO_CONNECT`, `CHROME_DEVTOOLS_AXI_BROWSER_URL`, and `wsEndpoint` modes, where the browser belongs to whoever launched it.\n\nRun multiple isolated bridges at once with `CHROME_DEVTOOLS_AXI_SESSION` - one per agent session, worktree, or test worker:\n\n```sh\nCHROME_DEVTOOLS_AXI_SESSION=worker-1 chrome-devtools-axi open https://example.com\nCHROME_DEVTOOLS_AXI_SESSION=worker-2 chrome-devtools-axi open https://example.org\n```\n\nEach session name gets its own bridge process, port (auto-derived from the name, or pinned with `CHROME_DEVTOOLS_AXI_PORT`), and on-disk state.\nIn 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.\nSessions 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.\nA 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.\nThe default (unset) session keeps port 9224 and the legacy state paths below.\n\nDo 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.\nRely on the per-session default ports instead, or set `CHROME_DEVTOOLS_AXI_PORT` only inline per command.\n\nState is stored in `~/.chrome-devtools-axi/` (named sessions nest under `sessions//`):\n\n| File | Purpose |\n| --------------------- | ------------------------------------- |\n| `bridge.pid` | PID and port of the running bridge |\n| `snapshot-generation` | Counter used to detect stale uid refs |\n\n## Development\n\n```sh\npnpm run build # Compile TypeScript to dist/\npnpm run build:skill # Regenerate the minimal skills/chrome-devtools-axi/SKILL.md stub from src/skill.ts\npnpm run dev # Run CLI directly with tsx\npnpm test # Run tests with vitest\npnpm run test:watch # Run tests in watch mode\n```\n\nThe committed `skills/chrome-devtools-axi/SKILL.md` is a minimal discovery stub generated by `pnpm run build:skill`; it points to the CLI for current guidance, and `pnpm test` fails if it drifts from `createSkillMarkdown()`.\nThe generated skill and its frontmatter are owned by `src/skill.ts`; update the generator instead of hand-editing the committed `SKILL.md`.\nThe npm package includes `skills/chrome-devtools-axi/`, so published releases ship the same installable Agent Skill documented in Quick Start.\nPrettier intentionally ignores generator-owned files listed in `.prettierignore`; use their generator checks instead of formatting them by hand.\n", "bytes": 20696, "sha": "369991ba2ca5012678e1418251f36a731d0cd718ee695a2eb7bb810410d30101", "repo_slug": "kunchenguid/chrome-devtools-axi", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_kunchenguid_chrome_devtools_axi_chrome_d_c6e82687/readme" }