# chromex-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/whallysson/chromex  
**GitHub Stars:** 4  
**npm Downloads (last month):** 80  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/chromex-mcp

## Description
Agent-first Chrome DevTools toolkit with a token-efficient CLI, 85 typed MCP tools, modal-free pipe transport, diagnostics, memory analysis, extensions, and WebMCP.

## Tools
Capabilities this server exposes over MCP:

- **chromex_list** — List open browser pages with unique target ID prefixes. Run this first to get target IDs.
- **chromex_launch** — Launch browser with remote debugging enabled. Supports headless, proxy, insecure certs, and custom Chrome flags.
- **chromex_doctor** — Diagnose local Chromex browser/CDP connectivity, config paths, DevToolsActivePort discovery, and visible pages.
- **chromex_open** — Open a new browser tab.
- **chromex_close** — Close a browser tab.
- **chromex_focus** — Activate/focus a browser tab.
- **chromex_incognito** — Create isolated incognito context with separate cookies/storage. No browser relaunch needed.
- **chromex_stop** — Stop per-tab daemon(s). Without target, stops all.
- **chromex_sessions** — List named Chromex sessions managed by the CLI.
- **chromex_show** — Create a local dashboard artifact for named Chromex sessions. Annotation mode also writes an annotation pack.
- **chromex_snapshot** — Accessibility tree snapshot. Returns incremental diff after first call (only changed nodes). Use refs=true to get @eN references for click/fill/hover. Use query to filter to matching nodes + ancestors (preserves hierarchy, slashes page output for large sites). Hints (help[]) are only emitted when refs=true because they rely on a fresh refMap.
- **chromex_html** — Get page HTML, optionally filtered by CSS selector.
- **chromex_screenshot** — Take screenshot. Supports PNG/JPEG/WebP, full page, and element capture by @eN ref. Returns inline image + file path.
- **chromex_network** — Network requests. Without requestId: list captured requests (status, method, URL). With requestId: full detail (headers, timing, response body).
- **chromex_perf** — Core Web Vitals including INP, long tasks, long animation frames, layout shifts, navigation timing, CPU profiles, and heap allocation sampling.
- **chromex_console** — Console messages. Default: live capture for duration. "list": stored messages since daemon start. "detail": full message with stack trace.
- **chromex_domsnapshot** — Structured DOM snapshot with bounding rects and optional computed styles.
- **chromex_highlight** — Highlight DOM element with visual overlay, or clear highlight.
- **chromex_locator** — Generate a stable locator for an element ref or CSS selector.
- **chromex_evidence** — Create an evidence pack with screenshots, snapshots, HTML, console, network timeline, and local replay HTML.
- **chromex_issues** — Collect and inspect Chromium Audits issues including CORS, CSP, cookies, deprecations, mixed content, accessibility, and form issues.
- **chromex_inspect** — Inspect computed CSS, matched rules, event listeners, and box model for an element.
- **chromex_diagnose** — Produce a prioritized runtime diagnosis from browser issues, failed requests, exceptions, console warnings, and performance counters.
- **chromex_eval** — Evaluate JavaScript expression in page context. Returns serialized result.
- **chromex_evalraw** — Execute raw CDP command. Some methods blocked by security config.
- **chromex_navigate** — Navigate to URL, back, forward, or reload. Returns snapshot with refs of the resulting page.
- **chromex_waitfor** — Wait for CSS selector to appear in DOM.
- **chromex_wait** — Wait for lifecycle event.
- **chromex_scroll** — Scroll page. Direction "to" accepts CSS selector as amount.
- **chromex_click** — Click element by CSS selector or @eN ref. Supports double-click. Returns auto-snapshot with updated refs.
- **chromex_clickxy** — Click at CSS pixel coordinates. Supports double-click. Returns auto-snapshot with updated refs.
- **chromex_type** — Type text at currently focused element. Returns auto-snapshot with updated refs.
- **chromex_hover** — Hover over element by @eN ref. Requires chromex_snapshot with refs=true first.
- **chromex_drag** — Drag and drop between selectors or coordinate pairs (x1,y1 x2,y2). Returns auto-snapshot with updated refs.
- **chromex_touch** — Touch gesture: tap, swipe, pinch, longpress. Returns auto-snapshot with updated refs.
- **chromex_dialog** — Handle JS dialogs (alert/confirm/prompt). Use "auto" to auto-accept all. Returns auto-snapshot with updated refs.
- **chromex_press_key** — Press key or key combination. For form submission (Enter), closing modals (Escape), keyboard shortcuts (Control+A), tab navigation (Tab). Returns auto-snapshot with updated refs.
- **chromex_loadall** — Click "load more" button repeatedly until it disappears. Returns auto-snapshot with updated refs.
- **chromex_fill** — Fill input/textarea. Handles React/Vue/Angular controlled inputs. Accepts @eN ref. Returns auto-snapshot with updated refs.
- **chromex_clear** — Clear input field. Returns auto-snapshot with updated refs.
- **chromex_select** — Select option in dropdown. Returns auto-snapshot with updated refs.
- **chromex_check** — Toggle checkbox or radio button. Returns auto-snapshot with updated refs.
- **chromex_form** — Batch fill form. JSON maps selectors to values. Booleans toggle checkboxes. Returns auto-snapshot with updated refs.
- **chromex_upload** — Upload file(s) to input[type=file]. Returns auto-snapshot with updated refs.
- **chromex_cookies** — Manage cookies: list (default), set (JSON), or clear.
- **chromex_storage** — Read localStorage, sessionStorage, or clear both.
- **chromex_state** — Save or load portable storage state for cookies and localStorage.
- **chromex_storage_usage** — Show origin storage usage, quota, and per-storage-type breakdown.
- **chromex_storage_clear_site_data** — Clear all site data for the current origin through CDP Storage.clearDataForOrigin.
- **chromex_app_summary** — Summarize Application panel state for the current origin: quota, local/session storage, cookies, Cache Storage entries, IndexedDB, Service Workers, storage buckets, and manifest.
- **chromex_service_workers** — List Service Worker registrations and versions observed for the current browser session.
- **chromex_service_worker_update** — Request an update check for a Service Worker registration scopeURL.
- **chromex_service_worker_skip_waiting** — Ask a waiting Service Worker for scopeURL to activate via skipWaiting.
- **chromex_service_worker_unregister** — Unregister a Service Worker registration by scopeURL.
- **chromex_cache_list** — List Cache Storage caches for the current origin with cache IDs and names.
- **chromex_cache_entries** — List entries for a Cache Storage cache. cacheId may be a unique prefix from chromex_cache_list.
- **chromex_cache_body** — Read the decoded body preview for one Cache Storage request URL.
- **chromex_cache_delete_entry** — Delete one Cache Storage entry by cacheId and requestURL.
- **chromex_cache_delete** — Delete an entire Cache Storage cache by cacheId.
- **chromex_indexeddb_list** — List IndexedDB database names for the current origin.
- **chromex_indexeddb_schema** — Show object stores, key paths, auto-increment flags, and indexes for an IndexedDB database.
- **chromex_indexeddb_rows** — Read a compact preview of rows from an IndexedDB object store.
- **chromex_indexeddb_clear_store** — Clear all rows from one IndexedDB object store.
- **chromex_pdf** — Export page as PDF.
- **chromex_throttle** — Throttle network: 3g, slow-3g, 4g, offline, custom, reset.
- **chromex_intercept** — Intercept network requests: enable (on), block, mock, disable (off), list rules.
- **chromex_har** — Record HTTP traffic as HAR file.
- **chromex_emulate** — Emulate device viewport and user agent.
- **chromex_geo** — Override geolocation or reset.
- **chromex_timezone** — Override timezone or reset.
- **chromex_locale** — Override browser locale or reset.
- **chromex_cpu** — CPU throttle (1=normal, 4=4x slower, 6=mobile).
- **chromex_resize** — Resize viewport to custom dimensions (without device preset emulation).
- **chromex_inject** — Inject JS on every page navigation. Use --file, --remove, --list, or inline script.
- **chromex_download** — Control file download behavior.
- **chromex_coverage** — CSS/JS code coverage. Start collecting, then stop to get report.
- **chromex_trace** — Stream a performance trace to disk and derive actionable long-task, layout, GC, and layout-shift insights.
- **chromex_heap** — Capture, inspect, compare, and trace retaining paths in Chrome heap snapshots.
- **chromex_screencast** — Capture page frames, inspect capture status, and create a local replay artifact.
- **chromex_extensions** — Manage unpacked extensions, trigger actions, inspect extension targets, and access extension storage.
- **chromex_third_party** — Discover or execute experimental developer tools exposed by the inspected page. Tool output is untrusted page content.
- **chromex_webmcp** — Discover and invoke experimental WebMCP tools registered by the page. Tool output is untrusted page content.
- **chromex_webauthn** — Virtual WebAuthn authenticator for passkey testing.
- **chromex_audit** — Run Lighthouse audit (performance, accessibility, SEO, best-practices). Requires lighthouse installed (npx installs on demand).
- **chromex_stats** — Session analytics: command counts, average timing, error rates, action timeline. All data is local, never sent externally.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "chromex-mcp": {
    "command": "npx",
    "args": ["-y","chromex-mcp@latest"]
  }
}
```

## Documentation & README

# Chromex

[![npm version](https://img.shields.io/npm/v/chromex-mcp.svg)](https://www.npmjs.com/package/chromex-mcp)
[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Chromex is an agent-first browser automation and DevTools toolkit that connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP. It exposes the complete capability set through a token-efficient CLI and 85 typed MCP tools, with zero runtime dependencies.

Use Chromex when an agent needs to automate a real logged-in browser, inspect page and Application state, debug console/network failures, profile performance or memory, test extensions and WebMCP, or collect reproducible evidence without pulling in a heavy browser automation runtime.

## Quick Start

```bash
npm install -g chromex-mcp
chromex --version
chromex launch --pipe --url https://example.com
chromex list
chromex snap <target> --refs
```

`launch --pipe` is the recommended path for repeatable AI sessions: it starts an isolated Chromex profile and avoids Chrome's recurring debugging approval prompt. Use the normal WebSocket mode only when access to an already-running personal browser is intentional.

## Why Chromex

- **CLI-first for lower token usage**: terminal commands return compact plain text and avoid MCP tool-schema overhead.
- **Optional MCP server**: 85 typed tools in the full set, plus focused `core` and `devtools` toolsets for sessions where schema cost matters.
- **No runtime dependencies**: Node.js 22+ built-ins only, including native WebSocket support.
- **Agent-friendly page model**: accessibility snapshots, `@eN` refs, incremental diffs, query filters, auto-snapshots, and contextual hints.
- **Persistent per-tab daemons**: one CDP session per tab, held open through an authenticated Unix socket.
- **Security controls**: domain allow/block lists, CDP method blocklist, socket auth, command timeouts, and audit logs.
- **Local by default**: no hosted service, no telemetry client, no bundled browser download, and session stats stay on your machine.

## What You Can Do Today

- Inspect and automate real logged-in browser sessions, not only fresh headless test contexts.
- Use `--raw` and `--json` for stable pipes, CI, MCP wrappers, and agent-to-agent integrations.
- Create named sessions with isolated browser contexts, reusable targets, and local session dashboards.
- Read page state through compact accessibility snapshots, filtered snapshots, DOM snapshots, HTML, screenshots, and highlighted elements.
- Act on UI through refs, CSS selectors, coordinates, keyboard input, forms, uploads, drag and drop, touch gestures, dialogs, and load-more loops.
- Record every JavaScript dialog with its text and outcome. A command that opens a dialog returns at once with that text instead of hanging until the timeout.
- Debug production behavior with console history, network request details, response bodies, HAR export, request blocking, API mocking, throttling, and offline mode.
- Test browser conditions with device presets, viewport resizing, DPR, geolocation, timezone, locale, CPU throttling, incognito contexts, proxies, and custom Chrome flags.
- Diagnose performance and quality with Core Web Vitals, transfer size, DOM/memory counters, Lighthouse audits, JS/CSS coverage, Chrome traces, and heap snapshots.
- Inspect Browser Issues, computed and matched CSS, event listeners, box models, prioritized runtime diagnoses, CPU profiles, heap retaining paths, duplicate strings, and trace insights.
- Capture bounded screencasts with a local replay, manage extensions in trusted pipe mode, and discover or execute WebMCP and page-exposed developer tools.
- Build evidence packs with screenshots, snapshots, HTML, console, network, dialogs, action timeline, and replay HTML.
- Validate modern browser flows such as passkey/WebAuthn registration and login, downloads, cookies, portable storage state, PDF export, and isolated profiles.
- Inspect Application panel state from the terminal: origin quota, storage usage breakdown, Cache Storage entries/bodies, IndexedDB schemas/rows, and Service Worker registrations.
- Turn `@eN` refs into locators and optional `chromex-test` action code.

The CLI and the default MCP `full` toolset expose the same capability families. CLI commands group related operations into subcommands, while MCP presents 85 individually typed tools.

| Capability | CLI | MCP `full` |
|------------|-----|------------|
| Input, navigation, forms, uploads, dialogs, and emulation | Yes | Yes |
| Console, network, Application state, interception, HAR, and audits | Yes | Yes |
| Browser Issues, CSS/listener/box inspection, and runtime diagnosis | Yes | Yes |
| Web Vitals, CPU profiles, heap sampling, traces, and heap analysis | Yes | Yes |
| Screencasts, extensions, page developer tools, and WebMCP | Yes | Yes |

## Positioning

Chromex is a direct CDP layer for coding agents. It sits between raw Chrome DevTools Protocol and heavier browser automation frameworks.

| Alternative | Trade-off | Chromex angle |
|-------------|-----------|---------------|
| Raw CDP WebSocket | Maximum browser power, but too verbose for agents. | Compact commands, refs, snapshots, and safety defaults. |
| Heavy browser automation libraries | Excellent automation frameworks, but they add dependencies and framework-level abstractions. | Zero-runtime-dependency CLI/MCP that talks to your existing Chromium browser. |
| Browser MCP only | Easy tool discovery, but tool schemas and structured responses add token cost. | CLI-first for cheap agent loops, MCP when typed tools are worth the overhead. |
| Manual DevTools | Great for humans, not scriptable enough for agents. | DevTools-grade inspection exposed as terminal and MCP commands. |

## Requirements

- Node.js 22 or newer.
- macOS or Linux.
- A Chromium-based browser: Chrome, Brave, Edge, Chromium, Chrome Canary, or Vivaldi.

## Zero-Dependency Boundary

The core runtime uses only Node.js built-in modules. Chromex does not install heavy browser automation runtimes, Selenium, browser drivers, telemetry SDKs, update checkers, or bundled browsers.

The only exception is the optional `audit` command: it uses `npx` to resolve Lighthouse on demand, then runs the Lighthouse JavaScript CLI directly with Node when you explicitly run an audit. All other CLI and MCP commands run through Chromex's own CDP client.

Development dependencies are used only for tests and token benchmarks.

## Browser Setup

Chromex needs Chrome DevTools Protocol access to your browser. Choose one of the two connection modes below before using the CLI or MCP server.

### Option A: Launch a Browser with Chromex

This is the recommended first-time setup. Chromex starts a new browser process with remote debugging already enabled, so there is no manual browser configuration and no "Allow debugging" prompt.

```bash
chromex launch --url https://example.com
```

Useful launch variants:

```bash
chromex launch --browser brave --url https://example.com
chromex launch --profile testing --url https://example.com
chromex launch --incognito --browser chrome
chromex launch --headless --url https://example.com
chromex launch --pipe --url https://example.com
chromex launch --extension-tools --url about:blank
chromex launch --webmcp --url https://example.com
chromex launch --browser-path "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
```

Named profiles are stored under `~/.chromex/profiles/` and keep test sessions isolated from your daily browser profile.

`chromex launch --pipe` is the preferred mode for repeated AI sessions. It uses one permission-protected local Unix-socket broker over Chrome's remote-debugging pipe, avoids approval modals, and lets CLI and MCP clients share the same browser connection. `--extension-tools` implies pipe mode because Chrome restricts extension lifecycle APIs to trusted debugging sessions. WebMCP requires a visible supported Chrome build, so do not combine `--webmcp` with `--headless` when the page tools must execute.

Chrome for Testing also works well with Chromex. Download it manually from Google's official Chrome for Testing channel, then point Chromex at the executable with `--browser-path` or `CHROMEX_BROWSER_PATH`. Chromex does not download or bundle a browser.

### Option B: Connect to an Already-Running Browser

Use this when you want Chromex to inspect tabs that are already open in your normal browser.

1. Open Chrome, Brave, Edge, Chromium, or Vivaldi.
2. Go to `chrome://inspect/#remote-debugging`.
3. Enable the remote debugging switch.
4. Run `chromex list` to verify that tabs are visible.

