ChromeWalk-MCP

# ChromeWalk

**A real, local browser for your AI.** ChromeWalk gives coding and research agents a
private, standalone Chrome-for-Testing instance they drive directly on your own machine —
no cloud relay, no tunnel, never your personal Chrome profile. It fetches WAF-protected
pages, captures full network/screenshot evidence, harvests e-commerce catalogs, runs
performance/accessibility inspection, and drives cross-engine QA (Chromium/WebKit/Firefox),
all exposed to your AI client as standard [MCP](https://modelcontextprotocol.io) tools.

This repository is the **public listing and install package** for ChromeWalk. It does not
contain ChromeWalk's source code, its signing keys, or its server code — those stay in the
private engineering repository. What's here is everything a client (Claude Desktop, Claude
Code, Codex, Cursor, VS Code, Gemini CLI, Windsurf/Cline/Continue, ...) needs to discover and
install the compiled, licensed ChromeWalk build, plus the packaging manifests for each
distribution channel (MCP Registry, Gemini CLI extension, Claude Code plugin, Cursor
directory).

- Website: https://chromewalk.com
- Docs: https://chromewalk.com/docs/
- What is ChromeWalk: https://chromewalk.com/docs/what-is-chromewalk.html
- Privacy: https://chromewalk.com/privacy.html
- Terms: https://chromewalk.com/terms.html
- Support / FAQ: https://chromewalk.com/faq.html
- License terms: [`LICENSE`](./LICENSE) (full EULA also at https://chromewalk.com/LICENSE.txt)

---

## License — a key is required

ChromeWalk is **proprietary software and requires a license**. There is no
anonymous or keyless trial mode in the shipped default build: until a license key is
activated on the machine, every ChromeWalk tool call returns a "license required" error.
(The offline grace window applies only to an already-activated license that temporarily
cannot reach the license server - it is not a keyless trial.)

1. Sign up at **https://chromewalk.com/register.html** with your email - or, from 13.0, just ask your
   AI assistant to sign you up: the `register` tool emails your key, and the `activate` tool activates
   it, both inside the chat and without a license. Your license key is tied to that email address.
2. Install ChromeWalk for your client (below).
3. Activate with either:
   - the `CHROMEWALK_LICENSE` environment variable (read once when the MCP server starts;
     it activates the device if it is not already activated), or
   - `cw activate <key>` from a terminal after install, or
   - pasting the key into the client's own extension/plugin settings UI (Claude Desktop
     `.mcpb` exposes a `license_key` field in `user_config`).

