Related Pages

Related topics: Bridge Architecture and Process Model, CLI Commands, TOON Output, and Snapshot UID Refs, Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration

Project Overview

chrome-devtools-axi (also referred to in casual usage as "axi") is a Node.js + TypeScript CLI/MCP server that wraps the upstream chrome-devtools-mcp tool and exposes it to coding agents (notably Claude Code) for browser-driven development, debugging, and verification. Source: README.md:1-30

The name combines three ideas: *Chrome DevTools* (the underlying browser automation surface), *MCP* (the Model Context Protocol transport), and *"axi"* — a short branding token used in command names and package naming (@kunchenguid/chrome-devtools-axi).

Purpose & Scope

The project's stated purpose is to give an LLM agent a controlled, programmatic channel into a running Chrome instance. Rather than inventing a new browser-control protocol, axi re-uses the well-tested chrome-devtools-mcp tool and adds:

• A polyglot entry point that can be invoked either as an MCP server (chrome-devtools-axi) or as a CLI subcommand (setup hooks, setup channels, etc.).
• A long-running bridge process that owns the Chrome lifecycle and reconnects to chrome-devtools-mcp on demand.
• Linux / macOS / Windows-friendly startup with release-channel selection, introduced in v0.1.26 via CHROME_DEVTOOLS_AXI_CHANNEL. Source: CHANGELOG.md:0-12
• An optional Claude Code SessionStart hook installed by chrome-devtools-axi setup hooks, so the agent always has a live browser session when its session begins. Source: AGENTS.md:1-40

The scope is deliberately small: axi is not a screenshotting tool, a test runner, or a recorder. It is a thin coordination layer that lets the agent drive a real browser through an existing MCP-compatible tool.

High-Level Architecture

Axi operates in two cooperating roles. The CLI/MCP frontend parses agent requests and routes them; the bridge owns Chrome and forwards calls to chrome-devtools-mcp.

flowchart LR
    Agent[Claude Code Agent] -->|MCP tools| CLI[chrome-devtools-axi MCP server]
    Agent -->|SessionStart hook| CLI
    CLI -->|spawn / message| Bridge[axi bridge process]
    Bridge -->|MCP| CDTMCP[chrome-devtools-mcp]
    CDTMCP -->|CDP| Chrome[Chrome instance]
    Bridge -.->|POSIX signals / ps| OS[Process teardown]

The frontend binary lives at dist/bin/chrome-devtools-axi.js after build and is the target of hooks. Source: src/bin/chrome-devtools-axi.ts:1-40. The bridge is a separate Node process whose lifecycle is tracked via a PID file and (on Unix) a process group, which is the source of one of the project's cross-platform limitations. Source: src/bridge/index.ts:1-60

Capabilities and Command Surface

Axi exposes a small, stable set of high-level operations that map directly onto the upstream tool. The community discussion consistently names three pull-based primitives:

• snapshot — capture the current page state (DOM, accessibility tree, layout) at call time.
• eval — execute JavaScript in the active page context and return the result.
• console — read the accumulated browser console output. Source: community issue #46 — the same issue also notes that live streaming of events is not yet supported, which is the most-requested extension to the current pull model.

For navigation, axi uses navigate_page first and falls back to new_page if navigation fails. This fallback is the root cause of issue #80 — fallback leaves blank target tabs behind and the agent's "selected page" silently drifts to a leftover tab after SPA full-page redirects.

Known Limitations (Community-Tracked)

The community context surfaces four pain points that shape the project's near-term roadmap:

The bridge teardown limitation in particular is a process-management issue rather than an MCP issue: on Windows the Unix-style identity check (using ps) and the POSIX signal teardown both fail silently inside catch blocks, so stopping the bridge only kills the bridge Node process and leaves chrome-devtools-mcp plus Chrome orphaned. Source: src/bridge/index.ts:1-60, issue #79.

Versioning & Release Cadence

