| name | agent-cdp |
| description | Chrome DevTools Protocol CLI workflow for runtime, console, network, trace, memory, and JavaScript CPU profiling analysis. Use when Codex needs to inspect debuggable Chrome/Chromium tabs, Node processes started with --inspect, React Native/Metro/Hermes targets, or to combine agent-device UI driving with CDP evidence for performance, heat, re-render, network, memory, or runtime-state diagnosis. |
agent-cdp
Use agent-cdp for evidence-backed runtime diagnostics through Chrome DevTools Protocol. Pair it with agent-device when a mobile UI interaction must be driven on a simulator/device while CDP records what the JS runtime, network, or profiler did.
First Step
Load the bundled upstream guide before non-trivial use:
agent-cdp skills get core
If that command cannot read bundled skills, fall back to the installed package files:
AGENT_CDP_ROOT="$(npm root -g)/agent-cdp"
sed -n '1,220p' "$AGENT_CDP_ROOT/skills/core.md"
Core Workflow
- Start/check the daemon:
agent-cdp start
agent-cdp status
- Find and select a target:
agent-cdp target list
agent-cdp target list --url http://127.0.0.1:8081
agent-cdp target list --url http://127.0.0.1:9229
agent-cdp target select <target-id>
Default target scanning checks local Chrome, Node inspect, and Metro-style endpoints. If no React Native target appears, first verify Metro/dev-server reachability and whether the app is actually running in a debuggable dev mode.
React Native/Metro inspector endpoints may reject WebSocket connections with HTTP 401 unless the client sends an Origin such as http://localhost:8081. If target list sees a React Native target but target select fails with 401, verify the installed agent-cdp transport sends that Origin for targets whose kind is react-native or whose websocket URL contains /inspector/debug.
- Capture only the evidence needed:
agent-cdp console list --limit 50
agent-cdp runtime eval --expr "globalThis.location?.href ?? process.version" --json
agent-cdp network start --name repro
agent-cdp trace start
agent-cdp profile cpu start --name hot-path
- Reproduce the interaction. For mobile, drive the UI with
agent-device:
agent-device --session <name> snapshot
agent-device --session <name> press <target>
agent-device --session <name> wait 1000
- Stop and inspect:
agent-cdp network stop
agent-cdp network summary
agent-cdp network list --limit 20
agent-cdp trace stop
agent-cdp trace summary
agent-cdp profile cpu stop
agent-cdp profile cpu hotspots --limit 20
Common Tasks
For heat or high CPU, prefer a bounded CPU profile around the suspect interaction, then inspect hotspots and stacks. Also capture a process snapshot with ps so CDP findings can be correlated with OS-level CPU.
For slow or noisy network behavior, use network start, reproduce once, then inspect network summary, filtered network list, and only specific request/response headers or bodies. Avoid dumping auth headers or secrets.
For runtime state, use runtime eval with read-only expressions. Do not mutate app state from CDP unless the user explicitly asks for that side effect.
For trace-style UI performance, use trace start/stop around a short interaction and inspect summary/tracks/entries. Export the raw trace only when compact summaries are insufficient.
For memory leaks, take baseline/action/cleanup samples or snapshots, then use the built-in memory diff/leak commands. Keep heap artifacts out of commits unless explicitly requested.
Safety
Prefer short captures over long recordings. Stop active network, trace, CPU, or allocation sessions before finishing. Report when no CDP target is available instead of pretending profile evidence exists.
