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.
license	MIT
compatibility	claude-desktop
metadata	{"version":"1.0.1","author":"Diego Consolini","category":"productivity","requires-api":"gemini-flash (optional)","requires-mcp":"chrome-devtools","runtime":"node.js"}

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