ChromeWalk does **not** collect page content, option values, file paths, or credentials. Its usage
telemetry is required by the license (there is no opt-out); from 12.0 each tool run reports the
target URL (scheme, host and path - credentials, query strings and fragments are removed on your
computer first) and its domain. Your license key itself is never sent in telemetry, only a SHA-256
hash of it (`license_hash`), which links the install to your account. See the
[Privacy Policy](https://chromewalk.com/privacy.html) for exactly what is collected.

---

## What's new in 14.0

**Measure the page, walk it politely, keep your AI's context small.** Still 35 MCP tools; every new feature is an option on a
tool you already have.

- **Content and SEO** - word, sentence and readability counts and image alt text on every audit; `compare --prose` (shingle
  overlap, containment, longest shared passages); `audit --dedupe` (near-duplicate pages, duplicate titles / descriptions / H1s,
  merge the results of several agents); `audit --layers seo` with `--check-links` (robots.txt, sitemap, llms.txt, canonical,
  hreflang, Open Graph, structured data, image SEO, a score and ranked fixes).
- **Smart file names and a navigation log** - captures are named `{seq}_{host}_{path}_{title}_{viewport}` and a
  `nav-log.jsonl` maps every file to its URL, referrer and step (`--name-template`, `--no-smart-names` for the old names).
- **One error collector for every walk** - hidden breaks (API 4xx/5xx, broken images, 404 scripts, CSP, mixed content, long
  tasks) and a WAF verdict in `result.walk`, `--walk-profile scrape|audit|parity`, polite per-host pacing, `--interact` /
  `--keep-alive` and stale-page detection. No humanised or randomised behaviour.
- **Proxy and Nimble** - `--proxy`, and an opt-in `--network nimble` (your own Nimble account) with geo-targeting; the engine
  parity matrix in the docs on chromewalk.com.
- **Lean for your AI** - the tool list is about a tenth of its former size (one line per tool, core arguments, an `advanced`
  object), `help: "brief" | "full"` on every tool, short results with file paths, and an idle-free server.
- **Zero zombies** - a hard-killed run takes its Chromium, Firefox and WebKit browsers with it.
- Behaviour changes (file names, always-on pacing, `--interact` in the audit/parity profiles, new report fields) are listed in
  the release notes.

## What's new in 13.0

**Test the flows, not just the pages.** 35 MCP tools.

- **Sign up and activate from your AI assistant** (`register`, `activate`) - no terminal needed. The
  Claude Desktop extension's license key field is optional.
- **Activate once per computer** - `cw activate <key> --remember` keeps the key in Windows Credential
  Manager and every other install for your user activates itself; `CHROMEWALK_LICENSE_FILE` for CI.
- **Click-flow coverage in smoke** - every scripted step can carry an `expect`, each step is checked for the
  errors and failed requests it caused (a failed step now fails the page), `explore` clicks the safe
  controls you never scripted (never delete / log out / pay / submit), and `coverage` reports what was
  exercised.
- **Logged-in testing on Firefox and WebKit** - `xengine` and `render` take `session`, `auth` and
  `local_storage_file`, and `xengine` runs the suite's steps, checks and Explore on every engine.
- **Microsoft Edge and Brave** - `browser: "edge" | "brave" | "chrome"` (or a path) on smoke, fetch,
  dump, screenshot, compare, design, audit and webinspect, always with ChromeWalk's own private profile.
- **Reliability** - a killed run no longer leaves Chrome behind; large design / audit runs are batched
  and resumable (`resume`); runs report where their time went; `doctor` shows the install folders and
  explains slow starts.
- **More AI tools in one command** - `cw connect` adds GitHub Copilot CLI, Kiro, Amazon Q Developer,
  Kilo Code, Goose and Visual Studio.
- **Skills** for Claude Code, Cursor and Codex in [`skills/`](./skills/) - copy them into your agent's
  skills folder.

---

## What's new in 12.0

- **`audit`** (one-pass UI-uniformity audit bundle) and **`baseline`** (per-page and per-selector visual
  regression with an anti-clobber gate) - 33 MCP tools.
- **Smoke**: slow is not failed, failure artifact bundles, changed-pages-only runs, a base-URL override,
  fewer infrastructure flakes.
- **Pre-capture hooks and browser options** on every capture tool (waits, scripts, attributes, console
  noise filters; language, time zone, throttling, reduced motion, `auth`).
- **Headless by default**, a **self-updating Windows app** (signed, self-tested, automatic rollback), and
  end-to-end recipes in the docs. Full notes: [CHANGELOG.md](./CHANGELOG.md).

---

## What's new in 10.0

**Reliability release.** MCP calls now run concurrently instead of serially, the browser layer
cleans up after itself even when a call is cancelled or hangs, and every tool (CLI and MCP)
shares one error/exit-code contract. Under multi-agent load (same machine, both licensed, 3
reps per scenario):

| Scenario | 9.0 | 10.0 |
|---|---|---|
| 8 pipelined MCP calls | fully serial; p50 24.4s, max 47.4s | up to 6 browsers at once; p50 8.9s, max 15.1s |
| 2 servers x (4 calls + 1 hang) | the hung call blocks every call behind it; up to 3 browser processes left after exit | other calls unaffected; every cancel honoured; 0 browser processes left |
| a forced tool timeout | server wedged, nothing answered within 120s; 10-14 browser processes left | a structured timeout error in 5-10s; 0 browser processes left |
| 12 parallel smoke runs on a saturated CPU | 3 launch failures | 0 launch failures (about 59% slower wall time — launch slots are throttled above 90% CPU) |

- **New `compare` tool** — page-vs-page, directory, or saved-baseline diffs across visual, DOM,
  text, network, structured-data, SEO, links, styles, accessibility, console, headers and
  performance layers, with noise calibration across repeated captures.
- **New diagnostics** — `doctor` (read-only environment health check), `procs` (census of
  ChromeWalk's own browser process trees, with orphan cleanup), `schema` (JSON-LD / microdata /
  RDFa / OpenGraph validation and diff), `cms` (platform fingerprint), and `config` (every
  tuning key, its effective value, and where it came from). The diagnostics work **without** a
  license, so they're how you debug a broken license or install.
- **Tunable configuration** — `chromewalk config show|get|set|unset` covers worker/agent counts,
  launch retries and backoff, connect/command timeouts, the circuit-breaker threshold, profile
  mode, default resource blocking, and more (flag > environment variable > config file > auto).
- **One exit-code contract everywhere:**

  | code | meaning |
  |---|---|
  | 0 | ok |
  | 2 | usage / bad arguments |
  | 3 | checked failure — the tool ran and the target failed a check (a diff, a missing required field, a page that never loaded); still a valid result |
  | 4 | license required |
  | 5 | infrastructure failure — browser launch/connect failed after retries, or a dependency is missing; retry, or run the `doctor` tool |
  | 6 | timed out or cancelled |
  | 1 | unexpected internal error |

- An unreachable page is now reported as a real failure (exit `3`) instead of a false "success"
  against t