```bash
chromex list
```

Important notes:

- Without remote debugging enabled, Chromex cannot discover or control your open tabs.
- The browser setting is usually persistent across restarts.
- Chrome may show an "Allow debugging" prompt for each new DevTools WebSocket connection to a normal browser profile. This is browser security behavior, so reconnecting from a new CLI or agent process can show it again.
- Per-tab daemons and the persistent MCP connection reduce reconnections, but they do not bypass Chrome's protection for a personal browser profile.
- Use `chromex launch --pipe` with a Chromex-managed isolated profile when a modal-free persistent AI connection is required.

If your browser uses a custom profile or a non-standard `DevToolsActivePort` location, set:

```bash
export CDP_PORT_FILE=/path/to/DevToolsActivePort
```

If your Chromium executable is installed in a non-standard location, either pass `--browser-path` to `chromex launch` or set:

```bash
export CHROMEX_BROWSER_PATH=/path/to/chrome
```

Run the local diagnostic command whenever browser discovery or CDP connection fails:

```bash
chromex doctor
```

## Install the CLI

Install the package globally to get the `chromex` command.

```bash
# npm
npm install -g chromex-mcp

# Bun
bun add -g chromex-mcp
```

Verify which installation every terminal and agent session will use:

```bash
command -v chromex
chromex --version
```

