chrome-devtools-optimizer

name	chrome-devtools-optimizer
description	Reduce token consumption by 70-80% when using Chrome DevTools MCP through smart snapshot strategies and optional Gemini Flash vision processing. Includes decision trees, pattern guides, and automated optimization workflows. Use when this capability is needed.
metadata	{"author":"diegocconsolini"}

Chrome DevTools Optimizer

Reduce token consumption by 70-80% when using Chrome DevTools MCP

When to Use This Skill

Use this skill when:

• User is working with Chrome DevTools MCP for web testing
• User needs to take screenshots or analyze web pages
• User wants to automate form filling or page interactions
• User is doing web debugging or visual regression testing
• User mentions high token costs with Chrome DevTools
• User needs to inspect page structure or elements

Core Principle

Default to text over images. Screenshots cost 1,600+ tokens. Text snapshots cost 300-500 tokens.

Decision Tree

When the user needs page information:

1. Need page structure/elements? → Use take_snapshot (text, ~500 tokens)
2. Need visual appearance? → Screenshot → Gemini Flash → text summary (~300 tokens)
3. Need specific element only? → Use take_screenshot with uid parameter (smaller image)
4. Need complex visual reasoning? → Direct screenshot to Claude (last resort, ~1,600 tokens)

🚨 IMPORTANT: Setup Required

This skill requires three components to work:

1. Chrome with Remote Debugging

2. Chrome DevTools MCP Server

3. Gemini API Key (Optional but Highly Recommended)

See the Setup section below for detailed instructions.

Optimization Rules

Rule 1: Snapshot First

ALWAYS try take_snapshot before take_screenshot. The accessibility tree provides:

• All interactive elements with unique IDs
• Text content
• Element hierarchy
• Form field states

GOOD: take_snapshot → analyze structure → targeted action
BAD:  take_screenshot → analyze image → action

Rule 2: Gemini Flash for Visual Analysis

When visual analysis IS needed, use the processor script:

node scripts/process-screenshot.js <base64_image_or_file>

This returns a text summary (~200-500 tokens) instead of embedding the image (~1,600 tokens).

Rule 3: Element-Targeted Screenshots

If you must screenshot, capture only what's needed:

GOOD: take_screenshot with uid="element-id" (element only)
BAD:  take_screenshot full page then describe one button

Rule 4: Compress Full-Page Screenshots

When full-page screenshot is unavoidable:

{
  "format": "jpeg",
  "quality": 50
}

This reduces image size by 30-40%.

Rule 5: Don't Re-Snapshot Unchanged Pages

If the page hasn't changed since last snapshot, reference the previous one:

"Based on the previous snapshot, the login form has fields for..."

Rule 6: Filter Network/Console Output

Use filters to reduce output size:

// Network - filter by type
{ "resourceTypes": ["Document", "XHR", "Fetch"] }

// Console - filter by type
{ "types": ["error", "warning"] }

// Both - use pagination
{ "pageSize": 20 }

Rule 7: Batch Form Operations

Use fill_form instead of multiple fill calls:

GOOD: fill_form with all fields at once
BAD:  fill("email", "...") → fill("password", "...") → fill("name", "...")

Token Cost Reference

Operation	Tokens	When to Use
take_snapshot	300-1,500	Structure, elements, text content
Screenshot → Gemini	200-500	Visual appearance, layout, colors
Element screenshot	400-800	Single component analysis
Full screenshot (JPEG 50%)	800-1,200	Complex visual debugging
Full screenshot (PNG)	1,600-4,000	Last resort, precise pixels needed

Setup Instructions

Step 1: Install Chrome (if not already installed)

macOS:

# Download from https://www.google.com/chrome/
# Or use Homebrew
brew install --cask google-chrome

Linux/WSL2:

# Add Google Chrome repository
wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list'

# Install Chrome
sudo apt update
sudo apt install -y google-chrome-stable

Verify installation:

google-chrome --version

Step 2: Start Chrome with Remote Debugging

Quick command:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile --no-sandbox > /tmp/chrome.log 2>&1 &

WSL2 users - Add this alias to ~/.bashrc for easy startup:

alias chrome-debug='mkdir -p /tmp/chrome-debug-profile && google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile --no-sandbox > /tmp/chrome.log 2>&1 &'

Then reload: source ~/.bashrc

Daily usage:

chrome-debug  # Start Chrome once per session

Verify Chrome is running:

curl http://localhost:9222/json

Should return JSON with browser info.

Step 3: Configure Chrome DevTools MCP Server

Add to your Claude Desktop configuration (~/.claude/settings.json or equivalent):

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browserUrl",
        "http://localhost:9222"
      ],
      "env": {}
    }
  }
}

