---
name: chrome-cdp-control
display-name: Chrome CDP Control
description: Connect to and operate a user-visible Chrome session through CDP
  for browser inspection, navigation, and interaction.
---

# Chrome CDP Control

Use Chrome DevTools Protocol (CDP) when the user asks you to inspect or operate their Chrome browser. Take initiative: inspect the live page, perform requested browser actions, verify the result, and report concise outcomes.

## Operating principles

- Treat the browser as user-controlled state. Never close, replace, or relaunch an existing browser without explaining the impact and obtaining approval when data could be lost.
- Prefer a separately launched CDP profile. Modern Chrome may ignore remote-debugging flags for its default profile.
- Never read, print, screenshot, or retain passwords, verification codes, card numbers, security codes, session tokens, cookie values, or other secrets. Leave secret-entry steps to the user.
- Inspect before acting. After navigation, clicks, form submissions, or permission changes, inspect again and verify the resulting URL, visible notice, or data row.
- Prepare consequential changes, summarize them, and pause before the final irreversible or high-impact action unless the user has explicitly authorized that exact action.
- Use exact URLs, selectors, accessible names, and visible text. Do not guess when multiple targets match.
- Prefer normal mouse and keyboard CDP events over calling `element.click()` or assigning `input.value`; framework-controlled pages often ignore synthetic DOM changes.

## Connect or launch

1. Test the standard endpoint:

   ```bash
   curl -fsS http://127.0.0.1:9222/json/version
   ```

2. If unavailable, inspect running browser processes and listening ports. A Chrome process without a remote-debugging endpoint cannot be attached in place.
3. If the user wants you to launch a controllable instance, call `get_scratchpad_folder`, create a profile folder there, and launch:

   ```bash
   open -na "Google Chrome" --args \
     --remote-debugging-address=127.0.0.1 \
     --remote-debugging-port=9222 \
     --user-data-dir="<scratchpad>/chrome-cdp-profile" \
     "<requested-url>"
   ```

4. Explain that a scratchpad profile persists across immediate restarts only while that scratchpad exists. For durable use, offer a dedicated persistent profile and obtain permission before writing outside the workspace.
5. Never expose the CDP port beyond loopback.

## Use the bundled helper

Resolve `scripts/cdp.mjs` relative to this `SKILL.md`. It uses Node's built-in WebSocket and has no third-party dependencies.

```bash
node <skill-folder>/scripts/cdp.mjs list
node <skill-folder>/scripts/cdp.mjs body --target-url 'example.com/path'
node <skill-folder>/scripts/cdp.mjs navigate --target-url 'example.com' --url 'https://example.com/new'
node <skill-folder>/scripts/cdp.mjs new --url 'https://example.com/'
node <skill-folder>/scripts/cdp.mjs click-text --target-url 'example.com' --text 'Continue'
node <skill-folder>/scripts/cdp.mjs type --target-url 'example.com' --selector 'input[name=email]' --text 'person@example.com'
node <skill-folder>/scripts/cdp.mjs eval --target-url 'example.com' --expression 'document.title'
node <skill-folder>/scripts/cdp.mjs screenshot --target-url 'example.com' --output '/absolute/scratchpad/page.png'
node <skill-folder>/scripts/cdp.mjs clear-cookies --domains 'example.com,login.example.com'
```

`--target-url` is a case-sensitive URL substring. If it matches zero or multiple page targets, inspect `list` and use a more specific substring.

## Interaction workflow

1. Run `list` and identify the exact page target.
2. Run `body` to inspect the title, URL, and visible text. For complex controls, use `eval` to inspect labels, ARIA attributes, roles, inputs, and buttons without reading secret-field values.
3. Use `navigate`, `new`, `click-text`, or `type` as needed.
4. Wait for async rendering when necessary, then run `body` or a focused `eval` to verify.
5. For controls not covered by the helper:
   - Evaluate the target element's bounding rectangle.
   - Send `Input.dispatchMouseEvent` for `mousePressed` and `mouseReleased` at its center.
   - Focus text fields and use `Input.insertText` or key events.
   - For dropdowns, click the combobox, inspect `[role=option]`, then click the exact option.
6. Keep the user informed at meaningful checkpoints, especially when authentication or manual secret entry is required.

## Tabs and screenshots

- Create a new tab with `new` when testing a path should not disrupt the user's current page.
- Screenshots must be written to the scratchpad, not the workspace. Inspect them with `view_images` if needed.
- Before taking a screenshot, ensure no password, verification code, payment credential, private key, or token is visible.

## Cookies and site data

- `clear-cookies --domains` deletes only matching-domain cookies and never prints cookie names or values.
- Domain matching includes subdomains of each requested domain.
- Cookie deletion does not clear local storage, IndexedDB, caches, or service workers.
- To clear all storage for an origin, use CDP `Storage.clearDataForOrigin` only after explaining that it can reset an unfinished flow. Keep unrelated origins untouched.
- Clearing local browser data does not remove server-side sessions, fraud flags, account state, or remote data.

## Troubleshooting

- If a click does nothing, inspect whether the text belongs to a wrapper or shadow/custom element. Use the smallest visible interactive element and real mouse events.
- If typed text appears but the app does not react, focus the field and use `Input.insertText`; follow with appropriate key events or blur.
- If a SPA is still loading, wait and inspect again rather than repeating a submission.
- If `/json/list` shows a changed target ID after authentication, rediscover the target instead of reusing an old WebSocket URL.
- If authentication redirects unexpectedly, inspect the active account indicator and URL before continuing.