Cloning the repository does not replace an existing global installation. To test the current checkout directly, run `node bin/chromex.mjs`. To deliberately install the current checkout globally, run `npm install -g .` from the repository root and verify the path and version again.

The package installs three binaries:

| Binary | Purpose |
|--------|---------|
| `chromex` | Main CLI for terminal, scripts, CI, and token-sensitive agent sessions. |
| `chromex-cli` | Alias for `chromex`. |
| `chromex-mcp` | MCP server over stdio JSON-RPC. Usually launched by an MCP client. |

## CLI Quick Start

The CLI is the recommended interface when token budget matters. It has no MCP schema overhead, works well in scripts, and returns compact plain-text output designed for LLM agents.

```bash
# 1. Launch or connect to a browser.
chromex launch --url https://github.com/login

# 2. List tabs and copy a target prefix.
chromex list
# 6BE827FA  Sign in to GitHub  https://github.com/login

# 3. Read the page through the accessibility tree and assign refs.
chromex snap 6BE8 --refs
# @e1 [textbox] Username or email address
# @e2 [textbox] Password
# @e3 [button] Sign in

# 4. Interact by ref instead of fragile CSS selectors.
chromex fill 6BE8 @e1 "user@example.com"
chromex fill 6BE8 @e2 "secret"
chromex click 6BE8 @e3

# 5. Inspect browser state.
chromex console 6BE8 list
chromex net 6BE8
chromex shot 6BE8
chromex app 6BE8
```

