# https://github.com/kunchenguid/chrome-devtools-axi Project Manual

Generated at: 2026-07-07 05:07:50 UTC

## Table of Contents

- [Project Overview](#page-1)
- [Bridge Architecture and Process Model](#page-2)
- [CLI Commands, TOON Output, and Snapshot UID Refs](#page-3)
- [Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration](#page-4)

<a id='page-1'></a>

## Project Overview

### Related Pages

Related topics: [Bridge Architecture and Process Model](#page-2), [CLI Commands, TOON Output, and Snapshot UID Refs](#page-3), [Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/README.md)
- [package.json](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/package.json)
- [AGENTS.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/AGENTS.md)
- [CHANGELOG.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/CHANGELOG.md)
- [src/bin/chrome-devtools-axi.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bin/chrome-devtools-axi.ts)
- [src/bridge/index.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge/index.ts)
</details>

# 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`](https://github.com/ChromeDevTools/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`](https://github.com/ChromeDevTools/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`.

```mermaid
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](https://github.com/kunchenguid/chrome-devtools-axi/issues/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](https://github.com/kunchenguid/chrome-devtools-axi/issues/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:

| # | Issue | Root-cause layer | Status |
|---|-------|------------------|--------|
| [#46](https://github.com/kunchenguid/chrome-devtools-axi/issues/46) | No live event subscription | MCP frontend | Open |
| [#80](https://github.com/kunchenguid/chrome-devtools-axi/issues/80) | `open` fallback leaks blank targets | CLI navigation | Open |
| [#79](https://github.com/kunchenguid/chrome-devtools-axi/issues/79) | Bridge teardown is POSIX-only (`ps`, process-group signals) | `src/bridge` | Open |
| [#73](https://github.com/kunchenguid/chrome-devtools-axi/issues/73) | Windows hook uses a raw `.js` path that Git Bash mangles | `setup hooks` | Fixed |

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](https://github.com/kunchenguid/chrome-devtools-axi/issues/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.

---

<a id='page-2'></a>

## Bridge Architecture and Process Model

### Related Pages

Related topics: [Project Overview](#page-1), [Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge.ts)
- [src/client.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/client.ts)
- [src/run.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/run.ts)
- [src/identity.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/identity.ts)
- [src/setup-hooks.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/setup-hooks.ts)
- [bin/chrome-devtools-axi.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/bin/chrome-devtools-axi.ts)
- [bin/chrome-devtools-axi-bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/bin/chrome-devtools-axi-bridge.ts)
</details>

# 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:

| Layer | Process | Role |
|---|---|---|
| Supervisor | `chrome-devtools-axi-bridge` (Node) | Owns lifecycle, identity checks, teardown |
| Middleware | `chrome-devtools-mcp` (Node) | Speaks CDP to Chrome, exposes MCP tools |
| Browser | Chrome (Chromium) | Renders pages, runs JS, emits DevTools events |

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 `taskkill`s 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.

---

<a id='page-3'></a>

## CLI Commands, TOON Output, and Snapshot UID Refs

### Related Pages

Related topics: [Project Overview](#page-1), [Bridge Architecture and Process Model](#page-2), [Sessions, Cross-Platform Lifecycle, Agent Skills, and Configuration](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/cli.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/cli.ts)
- [src/snapshot.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/snapshot.ts)
- [src/toon.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/toon.ts)
- [src/generation.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/generation.ts)
- [src/suggestions.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/suggestions.ts)
- [src/commands/open.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/commands/open.ts)
- [src/bridge/client.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge/client.ts)
</details>

# 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]()`

| Command | Purpose | Returns |
|---|---|---|
| `open <url>` | Navigate or open a new target | `{ targetId, url }` |
| `snapshot [options]` | Accessibility tree slice | `{ uid, ref, ... }` tree |
| `eval <expr>` | Run JS in page context | `{ result, type }` |
| `console [filter]` | Drain console buffer | `{ level, text, source }[]` |
| `suggest` | Recommend next actions | suggested verbs |

## 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`:

```mermaid
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]()`

---

<a id='page-4'></a>

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

### Related Pages

Related topics: [Project Overview](#page-1), [Bridge Architecture and Process Model](#page-2), [CLI Commands, TOON Output, and Snapshot UID Refs](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/sessions.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/sessions.ts)
- [src/paths.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/paths.ts)
- [src/hooks.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/hooks.ts)
- [src/skill.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/skill.ts)
- [src/bridge.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/bridge.ts)
- [src/config.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/config.ts)
- [src/commands/open.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/src/commands/open.ts)
- [skills/chrome-devtools-axi/SKILL.md](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/skills/chrome-devtools-axi/SKILL.md)
- [scripts/build-skill.ts](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/scripts/build-skill.ts)
- [package.json](https://github.com/kunchenguid/chrome-devtools-axi/blob/main/package.json)

</details>

# 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.

| Surface | Purpose | Entry point |
|---|---|---|
| `SKILL.md` | Tool description, command catalog, usage heuristics | `skills/chrome-devtools-axi/SKILL.md` |
| `setup skill` | Installs the skill into the agent's skills directory | `src/skill.ts` |
| `setup hooks` | Writes a Claude Code `SessionStart` hook | `src/hooks.ts` |
| `build-skill.ts` | Bundles skill assets for distribution | `scripts/build-skill.ts` |

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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: kunchenguid/chrome-devtools-axi

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/80

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://www.npmjs.com/package/chrome-devtools-axi

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/79

## 4. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://www.npmjs.com/package/chrome-devtools-axi

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/kunchenguid/chrome-devtools-axi/issues/73

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/chrome-devtools-axi

<!-- canonical_name: kunchenguid/chrome-devtools-axi; human_manual_source: deepwiki_human_wiki -->