# Chrome Devtools Optimizer

> 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.

- Skill: `tomevault-io/chrome-devtools-optimizer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/chrome-devtools-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/chrome-devtools-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/chrome-devtools-optimizer

---


# 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:

```bash
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:

```json
{
  "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:

```json
// 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:**
```bash
# Download from https://www.google.com/chrome/
# Or use Homebrew
brew install --cask google-chrome
```

**Linux/WSL2:**
```bash
# 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:**
```bash
google-chrome --version
```

### Step 2: Start Chrome with Remote Debugging

**Quick command:**
```bash
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:**
```bash
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:**
```bash
chrome-debug  # Start Chrome once per session
```

**Verify Chrome is running:**
```bash
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):

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

**Automated setup (Linux/macOS):**
```bash
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:**
```bash
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:**
```bash
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
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):**
   ```bash
   chrome-debug
   ```

2. **Verify Gemini is configured:**
   ```bash
   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:**
```bash
node scripts/process-screenshot.js "data:image/png;base64,iVBORw0KG..."
```

**From file:**
```bash
node scripts/process-screenshot.js /tmp/screenshot.png
```

**With custom prompt:**
```bash
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.

```bash
node scripts/setup.js
```

### test-connection.js
Verify Gemini API is configured and working.

```bash
node scripts/test-connection.js
```

### process-screenshot.js
Process screenshots through Gemini Flash for text summaries.

```bash
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
bash scripts/wsl2-setup.sh
```

## Troubleshooting

### Issue: "Cannot connect to Chrome"
**Solution:**
```bash
# 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:**
```bash
# Test configuration
node scripts/test-connection.js

# Reconfigure if needed
node scripts/setup.js
```

### Issue: "Config not found"
**Solution:**
Run setup to create config:
```bash
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:
```bash
# Don't send screenshot directly to Claude
# Instead:
node scripts/process-screenshot.js <screenshot> "describe the page"
```

### Issue: Chrome logs show errors
**Solution:**
```bash
# 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**
   ```bash
   chrome-debug
   ```

2. **Verify Gemini setup before visual work**
   ```bash
   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](https://github.com/diegocconsolini/claudeskillcollection) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-04 -->