`<target>` is a unique prefix of the tab target ID returned by `chromex list`. If a prefix is ambiguous, Chromex rejects it and asks for more characters.

For repeatable agent workflows, use named sessions instead of carrying target IDs manually:

```bash
chromex -s auth open https://github.com/login
chromex -s auth snap --refs
chromex -s auth fill @e1 "user@example.com"
chromex -s auth state save ~/.chromex/storage/auth.json
chromex sessions
```

## Token-Efficient Agent Workflow

Chromex is optimized for agents that need to act on browser state without wasting context.

1. Start with `chromex list`.
2. Prefer `chromex snap <target> --refs` over raw HTML.
3. Use `@eN` refs for `click`, `fill`, `hover`, and element screenshots.
4. On large pages, use `--query` before reading a full snapshot.
5. Let auto-snapshot show post-action state after interactive commands.
6. Add `--no-snap` only for fast scripted batches where you do not need immediate page state.
7. Add `--no-hints` when another program parses output strictly.
8. Use `--raw` for pipes and `--json` when another tool needs the stable envelope.
9. Save large snapshots with `--filename` when they are better as artifacts than inline text.

Examples:

```bash
chromex snap 6BE8 --query=login --refs
chromex click 6BE8 @e4
chromex wait 6BE8 networkidle
chromex snap 6BE8 --query=error
chromex --raw eval 6BE8 "document.title"
chromex list --json
chromex snap 6BE8 --filename=~/.chromex/snapshots/login.yml --boxes
chromex locator 6BE8 @e4 --format=chromex-test
chromex click 6BE8 @e4 --code=chromex-test
```

