Chrome Control

---
name: chrome-control
description: Use when debugging web applications, diagnosing page errors, inspecting console output, or capturing screenshots via Chrome DevTools Protocol (CDP).
---

# Chrome Control

Control Chrome via CDP. Connects to user's running Chrome — all tabs, cookies, logins accessible.

## Prerequisites

User must enable `chrome://inspect/#remote-debugging` in Chrome.

The daemon starts automatically on first command. No explicit `start` needed.
User clicks Allow once on the Chrome permission dialog.

Chrome pops a permission dialog on every new WebSocket connection. The daemon holds that single connection open so the user clicks Allow once and all subsequent CLI calls go through without prompts. Each command is a one-shot call; the caller does not hold any connection. The daemon idles out after 5 min of no commands. Unix socket: /tmp/chromectl-{uid}.sock.

If connection fails → tell user to check remote debugging is enabled, or offer legacy mode (`launch`).

Tool responses are sanitized: prompt-injection markers in page content are stripped before reaching the LLM.

## Commands

```bash
chromectl.py list
chromectl.py open https://example.com
chromectl.py status
chromectl.py targets
chromectl.py stop
```

Use `--json` for machine-parseable JSON output (default is human-readable).

## Target commands

All target commands: `chromectl.py TARGET COMMAND [ARGS]`

Target ID from list/open output. Prefix match OK (e.g. `88FA` instead of full 32-char ID).

```bash
chromectl.py ABC123 eval "document.title"
chromectl.py ABC123 screenshot -o page.png [--full-page]
chromectl.py ABC123 console-tail [--for 30]
chromectl.py ABC123 navigate https://example.com
```

## DOM helpers

Shorthands for common eval patterns. Selectors are CSS.

```
  click/check/uncheck/highlight SELECTOR
  submit/clear FORM
  type/fill SELECTOR TEXT
  select SELECTOR VALUE
  get-text/get-html/get-value/exists/count/get-texts SELECTOR
  get-attr SELECTOR ATTR
  scroll-to/wait-for/wait-hidden SELECTOR
  wait-text SELECTOR TEXT
  navigate URL
  wait-url PATTERN
  scroll-up/scroll-down [PIXELS]
  scroll-by X Y
  inject-css CSS
  reload/back/forward/get-title/get-url/scroll-top/scroll-bottom
```

Wait commands: --timeout N (default 10s)

For anything not covered: `chromectl.py ABC123 eval "JS expression"`

Top-level await: `chromectl.py ABC123 eval "await fetch('/api').then(r => r.json())"`

## Raw CDP

```bash
chromectl.py cdp Browser.getVersion
chromectl.py cdp Target.getTargets
```

## Legacy mode

For clean browser without existing sessions: `chromectl.py launch [--headless]`

## Resources

- `chromectl-reference.md` — all options, socket protocol, troubleshooting