Skip to content
Back to search

chrome-devtools-axi

The most agent-ergonomic browser automation

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunchenguid-chrome-devtools-axi/badge.svg)](/listings/kunchenguid-chrome-devtools-axi)

HTML

<a href="/listings/kunchenguid-chrome-devtools-axi"><img src="/api/listings/kunchenguid-chrome-devtools-axi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the chrome-devtools-axi skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 532 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">chrome-devtools-axi</h1>
  2. <p align="center">
  3. <a href="https://www.npmjs.com/package/chrome-devtools-axi"><img alt="npm" src="https://img.shields.io/npm/v/chrome-devtools-axi?style=flat-square" /></a>
  4. <a href="https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/ci.yml?style=flat-square&label=CI" /></a>
  5. <a href="https://github.com/kunchenguid/chrome-devtools-axi/actions/workflows/release-please.yml"><img alt="Release" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/release-please.yml?style=flat-square&label=Release" /></a>
  6. <a href="#"><img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" /></a>
  7. <a href="https://x.com/kunchenguid"><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square" /></a>
  8. <a href="https://discord.gg/Wsy2NpnZDu"><img alt="Discord" src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord" /></a>
  9. </p>
  10. <h3 align="center">The most agent-ergonomic browser automation</h3>
  11. `chrome-devtools-axi` wraps [chrome-devtools-mcp](https://www.npmjs.com/package/chrome-devtools-mcp) with an [AXI](https://axi.md)-compliant CLI.
  12. - **Token-efficient** — TOON-encoded output cuts token usage ~40% vs raw JSON
  13. - **Combined operations** — one command navigates, captures, and suggests next steps
  14. - **Contextual suggestions** — every response includes actionable next-step hints
  15. ## Benchmarks
  16. Agent ergonomics is measurable.
  17. 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.
  18. chrome-devtools-axi posts the lowest input tokens, cost, duration, and turn count of all 7 conditions, with 100% task success:
  19. | Condition | Avg Input Tokens | Avg Cost/Task | Avg Duration | Avg Turns | Success |
  20. | ------------------------------------ | ---------------- | ------------- | ------------ | --------- | -------- |
  21. | **chrome-devtools-axi** | **79,141** | **$0.074** | **21.5s** | **4.5** | **100%** |
  22. | dev-browser | 82,532 | $0.078 | 28.6s | 4.9 | 99% |
  23. | agent-browser (Vercel) | 93,074 | $0.088 | 24.6s | 4.8 | 99% |
  24. | chrome-devtools-mcp + compressor CLI | 130,779 | $0.091 | 29.7s | 7.6 | 100% |
  25. | chrome-devtools-mcp + ToolSearch | 133,712 | $0.096 | 29.4s | 7.5 | 99% |
  26. | chrome-devtools-mcp (raw MCP) | 184,711 | $0.101 | 26.0s | 6.2 | 99% |
  27. | chrome-devtools-mcp code execution | 129,606 | $0.120 | 36.2s | 6.4 | 100% |
  28. 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.
  29. ## Quick Start
  30. Install the chrome-devtools-axi skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):
  31. ```sh
  32. npx skills add kunchenguid/chrome-devtools-axi --skill chrome-devtools-axi -g
  33. ```
  34. That is the entire setup - no npm install needed.
  35. The skill teaches your agent to run chrome-devtools-axi through `npx -y chrome-devtools-axi`, so the CLI comes along on demand.
  36. The skill is not a user-facing slash command (`user-invocable: false`).
  37. 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.
  38. For ordinary web search, curl-able pages, or static extraction, the skill tells agents to skip Chrome and use simpler fetch/curl-style tooling.
  39. 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.
  40. `-g` installs the skill for all projects (`~/.claude/skills/`, for example); drop it to install for the current project only (`.claude/skills/`).
  41. ## What Agent Sees
  42. ```sh
  43. $ chrome-devtools-axi open https://example.com
  44. page: {title: "Example Domain", url: "https://example.com", refs: 1}
  45. snapshot:
  46. RootWebArea "Example Domain"
  47. heading "Example Domain"
  48. paragraph "This domain is for use in illustrative examples..."
  49. uid=g1:1 link "More information..."
  50. help[1]:
  51. Run `chrome-devtools-axi click @g1:1` to click the "More information..." link
  52. $ chrome-devtools-axi click @g1:1
  53. page: {title: "IANA — IANA-Managed Reserved Domains", refs: 12}
  54. snapshot:
  55. ...
  56. ```
  57. 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. 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.
  58. 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.
  59. ## Other Ways to Install
  60. The skill is the recommended path, but it is not the only one.
  61. ### Zero setup
  62. chrome-devtools-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all.
  63. Just tell your agent:
  64. ```
  65. Execute `npx -y chrome-devtools-axi` to get browser automation tools.
  66. ```
  67. ### Session hook
  68. Want ambient browser context - including the live page state of an active session - fed into every agent session instead of loading on demand?
  69. Install the CLI globally and opt into the hook:
  70. ```sh
  71. npm install -g chrome-devtools-axi
  72. chrome-devtools-axi setup hooks
  73. ```
  74. 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.
  75. **Restart your agent session after running this** so the new hook takes effect.
  76. Development entrypoints such as `pnpm run dev` and `bin/chrome-devtools-axi.ts` are guarded from accidental hook installation.
  77. ### From source
  78. ```sh
  79. git clone https://github.com/kunchenguid/chrome-devtools-axi.git
  80. cd chrome-devtools-axi
  81. pnpm install --frozen-lockfile
  82. pnpm run build
  83. pnpm link
  84. ```
  85. ## How It Works
  86. The bridge keeps one persistent MCP session across CLI invocations. With no
  87. shared URL (or a blank one), standalone mode uses the local stdio process chain
  88. below. See [Configuration](#configuration) for the two shared-service choices.
  89. ```
  90. ┌───────────────────────┐
  91. │ chrome-devtools-axi │ CLI — parse args, format output
  92. └──────────┬────────────┘
  93. │ HTTP (localhost:9224)
  94. ▼
  95. ┌───────────────────────┐
  96. │ Bridge Server │ Persistent process, manages MCP session
  97. └──────────┬────────────┘
  98. │ stdio
  99. ▼
  100. ┌───────────────────────┐
  101. │ chrome-devtools-mcp │ Headless Chrome via DevTools Protocol
  102. └───────────────────────┘
  103. ```
  104. In URL-only shared mode, the bridge uses Streamable HTTP directly instead:
  105. ```
  106. ┌───────────────────────┐
  107. │ chrome-devtools-axi │ CLI — parse args, format output
  108. └──────────┬────────────┘
  109. │ HTTP (localhost:9224)
  110. ▼
  111. ┌───────────────────────┐
  112. │ Bridge Server │ Persistent per-session MCP client
  113. └──────────┬────────────┘
  114. │ Streamable HTTP
  115. ▼
  116. ┌───────────────────────┐
  117. │ Shared MCP service │ One remote MCP process + Chrome
  118. └───────────────────────┘
  119. ```
  120. - **Persistent bridge** — a detached process keeps the selected MCP session alive across commands, so Chrome doesn't restart every invocation
  121. - **Auto-lifecycle** — the bridge starts on first command, writes a PID file to `~/.chrome-devtools-axi/bridge.pid`, and is reused only after a deep health check (`/health?deep=1`, one CDP `list_pages`). A bridge whose browser has died is terminated and respawned. Startup waits until `CHROME_DEVTOOLS_AXI_BRIDGE_TIMEOUT_MS` (default 30s). On stop, the bridge kills its process group; teardown escalates SIGTERM to SIGKILL, and only when `ps` confirms that PID is a bridge, so stdio-launched chrome-devtools-mcp and Chrome children are reaped. A bridge also shuts itself down when its stdio chrome-devtools-mcp process exits, since it can serve nothing without it. Otherwise it runs until `stop` unless you opt into an [idle timeout](#idle-timeout).
  122. - **Snapshot parsing** — accessibility tree snapshots are extracted and analyzed for interactive elements (`uid=` refs)
  123. - **TOON encoding** — structured metadata uses [TOON format](https://www.npmjs.com/package/@toon-format/toon) for compact, token-efficient output
  124. ## CLI Reference
  125. ### Navigation
  126. | Command | Description |
  127. | ----------------- | -------------------------------------------- |
  128. | `open <url>` | Navigate to URL and snapshot |
  129. | `snapshot` | Capture current page state |
  130. | `screenshot <p>` | Save a screenshot to a file |
  131. | `scroll <dir>` | Scroll: up, down, top, bottom |
  132. | `back` | Navigate back |
  133. | `reload` | Reload the selected page and snapshot |
  134. | `wait <ms\|text>` | Wait for time or text to appear |
  135. | `eval <js>` | Evaluate a JavaScript expression or function |
  136. | `run` | Execute a multi-step script from stdin |
  137. `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.
  138. ```sh
  139. chrome-devtools-axi eval "document.title"
  140. chrome-devtools-axi eval "() => { const rows = [...document.querySelectorAll('tr')]; return rows.map((row) => row.textContent) }"
  141. ```
  142. ### Interaction
  143. | Command | Description |
  144. | -------------------------- | ------------------------------ |
  145. | `click @<uid>` | Click an element by ref |
  146. | `fill @<uid> <text>` | Fill a form field |
  147. | `type <text>` | Type text at current focus |
  148. | `press <key>` | Press a keyboard key |
  149. | `hover @<uid>` | Hover over an element |
  150. | `drag @<from> @<to>` | Drag an element onto another |
  151. | `fillform @<uid>=<val>...` | Fill multiple form fields |
  152. | `dialog <accept\|dismiss>` | Handle a browser dialog |
  153. | `upload @<uid> <path>` | Upload a file through an input |
  154. `press` delivers keys to the page via CDP `Input.dispatchKeyEvent`, not as
  155. browser commands. Browser shortcuts such as `Meta+R`, `Ctrl+R`, and `Meta+L`
  156. do not trigger browser actions. To refresh the selected page, use
  157. `chrome-devtools-axi reload` (or `chrome-devtools-axi eval '() => location.reload()'`).
  158. Like other snapshot-producing commands, `reload` accepts `--full` for an
  159. untruncated snapshot.
  160. ### Page Management
  161. | Command | Description |
  162. | ----------------- | --------------------------- |
  163. | `pages` | List all open tabs |
  164. | `newpage <url>` | Open a new tab |
  165. | `selectpage <id>` | Switch to a tab by ID |
  166. | `closepage <id>` | Close a tab by ID |
  167. | `resize <w> <h>` | Resize the browser viewport |
  168. By default, `newpage` and `selectpage` print the automatic accessibility tree
  169. and snapshot-derived suggestions. Use `--no-snapshot` when navigating to a page
  170. and continuing with `eval` or another chained command without needing element
  171. UIDs. It suppresses only the printed tree and its derived guidance: capture
  172. still runs, preserving page metadata and fresh element-reference generations.
  173. Leave it off for UID-based `click`/`fill` workflows, or run `snapshot` explicitly.
  174. The flag may appear before or after the URL/page ID and takes precedence over
  175. `--full`.
  176. ```sh
  177. chrome-devtools-axi newpage https://example.com --no-snapshot
  178. chrome-devtools-axi selectpage 1 --no-snapshot
  179. ```
  180. Tabs share one cookie jar unless `newpage` is given `--context <name>`. That opens the tab in a separate browser context (chrome-devtools-mcp's `isolatedContext`) with its own cookies and storage, so one browser can hold two sign-ins at once or a signed-out view beside a signed-in one. Later `newpage --context` calls with the same name join that context. Names are kept by the bridge, so each named session has its own, and after the bridge stops a name starts a fresh context. Stopping the bridge closes Chrome when AXI launched it; in a browser something else started (`CHROME_DEVTOOLS_AXI_BROWSER_URL` or `CHROME_DEVTOOLS_AXI_AUTO_CONNECT`), tabs already open in the old context stay open. Names use 1-64 characters from `[A-Za-z0-9._-]`, not starting with `-`.
  181. ```sh
  182. chrome-devtools-axi newpage https://example.com --context signed-out
  183. ```
  184. `resize` reads the page's viewport back and fails, naming the actual size, when it did not reach the requested size (an emulated viewport, page zoom or the window's minimum size can hold it); use `emulate --viewport` then.
  185. Page-scoped tools require a selected page. `pages` only lists tabs and never changes the selection. `selectpage` sets it. `newpage` (and `open` when it has to create a tab) selects the tab chrome-devtools-mcp reports as selected in its own listing, which is the tab it just created, even when that URL is already open in another tab or changed while loading; a title continuation, no marked row, more than one `[selected]` line anywhere in the listing, a repeated `## Pages` section or page id, or chrome-devtools-mcp's note that it moved its selection off a closed tab leaves the selection unset, and the next page-scoped command fails until `selectpage`. The selected column in `pages` is AXI's selection, not the MCP `[selected]` marker. Closing the selected tab clears it. There is no automatic retarget onto another tab.
  186. If the browser reconnects in process, every page id is reissued and the selection is dropped. A command that named a page fails instead of running against a new id. `open` then creates a new tab rather than restoring the previous one. If a selected tab is already gone, the command instead fails with a page-unavailable error and clears that selection.
  187. ### Emulation
  188. | Command | Description |
  189. | --------- | ------------------------------- |
  190. | `emulate` | Emulate device/network/viewport |
  191. ### DevTools Debugging
  192. | Command | Description |
  193. | ------------------ | ------------------------------ |
  194. | `console` | List console messages |
  195. | `console-get <id>` | Get a specific console message |
  196. | `network` | List network requests |
  197. | `network-get [id]` | Get a specific network request |
  198. 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.
  199. ### Performance
  200. | Command | Description |
  201. | --------------------------- | ----------------------------- |
  202. | `lighthouse` | Run a Lighthouse audit |
  203. | `perf-start` | Start a performance trace |
  204. | `perf-stop` | Stop the performance trace |
  205. | `perf-insight <set> <name>` | Analyze a performance insight |
  206. | `heap <path>` | Capture a heap snapshot |
  207. ### Bridge
  208. | Command | Description |
  209. | ------------- | ----------------------------- |
  210. | `start` | Start the bridge server |
  211. | `stop` | Stop the bridge server |
  212. | `setup hooks` | Install or repair agent hooks |
  213. ### Maintenance
  214. | Command | Description |
  215. | ---------------- | ------------------------------------------------------ |
  216. | `update` | Upgrade the installed CLI to the latest npm version |
  217. | `update --check` | Report current vs latest version without installing it |
  218. Running with no command shows the CLI home view. By default, it prepends `bin`
  219. and `description` metadata (see [Configuration](#configuration) to customize the
  220. description), then includes the current snapshot when a browser session is active
  221. or the no-session status/help block when one is not.
  222. ### Flags
  223. `--help`, `-v`, `-V`, and `--version` are top-level options. All other flags
  224. are command-specific; the CLI rejects a flag that is not listed by
  225. `chrome-devtools-axi <command> --help`.
  226. | Flag | Description |
  227. | --------------------------- | ------------------------------------------- |
  228. | `--help` | Show usage information |
  229. | `-v`, `-V`, `--version` | Show the installed CLI version |
  230. | `--check` | Check for available updates (update) |
  231. | `--full` | Show complete output without truncation |
  232. | `--no-snapshot` | Omit auto snapshot (newpage/selectpage) |
  233. | `--background` | Open new page in background (newpage) |
  234. | `--context <name>` | Open in a separate context (newpage) |
  235. | `--timeout <ms>` | Navigation timeout (open/newpage) |
  236. | `--uid @<uid>` | Target a specific element (screenshot) |
  237. | `--full-page` | Capture entire scrollable page (screenshot) |
  238. | `--format <fmt>` | Image format: png, jpeg, webp (screenshot) |
  239. | `--viewport <spec>` | Viewport like "390x844x3,mobile" (emulate) |
  240. | `--color-scheme <value>` | dark, light, or auto (emulate) |
  241. | `--network <condition>` | Network throttle: Slow 3G, etc. (emulate) |
  242. | `--cpu <rate>` | CPU throttling rate 1-20 (emulate) |
  243. | `--geolocation <lat>x<lon>` | Set geolocation (emulate) |
  244. | `--user-agent <string>` | Custom user agent (emulate) |
  245. | `--type <type>` | Filter by type (console, network) |
  246. | `--limit <n>` | Max items to return (console, network) |
  247. | `--page <n>` | Pagination (console, network) |
  248. | `--device <device>` | desktop or mobile (lighthouse) |
  249. | `--mode <mode>` | navigation or snapshot (lighthouse) |
  250. | `--output-dir <path>` | Directory for reports (lighthouse) |
  251. | `--no-reload` | Skip page reload (perf-start) |
  252. | `--no-auto-stop` | Disable auto-stop (perf-start) |
  253. | `--file <path>` | Save trace data to file (perf-start/stop) |
  254. | `--response-file <path>` | Save response body (network-get) |
  255. | `--request-file <path>` | Save request body (network-get) |
  256. 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.
  257. Saved-path output uses the resolved absolute path.
  258. A denied or failed write exits non-zero with the tool error instead of printing success.
  259. Snapshots truncate at about 16k characters unless `--full` is set. `eval` output keeps its head and tail when truncated.
  260. Relative file paths for `upload` also resolve against the directory where you invoke the CLI, even if the bridge started in a different directory. Absolute upload paths pass through unchanged.
  261. `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`.
  262. `network --type` accepts `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `prefetch`, `eventsource`, `websocket`, `manifest`, `signedexchange`, `ping`, `cspviolationreport`, `preflight`, `fedcm`, `other`, and `all`.
  263. For both commands, `all` or an omitted `--type` returns every item.
  264. ## Configuration
  265. Set `CHROME_DEVTOOLS_AXI_DESCRIPTION` to replace the home view's description with
  266. text that fits your browser-tool routing rules. Leave it unset to keep the built-in
  267. description, or set it to an empty string to omit the description line while
  268. keeping the session status and help:
  269. ```sh
  270. export CHROME_DEVTOOLS_AXI_DESCRIPTION="Use for public pages and local development."
  271. # Or omit the description:
  272. export CHROME_DEVTOOLS_AXI_DESCRIPTION=""
  273. ```
  274. AXI honors chrome-devtools-mcp’s usage-statistics opt-out by forwarding `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` and `CI` to the MCP server it launches.
  275. The bridge server port defaults to `9224`. Override it with an environment variable:
  276. ```sh
  277. export CHROME_DEVTOOLS_AXI_PORT=9225
  278. ```
  279. To share one long-lived Chrome DevTools MCP service across AXI sessions on the
  280. same host, set `CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` to the service's Streamable
  281. HTTP endpoint. The exact combination with `CHROME_DEVTOOLS_AXI_MCP_PATH` selects
  282. how AXI reaches it:
  283. 1. **Direct (recommended, simplest):** the shared URL is nonblank and
  284. `CHROME_DEVTOOLS_AXI_MCP_PATH` is absent or blank. AXI constructs a
  285. `StreamableHTTPClientTransport` directly, starts no local MCP child, and
  286. validates that the URL is an absolute `http://` or `https://` endpoint. The
  287. shared service must already be running and reachable. This uses exactly one
  288. MCP process for all named AXI bridges; each bridge still gets its own remote
  289. MCP session/context and selected-page state.
  290. ```sh
  291. MCP_BIN=/absolute/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js
  292. node "$MCP_BIN" --http-port=9333 --isolated --headless \
  293. --chrome-arg=--use-mock-keychain --chrome-arg=--password-store=basic &
  294. unset CHROME_DEVTOOLS_AXI_MCP_PATH
  295. export CHROME_DEVTOOLS_AXI_MCP_SERVER_URL=http://127.0.0.1:9333/mcp
  296. CHROME_DEVTOOLS_AXI_SESSION=agent-a chrome-devtools-axi pages
  297. CHROME_DEVTOOLS_AXI_SESSION=agent-b chrome-devtools-axi pages
  298. ```
  299. 2. **Stdio proxy:** the shared URL and `CHROME_DEVTOOLS_AXI_MCP_PATH` are both
  300. nonblank. AXI checks that executable's `--help` advertises `--serverUrl`,
  301. then starts it with only `--server-url=<URL>`. Use this when the selected
  302. `chrome-devtools-mcp` build provides the verified proxy mode from
  303. [ChromeDevTools/chrome-devtools-mcp#2733](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/2733).
  304. The AXI bridge starts one proxy child per named bridge; manage the shared
  305. service separately.
  306. ```sh
  307. export CHROME_DEVTOOLS_AXI_MCP_PATH=/absolute/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js
  308. node "$CHROME_DEVTOOLS_AXI_MCP_PATH" --http-port=9333 --isolated --headless \
  309. --chrome-arg=--use-mock-keychain --chrome-arg=--password-store=basic &
  310. export CHROME_DEVTOOLS_AXI_MCP_SERVER_URL=http://127.0.0.1:9333/mcp
  311. CHROME_DEVTOOLS_AXI_SESSION=agent-a chrome-devtools-axi pages
  312. CHROME_DEVTOOLS_AXI_SESSION=agent-b chrome-devtools-axi pages
  313. ```
  314. If `CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` is absent or blank, AXI keeps its
  315. standalone stdio behavior: it starts the selected local
  316. `chrome-devtools-mcp` process (in order: `CHROME_DEVTOOLS_AXI_MCP_PATH`, a
  317. `chrome-devtools-mcp` executable on `PATH`, a detected global install, or
  318. `npx -y chrome-devtools-mcp@latest`) and launches/attaches
  319. Chrome according to the local settings below. A nonblank MCP_PATH without a
  320. shared URL also remains this local stdio mode.
  321. `CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` takes precedence over AXI's local Chrome
  322. launch and attach settings. Run the shared service on the same host and
  323. filesystem as AXI, keeping the endpoint loopback-only, so saved artifact paths
  324. refer to the same local files. Generic MCP stdio clients remain supported; the
  325. proxy choice above only changes how AXI's bridge reaches the shared service.
  326. Stop any existing bridges for those session names before switching between
  327. these configurations: a running bridge retains its original transport
  328. settings. `CHROME_DEVTOOLS_AXI_SESSION=<name> chrome-devtools-axi stop` stops
  329. that session's bridge and any AXI-owned proxy child; manage the shared service's
  330. lifecycle separately.
  331. Connect to an existing Chrome instance instead of launching one:
  332. ```sh
  333. export CHROME_DEVTOOLS_AXI_BROWSER_URL=http://127.0.0.1:9222
  334. ```
  335. `CHROME_DEVTOOLS_AXI_BROWSER_URL` accepts both `http://` or `https://` URLs and `ws://` or `wss://` endpoints:
  336. - `http(s)://` uses `--browserUrl` and fetches `/json/version` to discover the WebSocket URL.
  337. - `ws(s)://` uses `--wsEndpoint` directly.
  338. For authenticated `ws://` or `wss://` endpoints, pass JSON headers with `CHROME_DEVTOOLS_AXI_WS_HEADERS`:
  339. ```sh
  340. export CHROME_DEVTOOLS_AXI_BROWSER_URL=wss://cluster.example/launch
  341. export CHROME_DEVTOOLS_AXI_WS_HEADERS='{"Authorization":"Bearer token"}'
  342. ```
  343. Pick which installed Chrome release channel to target with `CHROME_DEVTOOLS_AXI_CHANNEL` - `stable` (the default), `beta`, `canary`, or `dev`:
  344. ```sh
  345. export CHROME_DEVTOOLS_AXI_AUTO_CONNECT=1
  346. export CHROME_DEVTOOLS_AXI_CHANNEL=beta
  347. ```
  348. This selects which Chrome `--autoConnect` attaches to, and which one is launched in the default and `CHROME_DEVTOOLS_AXI_USER_DATA_DIR` modes.
  349. It is ignored when `CHROME_DEVTOOLS_AXI_BROWSER_URL` is set, since that connects to an explicit endpoint regardless of channel.
  350. Launch a specific Chrome binary instead of the installed Chrome with `CHROME_DEVTOOLS_AXI_EXECUTABLE_PATH` (chrome-devtools-mcp's `--executablePath`).
  351. The installer prints the executable path of the downloaded browser; set the variable to that printed path, which depends on your platform and the current stable version:
  352. ```sh
  353. npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer
  354. # macOS arm64 example; use the path the installer printed
  355. export CHROME_DEVTOOLS_AXI_EXECUTABLE_PATH="$HOME/.cache/puppeteer/chrome/mac_arm-155.0.8059.39/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
  356. ```
  357. It applies only when this tool launches the browser (the default `--isolated` mode and `CHROME_DEVTOOLS_AXI_USER_DATA_DIR`) and is ignored in the `CHROME_DEVTOOLS_AXI_AUTO_CONNECT` and `CHROME_DEVTOOLS_AXI_BROWSER_URL` modes, where the browser is already running.
  358. For launched browsers it takes precedence over `CHROME_DEVTOOLS_AXI_CHANNEL`, which is then not passed.
  359. On macOS, prefer a [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) build: a headless copy of the installed Chrome registers with LaunchServices under the installed browser's bundle id, so links clicked in other apps can be delivered to a windowless automation instance instead of the user's browser. Chrome for Testing uses its own bundle id and can never be chosen.
  360. ### Keychain isolation
  361. When 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`.
  362. An automation browser has no business reading, writing, or offering to reset your OS password store, so it is kept off it entirely.
  363. Password autofill and saved-password access are therefore intentionally unavailable inside browsers this tool launches.
  364. On 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.
  365. Your 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.
  366. The 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.
  367. The shared MCP service is also externally launched; its operator owns Chrome's keychain policy, as illustrated by the service launch example above.
  368. Run multiple isolated bridges at once with `CHROME_DEVTOOLS_AXI_SESSION` - one per agent session, worktree, or test worker:
  369. ```sh
  370. CHROME_DEVTOOLS_AXI_SESSION=worker-1 chrome-devtools-axi open https://example.com
  371. CHROME_DEVTOOLS_AXI_SESSION=worker-2 chrome-devtools-axi open https://example.org
  372. ```
  373. 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.
  374. Outside shared-service mode, the default `--isolated` and `CHROME_DEVTOOLS_AXI_USER_DATA_DIR` launch modes each launch a Chrome per bridge, so concurrent sessions share neither browser state nor each other's stale-ref tracking.
  375. 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.
  376. A session name does not choose a connection mode or profile; for a locally launched persistent browser, give each session its own `CHROME_DEVTOOLS_AXI_USER_DATA_DIR`.
  377. The default (unset) session keeps port 9224 and the legacy state paths below.
  378. 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.
  379. Rely on the per-session default ports instead, or set `CHROME_DEVTOOLS_AXI_PORT` only inline per command.
  380. State is stored in `~/.chrome-devtools-axi/` (named sessions nest under `sessions/<name>/`):
  381. | File | Purpose |
  382. | --------------------- | ------------------------------------- |
  383. | `bridge.pid` | PID and port of the running bridge |
  384. | `snapshot-generation` | Counter used to detect stale uid refs |
  385. ### Navigation timeout
  386. chrome-devtools-mcp gives a navigation 10 seconds by default, so a heavy page can fail with `Navigation timeout of 10000 ms exceeded`. Opt into a longer wait with `--timeout <ms>` on `open` or `newpage`, or set a default once:
  387. ```sh
  388. chrome-devtools-axi newpage https://example.com/report --timeout 60000
  389. export CHROME_DEVTOOLS_AXI_NAVIGATION_TIMEOUT_MS=60000
  390. ```
  391. The flag wins over the environment variable. Either must be a positive integer (at most 1000000000); anything else is a usage error. Without either, nothing is sent and the 10-second default applies. The bridge raises its own MCP request deadline above the navigation timeout, so a long navigation is not cut off first.
  392. ### Idle timeout
  393. A bridge runs until `chrome-devtools-axi stop` by default, because it is detached from the shell or agent session that started it.
  394. To have bridges clean up after sessions that never run `stop`, opt into an idle timeout in milliseconds:
  395. ```sh
  396. export CHROME_DEVTOOLS_AXI_IDLE_TIMEOUT_MS=1800000 # 30 minutes
  397. ```
  398. A bridge started with it set shuts itself down, together with the chrome-devtools-mcp process and any browser it launched, once that long passes with no command and no request in flight.
  399. Every command that talks to the browser counts as activity except the home view: bare `chrome-devtools-axi`, which is also the page summary `setup hooks` shows at agent session start, does not renew the timeout, so starting new agent sessions does not keep an abandoned bridge alive.
  400. The next command after a shutdown starts a fresh bridge, so pages and state of a browser this tool launched are lost, as after `stop`.
  401. Unset, blank, or `0` keeps the default; values below `1000` are raised to `1000`, and a value that is not a whole number of milliseconds is ignored.
  402. A running bridge keeps the setting it started with.
  403. ## Development
  404. ```sh
  405. pnpm run build # Compile TypeScript to dist/
  406. pnpm run build:skill # Regenerate the minimal skills/chrome-devtools-axi/SKILL.md stub from src/skill.ts
  407. pnpm run dev # Run CLI directly with tsx
  408. pnpm test # Run tests with vitest
  409. pnpm run test:watch # Run tests in watch mode
  410. ```
  411. The 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()`.
  412. The generated skill and its frontmatter are owned by `src/skill.ts`; update the generator instead of hand-editing the committed `SKILL.md`.
  413. The npm package includes `skills/chrome-devtools-axi/`, so published releases ship the same installable Agent Skill documented in Quick Start.
  414. Prettier intentionally ignores generator-owned files listed in `.prettierignore`; use their generator checks instead of formatting them by hand.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.