## MCP Server

Use MCP when you want Claude Code or another MCP client to discover typed browser tools directly. MCP is convenient, but it costs more tokens than CLI usage because tool schemas, JSON-RPC framing, and structured tool results add overhead.

### Add to Claude Code

Global, available in all projects:

```bash
# npm
claude mcp add chromex --scope user -- npx -y chromex-mcp@latest

# Bun
claude mcp add chromex --scope user -- bunx chromex-mcp@latest
```

Project-only:

```bash
# npm
claude mcp add chromex -- npx -y chromex-mcp@latest

# Bun
claude mcp add chromex -- bunx chromex-mcp@latest
```

For MCP clients that accept a standard stdio configuration, point the client at the installed binary:

```json
{
  "mcpServers": {
    "chromex": {
      "command": "chromex-mcp",
      "args": []
    }
  }
}
```

After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_network`, `chromex_issues`, `chromex_inspect`, `chromex_diagnose`, `chromex_perf`, `chromex_trace`, `chromex_heap`, `chromex_screencast`, `chromex_extensions`, `chromex_third_party`, `chromex_webmcp`, `chromex_app_summary`, `chromex_cache_entries`, `chromex_indexeddb_rows`, and `chromex_evidence`.

Tools that produce machine-readable data or artifacts also include MCP `structuredContent`, so agents can read paths and metadata without parsing the human text block.

The default `full` toolset exposes all 85 tools. Use a focused toolset when the MCP client sends every schema into the model context:

```bash
chromex-mcp --toolset=core
chromex-mcp --toolset=devtools
CHROMEX_TOOLSET=full chromex-mcp
```

`core` exposes 24 navigation, inspection, input, form, and emulation tools. `devtools` exposes 26 browser-diagnostics, performance, trace, heap, Application, and audit tools. This selection changes discovery only; the complete CLI and the default MCP toolset retain every capability.

### Claude Code Auto-Approve

To approve all Chromex MCP tools at once, add this to `~/.claude/settings.json`:

```json
{
  "permissions": {
    "allow": ["mcp__chromex"]
  }
}
```

For CLI usage inside Claude Code, approve the shell command instead:

```json
{
  "permissions": {
    "allow": [
      "Bash(chromex *)",
      "Bash(chromex-cli *)"
    ]
  }
}
```

Review these permissions before enabling them. Chromex security settings still apply, and every command is audit-logged when `auditLog` is enabled.

## CLI vs MCP

Both interfaces use the same CDP core and the same per-tab daemons. Choose based on the workflow.

| Use case | Prefer CLI | Prefer MCP |
|----------|------------|------------|
| Token-sensitive agent sessions | Yes | No |
| Terminal scripts and CI | Yes | No |
| Quick one-off browser inspection | Yes | Optional |
| Typed tool discovery in Claude Code | No | Yes |
| Inline screenshots returned to the client | No, screenshots are files | Yes |
| Granular per-tool permissions | Shell pattern only | Yes |
| Lowest setup friction for MCP users | Optional | Yes |

You can remove MCP at any time and keep using the CLI:

```bash
claude mcp remove chromex
```

## Command Overview

### Pages and Browser

```bash
chromex list
chromex list --include-sensitive
chromex open "https://example.com"
chromex -s auth open "https://example.com/login"
chromex -s auth snap --refs
chromex sessions
chromex show --annotate
chromex close <target>
chromex focus <target>
chromex launch --url https://example.com
chromex launch --browser brave --incognito
chromex launch --headless --url https://example.com
chromex launch --pipe --url https://example.com
chromex launch --extension-tools --url about:blank
chromex launch --webmcp --url https://example.com
chromex launch --browser-path /path/to/chrome --url https://example.com
chromex doctor
chromex incognito https://example.com
chromex stop
```

### Inspect

```bash
chromex snap <target> --refs
chromex snap <target> --query=login
chromex snap <target> --filename=~/.chromex/snapshots/login.yml --boxes
chromex html <target> "#main"
chromex shot <target>
chromex shot <target> ~/.chromex/screenshots/full.png --full
chromex shot <target> @e5
chromex console <target> list
chromex net <target>
chromex net <target> <requestId> --include-sensitive
chromex net <target> <requestId> --body-limit=100000
chromex perf <target>
chromex domsnapshot <target> --styles
chromex issues <target> enable
chromex issues <target> list
chromex inspect <target> all "#checkout"
chromex diagnose <target>
chromex evidence <target> start checkout-flow
chromex evidence <target> mark "after login"
chromex evidence <target> stop
chromex evidence <target> replay
```

### Navigate and Wait

```bash
chromex nav <target> "https://example.com"
chromex nav <target> back
chromex nav <target> reload-hard
chromex waitfor <target> ".results" 10000
chromex wait <target> networkidle
chromex scroll <target> bottom
```

### Interact

```bash
chromex click <target> @e5
chromex clickxy <target> 100 200
chromex key <target> Enter
chromex type <target> "hello world"
chromex hover <target> @e12
chromex locator <target> @e12 --format=chromex-test
chromex click <target> @e12 --code=chromex-test
chromex drag <target> "#source" "#dest"
chromex dialog <target> accept
chromex dialog <target> auto
chromex dialog <target> log
```

### Forms

```bash
chromex fill <target> @e1 "user@example.com"
chromex clear <target> "#search"
chromex select <target> "#country" "BR"
chromex check <target> "#terms" true
chromex upload <target> "#avatar" /tmp/photo.png
chromex form <target> '{"#name":"John","#email":"john@example.com","#terms":true}'
```

### Data

```bash
chromex cookies <target>
chromex cookies <target> set '{"name":"token","value":"abc"}'
chromex storage <target> local
chromex storage <target> session
chromex storage <target> usage
chromex state <target> save ~/.chromex/storage/auth.json
chromex state <target> load ~/.chromex/storage/auth.json
chromex app <target> summary
chromex sw <target>
chromex cache <target> list
chromex cache <target> entries <cacheId> --query=/api
chromex idb <target> list
chromex idb <target> schema <databaseName>
chromex idb <target> rows <databaseName> <objectStoreName> --limit=20
chromex pdf <target>
```

### Network, Emulation, and Diagnostics

```bash
chromex throttle <target> 3g
chromex intercept <target> block "*.analytics.*"
chromex intercept <target> mock "/api/user" --status=200 --content-type=application/json --body='{"ok":true}'
chromex intercept <target> mock "/api/slow" --delay=750 --status=503 --body='unavailable'
chromex intercept <target> block "*.tracker.*" --abort=blockedbyclient
chromex intercept <target> on --remove-header=authorization
chromex har <target> start
chromex har <target> stop ~/.chromex/har/trace.har
chromex emulate <target> iphone-15-pro
chromex resize <target> 1280 720
chromex geo <target> -23.55 -46.63
chromex timezone <target> "America/Sao_Paulo"
chromex cpu <target> 4
chromex audit <target> performance,accessibility desktop
chromex stats <target> --full
```

### Advanced

```bash
chromex eval <target> "document.title"
chromex evalraw <target> "Page.getLayoutMetrics"
chromex inject <target> "window.DEBUG=true"
chromex download <target> allow ~/.chromex/downloads
chromex coverage <target> start
chromex trace <target> start
chromex trace <target> insights
chromex heap <target> snapshot ~/.chromex/heap/heap.heapsnapshot
chromex heap <target> summary
chromex screencast <target> start --max-frames=120
chromex extensions <target> list
chromex third-party <target> list
chromex webmcp <target> list
chromex webauthn <target> enable
```

Run `chromex --help` for the full command reference.

## Agent-Focused Features

### Ref-Based Selection

`chromex snap --refs` assigns stable refs to interactive elements:

```bash
chromex snap <target> --refs
# @e1 [textbox] Email
# @e2 [textbox] Password
# @e3 [button] Sign in