Automated setup (Linux/macOS):

jq '.mcpServers["chrome-devtools"] = {
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://localhost:9222"],
  "env": {}
}' ~/.claude/settings.json > /tmp/settings.tmp && mv /tmp/settings.tmp ~/.claude/settings.json

Important: Restart Claude Desktop after adding the MCP server.

Step 4: Configure Gemini API (Optional but Recommended)

Why Gemini?

• Without Gemini: Screenshot → Claude = ~1,600 tokens
• With Gemini: Screenshot → Gemini → text summary = ~300 tokens
• You lose 50% of token savings without Gemini

Get a free API key:

1. Visit: https://aistudio.google.com/apikey
2. Sign in with Google account
3. Create API key

Free tier limits:

• 15 requests/minute
• 1 million tokens/day
• More than enough for typical use

Run the setup script:

node scripts/setup.js

This will:

1. Prompt for your Gemini API key
2. Save to ~/.config/chrome-devtools-optimizer/config.json
3. Auto-test the connection

Verify setup:

node scripts/test-connection.js

You should see:

✅ Config loaded
✅ Gemini API connected
✅ Model: gemini-1.5-flash-latest
✅ Ready to process screenshots!

Step 5: WSL2-Specific Setup (Optional)

If you're on Windows using WSL2, run the automated setup script:

bash scripts/wsl2-setup.sh

This script will:

• Install Chrome if missing
• Create chrome-debug alias
• Configure Chrome DevTools MCP server
• Set up Gemini API (prompts for key)
• Verify all connections

Usage

Basic Workflow

1. Start Chrome (once per session):

   chrome-debug
   

2. Verify Gemini is configured:

   node scripts/test-connection.js
   

3. Use Chrome DevTools MCP tools with optimization:

   • For structure: take_snapshot
   • For visuals: take_screenshot → process with Gemini
   • For forms: fill_form (batch operation)
   • For verification: evaluate_script (lightweight)

Process Screenshots with Gemini

From base64 data:

node scripts/process-screenshot.js "data:image/png;base64,iVBORw0KG..."

From file:

node scripts/process-screenshot.js /tmp/screenshot.png

With custom prompt:

node scripts/process-screenshot.js /tmp/screenshot.png "find all buttons"

Output example:

Analysis complete (250 tokens):

The page shows a login form with:
- Email input field (top)
- Password input field (middle)
- "Remember me" checkbox
- Blue "Sign In" button (prominent)
- "Forgot password?" link (bottom right)

Example Workflows

1. Verify Login Page (Optimized)

1. navigate_page to login URL
2. take_snapshot → confirm form elements present
3. fill_form with credentials
4. click submit button by uid
5. take_snapshot → confirm success/error state

Total: ~1,500 tokens (vs ~6,400 with screenshots)

2. Debug Visual Layout Issue

1. take_snapshot → identify element uid
2. take_screenshot with uid → Gemini Flash
3. Gemini returns: "Button is misaligned, positioned 20px left of container"
4. Fix CSS based on text description

Total: ~800 tokens (vs ~3,200 with full screenshots)

3. Check Responsive Design

1. resize_page to mobile dimensions
2. take_snapshot → verify elements reflow
3. Only if visual issues: screenshot → Gemini for layout analysis

Total: ~600-1,000 tokens (vs ~3,200 minimum with screenshots)

4. Automated Form Testing

1. navigate_page to form URL
2. take_snapshot → get all form field UIDs
3. fill_form → all fields at once
4. click submit by uid
5. evaluate_script → check URL/DOM state (confirm redirect)
6. take_snapshot → verify success page

Total: ~1,000 tokens (vs ~6,000 with screenshots)

Token Savings Comparison

Traditional Approach (Screenshots)

navigate → screenshot (1,600) → fill form → screenshot (1,600) →
click → screenshot (1,600) → verify → screenshot (1,600)
Total: ~6,400 tokens

Optimized Approach (Snapshots + Gemini)

navigate → snapshot (500) → fill form → snapshot (500) →
click → evaluate (100) → verify → snapshot (500)
Total: ~1,600 tokens

Savings: 75% reduction

Available Tools (Quick Reference)

See references/tool-reference.md for complete documentation of all 26 Chrome DevTools MCP tools.

Most commonly used:

• take_snapshot - Get accessibility tree (text)
• take_screenshot - Capture screenshot (visual)
• navigate_page - Navigate to URL
• click - Click element by UID
• fill_form - Fill multiple form fields at once
• evaluate_script - Run JavaScript in page context
• list_console_messages - Get console output
• list_network_requests - Get network activity

