` | 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| `reload` | Reload the selected page and snapshot |\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`press` delivers keys to the page via CDP `Input.dispatchKeyEvent`, not as\nbrowser commands. Browser shortcuts such as `Meta+R`, `Ctrl+R`, and `Meta+L`\ndo not trigger browser actions. To refresh the selected page, use\n`chrome-devtools-axi reload` (or `chrome-devtools-axi eval '() => location.reload()'`).\nLike other snapshot-producing commands, `reload` accepts `--full` for an\nuntruncated snapshot.\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\nBy default, `newpage` and `selectpage` print the automatic accessibility tree\nand snapshot-derived suggestions. Use `--no-snapshot` when navigating to a page\nand continuing with `eval` or another chained command without needing element\nUIDs. It suppresses only the printed tree and its derived guidance: capture\nstill runs, preserving page metadata and fresh element-reference generations.\nLeave it off for UID-based `click`/`fill` workflows, or run `snapshot` explicitly.\nThe flag may appear before or after the URL/page ID and takes precedence over\n`--full`.\n\n```sh\nchrome-devtools-axi newpage https://example.com --no-snapshot\nchrome-devtools-axi selectpage 1 --no-snapshot\n```\n\n`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.\n\nPage-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.\n\nIf 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.\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. By default, it prepends `bin`\nand `description` metadata (see [Configuration](#configuration) to customize the\ndescription), then includes the current snapshot when a browser session is active\nor 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| `--no-snapshot` | Omit auto snapshot (newpage/selectpage) |\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.\nA denied or failed write exits non-zero with the tool error instead of printing success.\nSnapshots truncate at about 16k characters unless `--full` is set. `eval` output keeps its head and tail when truncated.\n\nRelative 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.\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\nSet `CHROME_DEVTOOLS_AXI_DESCRIPTION` to replace the home view's description with\ntext that fits your browser-tool routing rules. Leave it unset to keep the built-in\ndescription, or set it to an empty string to omit the description line while\nkeeping the session status and help:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_DESCRIPTION=\"Use for public pages and local development.\"\n# Or omit the description:\nexport CHROME_DEVTOOLS_AXI_DESCRIPTION=\"\"\n```\n\nAXI 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.\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\nTo share one long-lived Chrome DevTools MCP service across AXI sessions on the\nsame host, set `CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` to the service's Streamable\nHTTP endpoint. The exact combination with `CHROME_DEVTOOLS_AXI_MCP_PATH` selects\nhow AXI reaches it:\n\n1. **Direct (recommended, simplest):** the shared URL is nonblank and\n `CHROME_DEVTOOLS_AXI_MCP_PATH` is absent or blank. AXI constructs a\n `StreamableHTTPClientTransport` directly, starts no local MCP child, and\n validates that the URL is an absolute `http://` or `https://` endpoint. The\n shared service must already be running and reachable. This uses exactly one\n MCP process for all named AXI bridges; each bridge still gets its own remote\n MCP session/context and selected-page state.\n\n ```sh\n MCP_BIN=/absolute/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js\n node \"$MCP_BIN\" --http-port=9333 --isolated --headless \\\n --chrome-arg=--use-mock-keychain --chrome-arg=--password-store=basic &\n unset CHROME_DEVTOOLS_AXI_MCP_PATH\n export CHROME_DEVTOOLS_AXI_MCP_SERVER_URL=http://127.0.0.1:9333/mcp\n CHROME_DEVTOOLS_AXI_SESSION=agent-a chrome-devtools-axi pages\n CHROME_DEVTOOLS_AXI_SESSION=agent-b chrome-devtools-axi pages\n ```\n\n2. **Stdio proxy:** the shared URL and `CHROME_DEVTOOLS_AXI_MCP_PATH` are both\n nonblank. AXI checks that executable's `--help` advertises `--serverUrl`,\n then starts it with only `--server-url=`. Use this when the selected\n `chrome-devtools-mcp` build provides the verified proxy mode from\n [ChromeDevTools/chrome-devtools-mcp#2733](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/2733).\n The AXI bridge starts one proxy child per named bridge; manage the shared\n service separately.\n\n ```sh\n export CHROME_DEVTOOLS_AXI_MCP_PATH=/absolute/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js\n node \"$CHROME_DEVTOOLS_AXI_MCP_PATH\" --http-port=9333 --isolated --headless \\\n --chrome-arg=--use-mock-keychain --chrome-arg=--password-store=basic &\n export CHROME_DEVTOOLS_AXI_MCP_SERVER_URL=http://127.0.0.1:9333/mcp\n CHROME_DEVTOOLS_AXI_SESSION=agent-a chrome-devtools-axi pages\n CHROME_DEVTOOLS_AXI_SESSION=agent-b chrome-devtools-axi pages\n ```\n\nIf `CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` is absent or blank, AXI keeps its\nstandalone stdio behavior: it starts the selected local\n`chrome-devtools-mcp` process (in order: `CHROME_DEVTOOLS_AXI_MCP_PATH`, a\n`chrome-devtools-mcp` executable on `PATH`, a detected global install, or\n`npx -y chrome-devtools-mcp@latest`) and launches/attaches\nChrome according to the local settings below. A nonblank MCP_PATH without a\nshared URL also remains this local stdio mode.\n\n`CHROME_DEVTOOLS_AXI_MCP_SERVER_URL` takes precedence over AXI's local Chrome\nlaunch and attach settings. Run the shared service on the same host and\nfilesystem as AXI, keeping the endpoint loopback-only, so saved artifact paths\nrefer to the same local files. Generic MCP stdio clients remain supported; the\nproxy choice above only changes how AXI's bridge reaches the shared service.\n\nStop any existing bridges for those session names before switching between\nthese configurations: a running bridge retains its original transport\nsettings. `CHROME_DEVTOOLS_AXI_SESSION= chrome-devtools-axi stop` stops\nthat session's bridge and any AXI-owned proxy child; manage the shared service's\nlifecycle separately.\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\nLaunch a specific Chrome binary instead of the installed Chrome with `CHROME_DEVTOOLS_AXI_EXECUTABLE_PATH` (chrome-devtools-mcp's `--executablePath`).\nThe 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:\n\n```sh\nnpx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer\n# macOS arm64 example; use the path the installer printed\nexport 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\"\n```\n\nIt 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.\nFor launched browsers it takes precedence over `CHROME_DEVTOOLS_AXI_CHANNEL`, which is then not passed.\nOn 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.\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.\nThe shared MCP service is also externally launched; its operator owns Chrome's keychain policy, as illustrated by the service launch example above.\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.\nOutside 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.\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 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`.\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### Idle timeout\n\nA bridge runs until `chrome-devtools-axi stop` by default, because it is detached from the shell or agent session that started it.\nTo have bridges clean up after sessions that never run `stop`, opt into an idle timeout in milliseconds:\n\n```sh\nexport CHROME_DEVTOOLS_AXI_IDLE_TIMEOUT_MS=1800000 # 30 minutes\n```\n\nA 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.\nEvery 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.\nThe next command after a shutdown starts a fresh bridge, so pages and state of a browser this tool launched are lost, as after `stop`.\nUnset, 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.\nA running bridge keeps the setting it started with.\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","readmeFilename":"README.md"}![\"npm\"](\"https://img.shields.io/npm/v/chrome-devtools-axi?style=flat-square\")
\n ![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/ci.yml?style=flat-square&label=CI\")
\n ![\"Release\"](\"https://img.shields.io/github/actions/workflow/status/kunchenguid/chrome-devtools-axi/release-please.yml?style=flat-square&label=Release\")
\n ![\"Platform\"](\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square\"){kind=icon}
\n ![\"X\"](\"https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square\"){kind=icon}
\n ![\"Discord\"](\"https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord\")
\n