chromex fill <target> @e1 "user@example.com"
chromex click <target> @e3
```

Refs are shorter and more robust than CSS selectors for most agent workflows.

### Incremental Snapshots

The first snapshot returns the page tree. Later snapshots return only changed nodes unless you pass `--full`.

```bash
chromex snap <target> --refs
chromex click <target> @e3
# The click response includes a fresh incremental snapshot with refs.
```

### Query-Filtered Snapshots

Use `--query` to keep output small on large pages:

```bash
chromex snap <target> --query=issues --refs
chromex snap <target> --query="sign in" --refs
```

Chromex preserves ancestor nodes so the filtered output still has usable context.

### Contextual Hints

After actions that refresh refs, Chromex can append a `help[N]:` block with likely next commands:

```text
help[3]:
  chromex fill <t> @e1 "<value>"  # textbox "Email"
  chromex click <t> @e3           # button "Sign in"
  chromex click <t> @e4           # link "Forgot password?"
```

Disable hints with `--no-hints`.

### Stable Output and Artifacts

Chromex keeps plain text as the default output, but also supports stable modes for scripts:

```bash
chromex --raw eval <target> "document.title"
chromex list --json
chromex snap <target> --filename=~/.chromex/snapshots/home.yml --boxes
```

`--raw` prints only the primary command output and suppresses hints and auto-snapshot noise. `--json` returns a stable envelope with `ok`, `command`, `target`, `text`, `data`, `artifacts`, and `error`.

Generated artifacts are written under `~/.chromex/artifacts/<workspace>/` by default. Paths in the Chromex namespace, such as `.chromex/storage/auth.json` or `~/.chromex/storage/auth.json`, resolve to `~/.chromex/...`. Other explicit absolute or relative file paths are respected as provided. Set `CHROMEX_ARTIFACT_ROOT` to override the default artifact root for CI or tests.

### Named Sessions

Named sessions let agents reuse isolated browser contexts without carrying target IDs:

```bash
chromex -s auth open https://example.com/login
chromex -s auth snap --refs
chromex -s auth click @e3
chromex sessions
chromex show --annotate
chromex close-all
chromex delete-data auth
```

`CHROMEX_SESSION=auth` can replace `-s auth` for shell scripts.
`chromex show` opens the generated dashboard in the default browser during normal CLI usage; set `CHROMEX_NO_OPEN=1` or use `--json`/`--raw` to only write the artifact.

Named sessions keep a private storage-state file under `~/.chromex/session-data/<name>/storage-state.json`. Chromex restores it when the named session gets a new tab, through `-s <name> open <url>` or a `-s <name> launch` that starts a fresh browser, and then loads the requested URL again, so a page that redirected to a sign-in form before the cookies arrived opens as asked. A reused browser keeps its live cookies. Chromex refreshes the file after state-changing session commands.

Each named session remembers the browser it lives in. While that browser answers, `-s <name>` commands go to it even after another browser is launched, and a session tab missing from the shared page list is looked up in the session's own browser. An explicit `--cdp-url` or `CHROMEX_CDP_URL` still wins.

To give an agent its own browser without disturbing other sessions, launch it for a named session:

```bash
chromex -s qa launch --headless --profile qa --url https://app.example.test/login
chromex -s qa snap --refs
chromex -s qa close
```

`launch` with `-s` makes the first tab the session tab. A browser launched for a session is marked in its profile and is never chosen as the default browser for other clients while another browser answers. When that profile's browser is still running, `launch` reuses it, keeps the mark, and opens `--url` in a new tab, so a session can close its tab at the end of a run and launch again next time. Commands without `-s` keep using the most recently launched browser, so prefer named sessions when several agents share one machine.

`chromex show --annotate` generates a local dashboard with screenshot previews, region/point marking, per-mark notes, and JSON export. Browsers with File System Access support can save the exported pack directly; other browsers download the JSON file.

### Storage State and Locators

Storage state captures cookies plus localStorage for the current origin:

```bash
chromex state <target> save ~/.chromex/storage/auth.json
chromex state <target> load ~/.chromex/storage/auth.json
```

Refs can also be converted into reusable locator output or starter action code:

```bash
chromex locator <target> @e5 --format=chromex-test
chromex locator <target> @e5 --format=css
chromex locator <target> @e5 --format=testing-library
chromex fill <target> @e1 "user@example.com" --code=chromex-test
```

### Evidence Packs

Evidence packs collect browser evidence without recording video:

```bash
chromex evidence <target> start checkout-flow
chromex click <target> @e3
chromex fill <target> @e5 "user@example.com"
chromex evidence <target> mark "after login"
chromex evidence <target> stop
chromex evidence <target> replay
```

Each pack is written under `~/.chromex/artifacts/<workspace>/evidence/` and includes screenshots, accessibility snapshots with boxes, HTML captures, console JSON, network JSON, dialog JSON, interception rules with their hits, action timeline, `evidence.json`, and `index.html` for local replay. Values passed to `fill`, `type`, and `form` are redacted from the action timeline, including the command output that repeats them.

The console, network, and dialog files hold only what was recorded while the pack was open, so one pack per test scenario shows that scenario alone. Pass `--dir` to `start` or `capture` to write the pack into your own folder, such as a CI artifacts directory; Chromex refuses a directory that already holds a pack:

```bash
chromex evidence <target> start scenario-1 --dir=./artifacts/evidence/scenario-1
```

Screenshots, snapshots, and HTML show the page as it was, unmasked. Keep packs from pages with real personal data out of public tickets and repositories.

## Application State Suite

Chromex exposes browser Application panel state without heavy browser automation runtimes or extra packages. This is useful for debugging PWAs, offline behavior, stale caches, local database migrations, authentication state, and quota issues from the same logged-in browser session an agent is already using.

```bash
# One-line overview for the current origin
chromex app <target> summary