---
name: chrome-cdp-control
display-name: Chrome CDP Control
description: Connect to and operate a user-visible Chrome session through CDP
  for browser inspection, navigation, and interaction.
---

# Chrome CDP Control

Use Chrome DevTools Protocol (CDP) when the user asks you to inspect or operate their Chrome browser. Take initiative: inspect the live page, perform requested browser actions, verify the result, and report concise outcomes.

## Operating principles

- Treat the browser as user-controlled state. Never close, replace, or relaunch an existing browser without explaining the impact and obtaining approval when data could be lost.
- Prefer a separately launched CDP profile. Modern Chrome may ignore remote-debugging flags for its default profile.
- Never read, print, screenshot, or retain passwords, verification codes, card numbers, security codes, session tokens, cookie values, or other secrets. Leave secret-entry steps to the user.
- Inspect before acting. After navigation, clicks, form submissions, or permission changes, inspect again and verify the resulting URL, visible notice, or data row.
- Prepare consequential changes, summarize them, and pause before the final irreversible or high-impact action unless the user has explicitly authorized that exact action.
- Use exact URLs, selectors, accessible names, and visible text. Do not guess when multiple targets match.
- Prefer normal mouse and keyboard CDP events over calling `element.click()` or assigning `input.value`; framework-controlled pages often ignore synthetic DOM changes.

## Connect or launch

1. Test the standard endpoint:

   ```bash
   curl -fsS http://127.0.0.1:9222/json/version
   ```

2. If unavailable, inspect running browser processes and listening ports. A Chrome process without a remote-debugging endpoint cannot be attached in place.
3. If the user wants you to launch a controllable instance, call `get_scratchpad_folder`, create a profile folder there, and launch:

   ```bash
   open -na "Google Chrome" --args \
     --remote-debugging-address=127.0.0.1 \
     --remote-debugging-port=9222 \
     --user-data-dir="<scratchpad>/chrome-cdp-profile" \
     "<requested-url>"
   ```

4. Explain that a scratchpad profile persists across immediate restarts only while that scratchpad exists. For durable use, offer a dedicated persistent profile and obtain permission before writing outside the workspace.
5. Never expose the CDP port beyond loopback.

## Use the bundled helper

Resolve `scripts/cdp.mjs` relative to this `SKILL.md`. It uses Node's built-in WebSocket and has no third-party dependencies.

```bash
node <skill-folder>/scripts/cdp.mjs list
node <skill-folder>/scripts/cdp.mjs body --target-url 'example.com/path'
node <skill-folder>/scripts/cdp.mjs navigate --target-url 'example.com' --url 'https://example.com/new'
node <skill-folder>/scripts/cdp.mjs new --url 'https://example.com/'
node <skill-folder>/scripts/cdp.mjs click-text --target-url 'example.com' --text 'Continue'
node <skill-folder>/scripts/cdp.mjs type --target-url 'example.com' --selector 'input[name=email]' --text 'person@example.com'
node <skill-folder>/scripts/cdp.mjs eval --target-url 'example.com' --expression 'document.title'
node <skill-folder>/scripts/cdp.mjs screenshot --target-url 'example.com' --output '/absolute/scratchpad/page.png'
node <skill-folder>/scripts/cdp.mjs clear-cookies --domains 'example.com,login.example.com'
```

`--target-url` is a case-sensitive URL substring. If it matches zero or multiple page targets, inspect `list` and use a more specific substring.

## Interaction workflow

1. Run `list` and identify the exact page target.
2. Run `body` to inspect the title, URL, and visible text. For complex controls, use `eval` to inspect labels, ARIA attributes, roles, inputs, and buttons without reading secret-field values.
3. Use `navigate`, `new`, `click-text`, or `type` as needed.
4. Wait for async rendering when necessary, then run `body` or a focused `eval` to verify.
5. For controls not covered by the helper:
   - Evaluate the target element's bounding rectangle.
   - Send `Input.dispatchMouseEvent` for `mousePressed` and `mouseReleased` at its center.
   - Focus text fields and use `Input.insertText` or key events.
   - For dropdowns, click the combobox, inspect `[role=option]`, then click the exact option.
6. Keep the user informed at meaningful checkpoints, especially when authentication or manual secret entry is required.

## Tabs and screenshots

- Create a new tab with `new` when testing a path should not disrupt the user's current page.
- Screenshots must be written to the scratchpad, not the workspace. Inspect them with `view_images` if needed.
- Before taking a screenshot, ensure no password, verification code, payment credential, private key, or token is visible.

## Cookies and site data

- `clear-cookies --domains` deletes only matching-domain cookies and never prints cookie names or values.
- Domain matching includes subdomains of each requested domain.
- Cookie deletion does not clear local storage, IndexedDB, caches, or service workers.
- To clear all storage for an origin, use CDP `Storage.clearDataForOrigin` only after explaining that it can reset an unfinished flow. Keep unrelated origins untouched.
- Clearing local browser data does not remove server-side sessions, fraud flags, account state, or remote data.

## Troubleshooting

- If a click does nothing, inspect whether the text belongs to a wrapper or shadow/custom element. Use the smallest visible interactive element and real mouse events.
- If typed text appears but the app does not react, focus the field and use `Input.insertText`; follow with appropriate key events or blur.
- If a SPA is still loading, wait and inspect again rather than repeating a submission.
- If `/json/list` shows a changed target ID after authentication, rediscover the target instead of reusing an old WebSocket URL.
- If authentication redirects unexpectedly, inspect the active account indicator and URL before continuing.