Anti-Patterns (Avoid These)

❌ Screenshot after every action ✅ Use snapshot or verify with evaluate_script

❌ Multiple fill() calls for one form ✅ Use single fill_form() with all fields

❌ Unfiltered console/network output ✅ Always use types/resourceTypes + pageSize

❌ Full page screenshot for one element ✅ Use uid parameter to capture element only

❌ Re-snapshot unchanged pages ✅ Reference previous snapshot in conversation

Pattern Guides

The patterns/ directory contains detailed guides for common workflows:

• forms.md - Form filling and validation
• navigation.md - Page navigation and routing
• debugging.md - Console logs and network requests
• visual-check.md - Visual regression testing

Scripts Reference

setup.js

Configure Gemini API key and test connection.

node scripts/setup.js

test-connection.js

Verify Gemini API is configured and working.

node scripts/test-connection.js

process-screenshot.js

Process screenshots through Gemini Flash for text summaries.

node scripts/process-screenshot.js <image_path_or_base64> [prompt]

wsl2-setup.sh

Automated setup for WSL2 users (installs Chrome, configures MCP, sets up Gemini).

bash scripts/wsl2-setup.sh

Troubleshooting

Issue: "Cannot connect to Chrome"

Solution:

# Check if Chrome is running
ps aux | grep chrome

# Check port 9222
curl http://localhost:9222/json

# Restart Chrome
pkill chrome
chrome-debug

Issue: "Gemini API error"

Solution:

# Test configuration
node scripts/test-connection.js

# Reconfigure if needed
node scripts/setup.js

Issue: "Config not found"

Solution: Run setup to create config:

node scripts/setup.js

Config is stored at: ~/.config/chrome-devtools-optimizer/config.json

Issue: "Screenshots still high tokens"

Solution: Make sure you're processing through Gemini:

# Don't send screenshot directly to Claude
# Instead:
node scripts/process-screenshot.js <screenshot> "describe the page"

Issue: Chrome logs show errors

Solution:

# View Chrome logs
cat /tmp/chrome.log

# Common fix: Clear profile
rm -rf /tmp/chrome-debug-profile
chrome-debug

Performance Metrics

Real-World Token Savings

Login flow:

• Traditional: 6,400 tokens
• Optimized: 1,600 tokens
• Savings: 75%

Form testing:

• Traditional: 8,000 tokens
• Optimized: 2,000 tokens
• Savings: 75%

Visual debugging:

• Traditional: 3,200 tokens
• Optimized: 800 tokens
• Savings: 75%

Responsive design check:

• Traditional: 6,400 tokens
• Optimized: 1,000 tokens
• Savings: 84%

Gemini API Usage

• Average request: 200-500 input tokens (screenshot)
• Average response: 100-300 output tokens (description)
• Total: ~300-800 tokens per screenshot analysis
• vs Claude direct: 1,600-4,000 tokens

Limitations

1. Requires external services:

   • Chrome with remote debugging
   • Chrome DevTools MCP server
   • Gemini API (optional but recommended)

2. Text-first approach:

   • May miss subtle visual issues
   • Complex visual reasoning requires manual review

3. Setup complexity:

   • Multiple components to configure
   • WSL2 requires additional steps

4. Gemini API limits:

   • Free tier: 15 req/min, 1M tokens/day
   • Need to handle rate limits

Best Practices

1. Always start Chrome before using MCP tools

   chrome-debug
   

2. Verify Gemini setup before visual work

   node scripts/test-connection.js
   

3. Use snapshots for structure, Gemini for visuals

   • Default to take_snapshot
   • Use Gemini only when visual analysis needed

4. Batch operations when possible

   • fill_form instead of multiple fill calls
   • Filter network/console output

5. Reference previous snapshots

   • Don't re-snapshot unchanged pages
   • Use conversation context

References

• README.md - Complete setup and usage guide
• references/tool-reference.md - All 26 Chrome DevTools MCP tools
• references/token-costs.md - Detailed cost analysis
• references/decision-tree.md - Flowchart decision logic
• patterns/ - Workflow patterns for common tasks

Support

For issues or questions:

1. Check troubleshooting section above
2. Review README.md for detailed docs
3. Test connection with scripts/test-connection.js
4. Verify Chrome is running on port 9222

License

MIT License - See LICENSE file for details

Credits

• Built for Claude Desktop with Chrome DevTools MCP
• Uses Gemini Flash 1.5 for visual analysis
• Token optimization research and benchmarking

---

Version: 1.0.1 Last Updated: 2025-12-25 Status: Production Ready

---

Source: diegocconsolini/claudeskillcollection — distributed by TomeVault.