# Origin quota and per-storage-type usage
chromex storage <target> usage

# Service Worker registrations and versions
chromex sw <target>
chromex sw <target> update https://example.com/
chromex sw <target> skip-waiting https://example.com/

# Cache Storage
chromex cache <target> list
chromex cache <target> entries <cacheId> --query=/api
chromex cache <target> body <cacheId> https://example.com/app.js

# IndexedDB
chromex idb <target> list
chromex idb <target> schema app-db
chromex idb <target> rows app-db users --limit=20
```

`chromex app <target> summary` includes origin, quota, localStorage key count, sessionStorage key count, cookie count, Cache Storage cache/entry counts, IndexedDB database count, active/waiting Service Worker counts, storage bucket count, and manifest status.

Destructive Application commands are explicit: `storage clear-site-data`, `sw unregister`, `cache delete-entry`, `cache delete`, and `idb clear`.

## Security

Chromex creates `~/.chromex/config.json` on first run:

```json
{
  "commandTimeout": 15000,
  "navigationTimeout": 30000,
  "idleTimeout": 1200000,
  "allowedDomains": [],
  "blockedDomains": [],
  "blockedCdpMethods": [
    "Network.enable",
    "Network.setRequestInterception",
    "Network.setCacheDisabled",
    "Page.setDocumentContent",
    "Security.disable",
    "Security.setIgnoreCertificateErrors",
    "Fetch.enable",
    "Fetch.fulfillRequest",
    "Fetch.continueRequest",
    "Browser.close",
    "Browser.crashGpuProcess",
    "Target.disposeBrowserContext",
    "SystemInfo.getProcessInfo",
    "Storage.clearDataForOrigin",
    "Storage.getCookies",
    "IndexedDB.requestData"
  ],
  "auditLog": true,
  "socketAuth": true
}
```

Recommended security practices:

- Add sensitive sites to `blockedDomains`, such as email, banking, password managers, and admin panels.
- Use `allowedDomains` in restricted environments where the agent should access only specific hosts.
- Keep `socketAuth` enabled.
- Keep `auditLog` enabled and review `~/.chromex/audit.log` when needed.
- Prefer `chromex launch --profile testing` for isolated browser state.

Page URLs, network, console, extension-storage, third-party, and WebMCP outputs redact secret-shaped headers and fields by default. The browser still sends and receives the original values. Use CLI `--include-sensitive` or MCP `includeSensitive: true` only on the specific live call that needs exact values. Audit logs, page caches, stats, HAR, and structured evidence timelines, network data, and console data remain redacted even when a live response is revealed. Screenshots, screencasts, snapshots, HTML, traces, heap snapshots, and raw page content can still contain sensitive information and should be handled accordingly.

See [docs/security.md](https://github.com/whallysson/chromex/blob/HEAD/docs/security.md) for the full security model.

## How It Works

```text
CLI or MCP client -> authenticated Unix socket -> per-tab daemon -> CDP WebSocket -> browser
                                                        \-> pipe broker -> Chrome debugging pipe