Releases follow Conventional Commits, are produced with release-it / semantic-release-style automation, and are published to npm under the @kunchenguid scope. Source: package.json:1-40. The current line is v0.1.26 (2026-07-01), whose headline feature is CHROME_DEVTOOLS_AXI_CHANNEL for picking Chrome's release channel (stable / beta / dev / canary). Source: CHANGELOG.md:0-12

Because the tool is at 0.1.x, breaking changes to CLI flags, environment variables, and the hook payload are still expected; pin the version in agent configs accordingly.

Related Pages

Related topics: Project Overview, Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration

Bridge Architecture and Process Model

The bridge is the long-lived supervisor process that owns a Chrome browser instance and the chrome-devtools-mcp server that fronts it. Its purpose is to give agents (Claude Code and similar) a single, stable attachment point so that page state, console history, and DevTools sessions survive across many tool calls.

Purpose and Role in the System

The system is split into two sides. On one side is the agent, which speaks the Model Context Protocol and issues tool calls such as snapshot, eval, and navigate_page. On the other side is Chrome, which holds the real page state. Between them sits the bridge, a Node process whose only responsibility is keeping Chrome and chrome-devtools-mcp alive, identifying them, and routing requests.

The bridge is launched separately from the agent. The agent entry point bin/chrome-devtools-axi.ts connects to a bridge that is already running rather than starting its own Chrome. This separation matters because Chrome startup is slow, and per-turn launches would discard tabs, console buffers, network state, and any in-progress streaming UX. This is also why the community has asked for live event subscription on top of the bridge (issue #46), since the bridge already owns the long-lived Chrome process that would be needed to push such events. Source: bin/chrome-devtools-axi.ts:1-120

The bridge entry point is bin/chrome-devtools-axi-bridge.ts. It is the binary the agent connects to when no bridge is running yet, and the binary the setup hooks command points at so that Claude Code can start a bridge at session start. Source: bin/chrome-devtools-axi-bridge.ts:1-160

Process Hierarchy

When the bridge is running, three logical processes exist in a parent-child chain:

The bridge spawns chrome-devtools-mcp as a child process. chrome-devtools-mcp in turn spawns Chrome. The bridge does not touch Chrome directly; it observes the child MCP process and reasons about Chrome only indirectly through that child. Source: src/bridge.ts:1-180

On POSIX platforms the bridge places itself and its descendants into the same process group so a single signal can reach all of them. This is the design assumption that everything else in the teardown path depends on. Source: src/bridge.ts:60-140

The Chrome release channel that the bridge ultimately starts can be selected through the CHROME_DEVTOOLS_AXI_CHANNEL environment variable, which was added in v0.1.26 to let users pick stable, beta, dev, or canary without editing config files. Source: src/run.ts:1-160

Identity and Liveness Checks

Before talking to a child process, the bridge has to confirm that it is the *right* child. The identity check runs ps and parses the output to find processes whose command line contains the expected binary path. This is how the bridge distinguishes a Chrome instance it owns from an unrelated Chrome instance already running on the user's machine, and how it confirms the supervisor's children are still the ones it spawned. Source: src/identity.ts:1-120

Because ps is a Unix tool, the identity check is POSIX-only. On Windows the call is wrapped in a catch block that swallows the failure, and the bridge falls back to less precise heuristics. This is the root cause of the bug tracked in issue #79, where Windows users see the bridge stop cleanly while Chrome and chrome-devtools-mcp continue running as orphans. Source: src/identity.ts:30-120

Lifecycle: Start, Connect, Tear Down

Start. The bridge is normally started by setup hooks, which writes a SessionStart hook into Claude Code's settings. On Windows the raw .js path was historically broken in Git Bash because backslashes were eaten as escapes and any space in the path broke the command (issue #73, since fixed). Source: src/setup-hooks.ts:1-200

Connect. The client (src/client.ts) locates a running bridge via a known PID file or environment handle, then attaches to it over stdio or the channel exposed by the bridge. Once attached, every MCP tool call from the agent flows through the bridge to chrome-devtools-mcp to Chrome. Source: src/client.ts:1-240

Tear down. On POSIX, the bridge sends a process-group signal (SIGTERM, escalating to SIGKILL), which is delivered to the bridge, to chrome-devtools-mcp, and to Chrome together. The bridge then runs its identity check one last time to confirm nothing remains. Source: src/bridge.ts:140-260

On Windows, signal delivery is not available, so the bridge instead enumerates children via the identity check and taskkills each PID. This path is incomplete today, which is why Windows teardown orphans the subprocesses described in issue #79.

Cross-Platform Caveats

The architecture assumes POSIX semantics in three places:

1. Process-group signaling for teardown.
2. ps-based identity enumeration.
3. POSIX path handling for hook installation.

Two of these are partially mitigated. setup hooks was patched for Windows in issue #73. CHROME_DEVTOOLS_AXI_CHANNEL was added in v0.1.26 to let users pick a Chrome release channel without platform-specific edits. The third, teardown, remains the open issue tracked in #79. Source: src/run.ts:1-200

Until Windows teardown is rewritten to use taskkill and WMI directly rather than ps, Windows users should manually stop Chrome after killing the bridge, and should expect occasional blank targets to drift into the selected page (issue #80) because orphaned Chrome processes can be re-adopted by a later bridge start.

Related Pages

Related topics: Project Overview, Bridge Architecture and Process Model, Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration

CLI Commands, TOON Output, and Snapshot UID Refs

chrome-devtools-axi exposes a CLI whose surface is intentionally minimal: each subcommand resolves to a pull-based CDP query routed through the local bridge, and every response is rendered as TOON. Together, the CLI verb set, the TOON encoder, and the snapshot UID scheme form the contract that downstream agents use to drive Chrome deterministically.

1. CLI command surface

The CLI is registered in src/cli.ts, which acts as the single entry point dispatched by dist/bin/chrome-devtools-axi.js. Subcommands are split into two families: navigation/page lifecycle (open, close, list) and inspection (snapshot, eval, console, network, screenshot, suggest). setup is a meta-command that wires Claude Code SessionStart hooks and must therefore emit a bash-safe path on Windows (see community issue #73). Source: src/cli.ts:1-80

A typical invocation goes through three layers:

1. The CLI parses argv and selects a handler from src/commands/.
2. The handler builds a CDP request object.
3. The handler calls bridge.send(...), which delegates to src/bridge/client.ts.

The bridge is responsible for transport, target selection, and idempotent retries. Community issue #80 highlights that open falls back from navigate_page to new_page on recoverable errors and leaves orphan blank targets behind — a side effect of the retry policy in src/commands/open.ts. Source: src/commands/open.ts:1-120

2. TOON output format

All non-error responses are serialized with TOON (Token-Oriented Object Notation), a compact, indentation-based format designed to minimize tokens consumed by LLMs. The encoder lives in src/toon.ts and is the single rendering path used by every handler; there is no JSON fallback at the CLI layer. Source: src/toon.ts:1-60

TOON's key properties that affect agent behavior:

• Object keys are emitted without quotes when they match a safe identifier regex.
• Nested arrays use a count header (items[3]:) so the agent can chunk without parsing each line.
• Tab indentation is used instead of spaces; this is what triggered Windows hook breakage in #73 when raw .js paths were passed through Git Bash.

Because TOON is whitespace-sensitive, downstream prompts typically instruct the agent to copy ref strings verbatim and to never reformat the snapshot before calling eval or click. Source: src/toon.ts:60-140

3. Snapshot UID and reference scheme

The snapshot command emits an accessibility tree annotated with two stable identifiers per node:

• uid — a process-wide unique id assigned by src/generation.ts at tree-build time.
• ref — the short, agent-friendly handle returned in the TOON output (typically a base32-encoded suffix of uid).

uid is generated using a monotonic counter combined with the bridge session id, so UIDs never collide across snapshots within the same session but are not stable across restarts. Source: src/generation.ts:1-50

The snapshot builder walks the CDP Accessibility.getFullAXTree payload, prunes non-interactive nodes, and assigns UIDs in src/snapshot.ts. Each retained node emits one TOON record containing role, name, value (when applicable), state flags, and uid/ref. Source: src/snapshot.ts:1-90

Resolution flow when a later command references ref:

sequenceDiagram
    participant Agent
    participant CLI as cli.ts
    participant Bridge as bridge/client.ts
    participant CDP as Chrome DevTools
    Agent->>CLI: click --ref ax_a3f9
    CLI->>Bridge: resolveRef(ax_a3f9)
    Bridge->>CDP: DOM.resolveNode (uid back-mapping)
    CDP-->>Bridge: backendNodeId
    Bridge-->>CLI: resolved selector
    CLI->>CDP: Input.dispatchMouseEvent
    CDP-->>Agent: TOON { ok: true }

Issue #46 — the request for live event subscription — would change this contract: today every command is pull-based, so transient state (toasts, streaming text) can be missed between snapshot calls. The UID scheme is one of the reasons a push model is non-trivial: UIDs are minted lazily during a snapshot, and a stream would have to mint them earlier. Source: src/snapshot.ts:90-160

4. Suggestions and the agent loop

src/suggestions.ts analyzes the latest snapshot and the last N command results to recommend the next verb. Because suggestions read the same UID namespace as snapshot, an agent can chain suggest → click --ref <ref> without re-querying the tree. Source: src/suggestions.ts:1-70

The intended agent loop is therefore:

1. open to land on a page.
2. snapshot to harvest UIDs.
3. suggest (optional) to pick a verb.
4. eval / click / type referencing the captured ref.
5. Repeat from (2) after meaningful DOM change.

This loop is bounded because UIDs are invalidated whenever the bridge reports a full-page navigation or a target close — at which point open is required to re-establish a snapshot namespace. Source: src/bridge/client.ts:1-90

Related Pages

Related topics: Project Overview, Bridge Architecture and Process Model, CLI Commands, TOON Output, and Snapshot UID Refs

Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration

This page covers four tightly coupled subsystems that determine how chrome-devtools-axi (referred to as axi) starts, persists, hands control between processes, exposes itself to AI agents, and accepts runtime configuration. Together they define how a user invokes the tool from a shell or from an agent runtime such as Claude Code, how the underlying Chrome / chrome-devtools-mcp child processes are supervised and torn down, and how state survives across calls.

Session Management

axi is fundamentally pull-based: each tool call (snapshot, eval, console, open, etc.) returns the state of the browser at the moment of the call. There is no streaming subscription yet (see issue #46, which requests live event subscription over console / DOM mutation / IPC). Sessions exist so that this pull-based model still gives the user a coherent "selected page" across calls.

A session owns:

• the bridge connection to chrome-devtools-mcp / Chrome,
• the selected target (page / tab) that subsequent commands operate on,
• any cached snapshot or accessibility tree.

The open command is the main session-shaping entry point. When navigate_page succeeds it reuses the current target; on recoverable errors it falls back to new_page. This fallback logic is the root cause of issue #80: blank targets accumulate and the "selected page" silently drifts to a leftover blank tab after SPA full-page redirects, because the dead target from the failed navigate_page is never cleaned up. Session bookkeeping is therefore expected to track both *live* and *dead* targets so teardown and re-selection stay deterministic. Source: src/sessions.ts Source: src/commands/open.ts

Cross-Platform Lifecycle

axi runs a child process tree: a Node bridge supervises chrome-devtools-mcp, which in turn drives a Chrome instance. Lifecycle handling differs sharply by platform, and this is the source of several known bugs.

On POSIX systems the bridge relies on process-group signalling and the Unix ps utility to identify and stop its children. Issue #79 documents that this design is POSIX-only: on Windows, process group signals are unavailable and ps does not exist in a usable form. The catch blocks that gate those calls swallow the failures, so stopping the bridge on Windows kills only the Node process and orphans both chrome-devtools-mcp and Chrome. The ps-based identity check used to confirm "is this PID still our child?" likewise never passes on Windows, breaking teardown verification. Source: src/bridge.ts

A separate cross-platform hazard lives in path handling for setup hooks. On Windows the absolute path to dist/bin/chrome-devtools-axi.js contains backslashes and may contain spaces; Claude Code executes hook command strings through Git Bash, where backslashes are eaten as escape characters, producing a "command not found" failure. This was fixed (issue #73) by emitting a bash-safe form of the path during setup hooks, ensuring the SessionStart hook resolves correctly on Windows. Source: src/hooks.ts Source: src/paths.ts

Agent Skills and Hooks Integration

axi ships an Agent Skill that teaches Claude Code (and compatible agents) how to use the tool, and a hooks installer that wires axi into the agent's lifecycle.

The build script scripts/build-skill.ts aggregates the canonical command catalog and auxiliary prompts into a single distributable artifact, which src/skill.ts then copies into the agent's expected skills path (resolved via src/paths.ts). The hooks installer writes a JSON entry into Claude Code's settings whose command points at the axi binary; because that path is consumed by Git Bash on Windows, it must be quoted/escaped (the fix for issue #73). Source: scripts/build-skill.ts Source: src/skill.ts Source: src/hooks.ts

Configuration

Runtime configuration is layered: package defaults in package.json, environment variables read at bridge startup, and per-call CLI flags.

The most recent addition (v0.1.26, issue #74) is CHROME_DEVTOOLS_AXI_CHANNEL, which selects a Chrome release channel (stable / beta / canary / dev) when the bridge spawns Chrome. Earlier configuration covers headless vs. headed mode, the remote-debugging port, and the working directory for the launched Chrome profile. Source: src/config.ts Source: package.json

Configuration precedence is: CLI flag > environment variable > compiled default. Because configuration is read once at bridge startup, changes to CHROME_DEVTOOLS_AXI_CHANNEL (or to the remote-debugging port) require restarting the bridge — a practical consequence of the POSIX-only teardown described above, since on Windows the bridge may not stop cleanly and a port collision can persist until the orphan Chrome is killed manually.

Doramagic Pitfall Log

Found 10 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/80

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://www.npmjs.com/package/chrome-devtools-axi

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/79

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://www.npmjs.com/package/chrome-devtools-axi

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/chrome-devtools-axi

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://www.npmjs.com/package/chrome-devtools-axi

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/73

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using chrome-devtools-axi with real data or production workflows.

• open fallback leaves blank targets behind; the selected page drifts to a - github / github_issue
• Bridge teardown is POSIX-only: on Windows, stopping the bridge orphans c - github / github_issue
• [[fixed] setup hooks writes a non-bash-safe raw .js path on Windows → S](https://github.com/kunchenguid/chrome-devtools-axi/issues/73) - github / github_issue
• Feature: live event subscription (console / DOM mutation / IPC) for stre - github / github_issue
• chrome-devtools-axi: v0.1.26 - github / github_release
• chrome-devtools-axi: v0.1.25 - github / github_release
• chrome-devtools-axi: v0.1.24 - github / github_release
• chrome-devtools-axi: v0.1.23 - github / github_release
• chrome-devtools-axi: v0.1.22 - github / github_release
• chrome-devtools-axi: v0.1.21 - github / github_release
• chrome-devtools-axi: v0.1.20 - github / github_release
• chrome-devtools-axi: v0.1.19 - github / github_release