Chrome DevTools Protocol Skill

Purpose

Provides Chrome DevTools Protocol (CDP) access through a local Docker container, enabling browser debugging, network inspection, performance profiling, and DOM manipulation without remote MCP dependencies.

Capabilities

• Page Control: Navigate, reload, screenshot
• JavaScript Execution: Evaluate scripts in browser context
• Network Monitoring: Capture requests, responses, timing
• DOM Inspection: Query and manipulate DOM elements
• Performance: Profiling, metrics, Core Web Vitals
• Console: Capture console logs and errors

Requirements

Docker

• Docker Desktop installed and running
• agent-network Docker network created
• Chrome DevTools container running

Ruby

• Ruby ≥2.7
• Gems: websocket-client-simple, json, net-http

Setup

# Start Chrome DevTools container
cd ~/.claude/skills/chrome-devtools/docker
docker-compose up -d

# Verify container is running
docker ps | grep chrome-devtools-server

# Check CDP endpoint
curl http://localhost:9222/json/version

Usage

Page Navigation

# Navigate to URL
~/.claude/skills/chrome-devtools/scripts/navigate.rb "https://example.com"

JavaScript Evaluation

# Execute JavaScript
~/.claude/skills/chrome-devtools/scripts/evaluate.rb "document.title"

# Get complex data
~/.claude/skills/chrome-devtools/scripts/evaluate.rb "Array.from(document.querySelectorAll('a')).map(a => a.href)"

Network Monitoring

# Capture network traffic
~/.claude/skills/chrome-devtools/scripts/network_capture.rb "https://example.com" 5

# Arguments: URL, duration (seconds)

Screenshots

# Capture screenshot
~/.claude/skills/chrome-devtools/scripts/screenshot.rb /tmp/screenshot.png

# JPEG with quality
~/.claude/skills/chrome-devtools/scripts/screenshot.rb /tmp/screenshot.jpg --format jpeg --quality 80

Console Logs

# Monitor console output
~/.claude/skills/chrome-devtools/scripts/console_log.rb "https://example.com" 10

# Arguments: URL, duration (seconds)

Docker Management

Start Container

~/.claude/skills/chrome-devtools/scripts/start.sh

Stop Container

~/.claude/skills/chrome-devtools/scripts/stop.sh

Restart Container

~/.claude/skills/chrome-devtools/scripts/restart.sh

Check Status

~/.claude/skills/chrome-devtools/scripts/status.sh

VNC Access (Visual Debugging)

# Get VNC connection details
~/.claude/skills/chrome-devtools/scripts/vnc_url.sh

# Connect with VNC viewer to: vnc://localhost:5900
# Password: secret

Troubleshooting

Container won't start

Symptom: docker-compose up -d fails

Solutions:

1. Check Docker Desktop is running
2. Verify SHM size setting (Chrome needs shared memory)
3. Check logs: docker-compose logs
4. Try with increased shm_size in docker-compose.yml

CDP connection failed

Symptom: Can't connect to WebSocket

Solutions:

1. Verify container is running: docker ps | grep chrome
2. Check CDP endpoint: curl http://localhost:9222/json
3. Verify port not in use: lsof -i :9222
4. Check container logs: docker logs chrome-devtools-server

Browser crashed

Symptom: CDP commands fail with "Target closed"

Solutions:

1. Restart container: docker-compose restart
2. Check memory limits (Chrome needs ≥1GB)
3. Review crash logs: docker logs chrome-devtools-server

VNC not working

Symptom: Can't connect to VNC

Solutions:

1. Verify VNC port exposed: docker port chrome-devtools-server
2. Check DEFAULT_HEADLESS=false in environment
3. Try different VNC client
4. Restart container: docker-compose restart

Performance Notes

• Container startup: ~15-20 seconds
• CDP response time: <200ms typical
• Memory usage: ~800MB-1.5GB
• Supports up to 5 concurrent sessions (configurable)

Advanced Configuration

Headless vs Headed Mode

Edit docker-compose.yml environment:

environment:
  - DEFAULT_HEADLESS=false  # Enable headed mode for VNC

Session Limits

environment:
  - MAX_CONCURRENT_SESSIONS=10

Preboot Optimization

environment:
  - PREBOOT_CHROME=true  # Faster first connection

CDP Domains Reference

Commonly Used Domains

• Page: Navigation, lifecycle, resources
• Runtime: JavaScript evaluation, console
• Network: Request/response monitoring
• DOM: Document structure, queries
• Performance: Metrics, profiling
• Debugger: Breakpoints, stepping
• Profiler: CPU/Memory profiling

Event Subscription Example

require_relative 'cdp_client'

client = CDPClient.new
client.network_enable

client.on_event('Network.requestWillBeSent') do |params|
  puts "Request: #{params['request']['url']}"
end

client.page_navigate('https://example.com')
sleep 5 # Capture traffic

See Also

• Playwright skill for browser automation
• CDP Protocol documentation: https://chromedevtools.github.io/devtools-protocol/
• Original research: ~/.claude/claudedocs/research_mcp_to_agent_skill_conversion_20251116.md