```

1. Chromex finds a browser DevTools endpoint or a Chromex pipe-broker marker.
2. The first tab command starts a detached daemon for that tab.
3. The daemon attaches once through CDP and keeps the session open.
4. CLI and MCP commands talk to the daemon through an authenticated Unix socket; pipe mode multiplexes CDP through a second local socket restricted to the current OS user.
5. Daemons exit after the configured idle timeout.

See [docs/architecture.md](https://github.com/whallysson/chromex/blob/HEAD/docs/architecture.md) for implementation details.

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](https://github.com/whallysson/chromex/blob/HEAD/docs/getting-started.md) | Installation, browser setup, first commands. |
| [Inspect and Debug](https://github.com/whallysson/chromex/blob/HEAD/docs/inspect.md) | Screenshots, accessibility tree, refs, Browser Issues, CSS/listener inspection, diagnostics, performance, and console. |
| [Navigate and Interact](https://github.com/whallysson/chromex/blob/HEAD/docs/navigate.md) | Navigation, clicking, typing, scrolling, drag and drop, touch, dialogs. |
| [Form Filling](https://github.com/whallysson/chromex/blob/HEAD/docs/forms.md) | Fill, clear, select, check, upload, batch form examples. |
| [Data Access](https://github.com/whallysson/chromex/blob/HEAD/docs/data.md) | Cookies, localStorage, sessionStorage, Application state, Cache Storage, IndexedDB, Service Workers, PDF export. |
| [Network Control](https://github.com/whallysson/chromex/blob/HEAD/docs/network.md) | Live request history and bodies, filtering, redaction, throttling, interception, mocking, and HAR. |
| [Device Emulation](https://github.com/whallysson/chromex/blob/HEAD/docs/emulation.md) | Responsive testing, geolocation, timezone, CPU throttling. |
| [Security](https://github.com/whallysson/chromex/blob/HEAD/docs/security.md) | Domain filtering, CDP blocklist, audit log, best practices. |
| [Advanced](https://github.com/whallysson/chromex/blob/HEAD/docs/advanced.md) | CPU and heap profiles, trace insights, heap graph analysis, screencasts, extensions, page tools, WebMCP, and WebAuthn. |
| [Architecture](https://github.com/whallysson/chromex/blob/HEAD/docs/architecture.md) | Daemon model, connection modes, and file layout. |
| [Troubleshooting](https://github.com/whallysson/chromex/blob/HEAD/docs/troubleshooting.md) | Installation drift, connection failures, debugging prompts, Node warnings, extensions, and WebMCP. |

## Development

```bash
git clone https://github.com/whallysson/chromex.git
cd chromex
bun install
bun run test
```

The runtime package has no dependencies. Development dependencies are used only for tests and token benchmarks.

Run the browser-backed smoke flow explicitly when validating a release candidate:

```bash
bun run test:smoke
```

The smoke script launches a temporary headless Chromium profile through `CDP_PORT_FILE`, exercises named sessions, snapshots, locators, storage state, annotation dashboard artifacts, and then stops the launched process.

To reproduce the token-format comparison:

```bash
bun tests/benchmarks/token-format-comparison.mjs
```

## License

MIT. See [LICENSE](https://github.com/whallysson/chromex/blob/HEAD/LICENSE).