High-performance rust CLI that connects to an existing Chrome browser via the DevTools Protocol. Auto-connects by default, no manual WebSocket URL needed.

brew install aeroxy/tap/chrome-devtools

cargo install chrome-devtools-cli

The installed binary is named chrome-devtools.

cargo build --release
# Binary: ./target/release/chrome-devtools

Inspired by chrome-devtools-mcp — the official MCP server for Chrome DevTools. It works well, but MCP-based browser tools consume a lot of token context: every interaction sends and receives large protocol payloads through the MCP layer.

99% of the time the browser being controlled is the user's own Chrome with their own credentials, so there is no need for a full headless browser stack like Puppeteer or Playwright, and no need for the MCP overhead.

This is a lightweight Rust binary that talks directly to Chrome's DevTools Protocol. One command in, one result out. No separate browser process, no credential handoff, no heavyweight runtime. The agent skill for this tool is a single SKILL.md file — the entire context overhead is this documentation.

chrome-devtools navigate https://example.com
        │
        ├─ Try daemon (Unix socket /tmp/chrome-devtools-daemon.sock)
        │   └─ If running → send command → get result
        │
        ├─ If no daemon → spawn one (background process)
        │   └─ Daemon connects to Chrome WebSocket (one-time approval)
        │   └─ Listens on Unix socket, 5-min idle timeout
        │
        └─ Fallback → direct WebSocket connection (no daemon)

The daemon keeps a persistent WebSocket connection to Chrome, so the browser only prompts for DevTools access once. Subsequent commands reuse the connection.

Chrome must have remote debugging enabled:

1. Open Chrome
2. Go to chrome://inspect/#remote-debugging
3. Enable the remote debugging server

By default, the CLI reads DevToolsActivePort from Chrome's user data directory:

Override with --user-data-dir, --channel (beta/canary/dev), or --ws-endpoint. All three also read from environment variables:

Every page-level command outputs a friendly target name like [target:red-snake]. This is a deterministic word-pair derived from Chrome's internal target ID — same page always gets the same name.

# Navigate — note the target name
chrome-devtools navigate https://example.com
# Navigated to https://example.com
# [target:red-snake]

# Pin subsequent commands to the same page
chrome-devtools --target red-snake screenshot --output /tmp/page.png
chrome-devtools --target red-snake evaluate "document.title"

Without --target, commands default to page index 0, which may vary as Chrome reorders tabs. Always capture and reuse the target name.

list-pages shows all pages with their friendly names:

[0] (green-dog) My App — https://localhost:3000
[1] (red-snake) Example Domain — https://example.com
[2] (bold-stag) GitHub — https://github.com

You can also use --page <index> for quick one-offs, or pass the raw hex target ID.

navigate and new-page accept atomic emulation flags (--viewport, --mobile, --device-scale-factor, --geolocation, --accuracy) and --extra-headers for custom HTTP headers, so you can navigate and emulate in a single call.

These commands interact with tools injected into the page via window.__dtmcp.toolGroup / window.__dtmcp.executeTool.

emulate with no flags shows the active tab's overrides. Viewport, geolocation, and URL blocks are all per-tab — each page keeps its own. They persist across navigation within that tab and do not leak to other tabs, so you can hold (say) a mobile viewport with images blocked on one tab and a desktop baseline on another at the same time. They persist until you clear them (--clear-viewport, --clear-geolocation, --clear-blocks, or --clear-all), the tab closes, or the daemon exits.

The daemon keeps a persistent CDP session on the active page that continuously collects Network and Runtime events. console and network drain whatever has accumulated since the last call (or since the session attached, if never drained).

A drain without a --duration returns instantly. Adding --duration N switches the command to live mode and blocks for N ms.

kill-daemon signals the running daemon with SIGTERM, removes the socket and PID file, and exits. It's a no-op if no daemon is running. Prefer this over pkill -f __daemon__ — the process name is shared by legitimate Chrome children processes.

Global --block-url and --unblock-url update the active tab's block list and apply via Network.setBlockedURLs; the daemon re-applies each tab's list when that tab is in use, so blocking is isolated per tab. Note: Chrome only blocks subresources (images, scripts, fetch/XHR, stylesheets, CDN, trackers, fonts). The top-level navigation document itself is never blocked — e.g. --block-url "*example.com*" then navigate https://example.com still loads the page, but any *.png, *.woff2, etc. subresources on it are blocked.

• Socket: /tmp/chrome-devtools-daemon.sock
• PID file: /tmp/chrome-devtools-daemon.pid
• Idle timeout: 5 minutes (auto-exits, cleans up socket)
• Protocol: Length-prefixed JSON over Unix socket
• Spawned by: First CLI invocation (transparent to user)
• Kill: chrome-devtools kill-daemon (or delete the socket + PID file)

The daemon keeps a persistent CDP session on the current page to:

• Continuously collect Network.* and Runtime.consoleAPICalled/exceptionThrown events for console and network drains.
• Re-apply Network.setBlockedURLs and emulation state across page-level commands.
• Re-attach to a new target when --target changes (the previous target's event buffers are discarded on the switch).

- +text src/ ├── main.rs # Entry point + daemon dispatch

├── lib.rs # CLI (clap) + command routing ├── cdp.rs # Raw CDP over WebSocket (JSON-RPC) + persistent session ├── browser.rs # Auto-connect (DevToolsActivePort) ├── daemon.rs # Background daemon (persistent connection) ├── client.rs # Talks to daemon via Unix socket ├── protocol.rs # IPC message types (DaemonRequest / DaemonResponse) ├── friendly.rs # Target ID → word-pair names ├── format.rs # OutputFormat (text/json/toon) + format_structured helper ├── result.rs # Command result types ├── error.rs # CLI error types and codes ├── constants.rs # Shared constants ├── telemetry.rs # Logging and telemetry └── commands/ ├── mod.rs ├── navigate.rs ├── pages.rs # list/new/close/select/wait-for ├── screenshot.rs ├── evaluate.rs ├── executor.rs # Command dispatch + persistent-session reuse ├── input.rs # click/fill/type/press/hover ├── snapshot.rs ├── emulation.rs # emulate (viewport/geolocation/blocklist get/set/clear) ├── console.rs # console drain / live collection ├── network.rs # network drain / live collection ├── sw_logs.rs # extension service-worker log collection └── third_party.rs # list-3p-tools/execute-3p-tool

## Typical workflow

```bash
# 1. Navigate — capture the [target:name]
chrome-devtools navigate https://example.com
# [target:red-snake]

# 2. Understand the page
chrome-devtools --target red-snake snapshot
chrome-devtools --target red-snake screenshot --output /tmp/page.png

# 3. Interact
chrome-devtools --target red-snake fill "#email" "user@example.com"
chrome-devtools --target red-snake click "#submit"

# 4. Extract data
chrome-devtools --target red-snake evaluate "document.title"

# 5. Inspect what the page did under the hood
chrome-devtools --target red-snake network      # drain accumulated requests
chrome-devtools --target red-snake console       # drain console + exceptions

Always pass --target from step 2 onward to stay on the same page.

skill/chrome-devtools/SKILL.md is a Claude Code skill that teaches the agent how to use this binary. Drop it into any Claude Code plugin's skills/ directory and set chrome-devtools to the binary path. The skill covers the full workflow, all commands, and the --target pinning pattern — everything needed to reliably automate Chrome without large context overhead.

MIT