chrome-devtools-mcp-cleanup
/chrome-devtools-mcp-cleanup
Diagnose + clean up the recurring chrome-devtools-mcp wedge — multiple stale `chrome-devtools-mcp@latest` parent processes colliding on the shared `~/.cache/chrome-devtools-mcp/chrome-profile` directory. Use when state-changing tools (new_page, navigate_page, select_page, take_snapshot) error with "The browser is already running for /Users/.../chrome-profile. Use --isolated to run multiple browser instances." while `list_pages` still works. Card #223 (CvjIx0qZ).
- Author
- msapps-mobile ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Diagnose + clean up the recurring chrome-devtools-mcp wedge — multiple stale `chrome-devtools-mcp@latest` parent processes colliding on the shared `~/.cache/chrome-devtools-mcp/chrome-profile` directory. Use when state-changing tools (new_page, navigate_page, select_page, take_snapshot) error with "The browser is already running for /Users/.../chrome-profile. Use --isolated to run multiple browser instances." while `list_pages` still works. Card #223 (CvjIx0qZ).
Original author description
Diagnose + clean up the recurring chrome-devtools-mcp wedge — multiple stale `chrome-devtools-mcp@latest` parent processes colliding on the shared `~/.cache/chrome-devtools-mcp/chrome-profile` directory. Use when state-changing tools (new_page, navigate_page, select_page, take_snapshot) error with "The browser is already running for /Users/.../chrome-profile. Use --isolated to run multiple browser instances." while `list_pages` still works. Card #223 (CvjIx0qZ).
How it works
- Symptom
- When to invoke
- Diagnosis
- Cleanup — only when ≥2 parents found
- Verify
- After cleanup — confirm the permanent fix is in place
- Why we chose --isolated over per-PID userDataDir
- Don't
- Refs
SKILL.md preview
---
name: chrome-devtools-mcp-cleanup
description: Diagnose + clean up the recurring chrome-devtools-mcp wedge — multiple stale `chrome-devtools-mcp@latest` parent processes colliding on the shared `~/.cache/chrome-devtools-mcp/chrome-profile` directory. Use when state-changing tools (new_page, navigate_page, select_page, take_snapshot) error with "The browser is already running for /Users/.../chrome-profile. Use --isolated to run multiple browser instances." while `list_pages` still works. Card #223 (CvjIx0qZ).
---
# chrome-devtools-mcp wedge cleanup
> **Different server from Claude-in-Chrome.** This is for `chrome-devtools-mcp`
> (DevTools Protocol; tools `new_page`, `take_snapshot`, `navigate_page`,
> `evaluate_script`, `lighthouse_audit`). Not the Claude-in-Chrome extension
> (`mcp__Claude_in_Chrome__*`). Both can be down independently — see the
> sibling `/fix-chrome-connection` skill for the extension.
## Symptom
`list_pages` works (read-only) but every state-changing tool errors with:
> The browser is already running for /Users/michalshatz/.cache/chrome-devtools-mcp/chrome-profile. Use --isolated to run multiple browser instances.
Root cause: ≥2 concurrent `chrome-devtools-mcp@latest` parents, each spawning Chromium pinned to the shared profile dir. The Chrome that the *current* MCP tries to start collides with one started by a stale MCP parent from an earlier session.
The permanent fix landed in `~/.claude.json` (per-user MCP config) — the chrome-devtools server now passes `--isolated` so each session gets its own profile. This skill is the one-time cleanup for hosts where stale parents accumulated *before* that fix.
## When to invoke
Use deliberately — **NOT** from a scheduled-task runner. Killing processes on a shared Mac is destructive; the user must opt in.
Trigger phrases: "fix chrome-devtools-mcp", "chrome-devtools wedged", "browser is already running for chrome-profile", "stale chrome-devtools parents", "card #223 cleanup".
## Diagnosis
```bash
# 1. List all chrome-devtools-mcp parent processes
ps -eo pid,etime,command | awk '/chrome-devtools-mcp@latest/ && !/awk/'
# 2. List Chromium children spawned by them (pinned to chrome-profile)
ps -eo pid,ppid,etime,command \
| awk '/chrome-devtools-mcp\/chrome-profile/ && !/awk/'
# 3. Show the lock file holder
ls -la ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock 2>/dev/null
```
If only ONE parent shows up: the wedge is unrelated to staleness — verify the new `--isolated` flag is in `~/.claude.json`:
```bash
grep -A6 '"chrome-devtools"' ~/.claude.json | head -10
```
Should show `"--isolated"` in the args array. If missing, add it (close every Claude Code window first; the change picks up at next launch).
## Cleanup — only when ≥2 parents found
```bash
# Identify orphaned parents — those whose ppid is 1 (init) or whose parent
# is a long-dead Claude session (stat of /proc/<ppid> equivalent on macOS:
# we just check if the ppid resolves to a live `claude` process).
ps -eo pid,ppid,etime,command | awk '/chrome-devtools-mcp@latest/ && !/awk/' \
| while read pid ppid etime cmd; do
parent_alive=$(ps -p "$ppid" -o command= 2>/dev/null | grep -c claude || true)
printf "%s\tppid=%s\tparent_alive=%s\tetime=%s\n" "$pid" "$ppid" "$parent_alive" "$etime"
done
```
Identify the parent **owned by the current session** (its ppid corresponds to your active Claude Code process — `pgrep -f "claude.*-l" | head` or check the session you're running in). Keep that one; kill the others:
```bash
# Pseudocode — REVIEW each PID before running. Replace <ORPHAN_PID> with the
# pid of a parent whose own parent is dead / non-Claude.
kill -TERM <ORPHAN_PID> # graceful
sleep 2
kill -KILL <ORPHAN_PID> 2>/dev/null # if it's still around
# Then sweep their Chromium children:
pkill -f 'chrome-devtools-mcp/chrome-profile' || true
```
Don't `pkill -f chrome-devtools-mcp@latest` blindly — that nukes your active session's parent too.
## Verify
```bash
# 1. Only ONE parent should remain (the active session's).
ps -eo pid,ppid,etime,command | awk '/chrome-devtools-mcp@latest/ && !/awk/' | wc -l
# 2. Lock file should be either gone or owned by the surviving parent.
ls -la ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock 2>/dev/null
# 3. From your active Claude Code session, smoke-test:
# list_pages → should still work
# new_page("https://example.com") → should succeed without "browser already running"
# take_snapshot → should succeed
```
## After cleanup — confirm the permanent fix is in place
```bash
grep -A6 '"chrome-devtools"' ~/.claude.json | head -10
```
You should see:
```json
"chrome-devtools": {
"type": "stdio",
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--isolated"
],
"env": {}
}
```
With `--isolated` in place, future sessions will each get their own Chromium profile directory under a tmp path — no more SingletonLock collisions, even if multiple Claude Code windows are open.
## Why we chose --isolated over per-PID userDataDir
`--isolated` is the upstream-blessed flag and is one line of config. Per-PID (`--userDataDir /tmp/chrome-devtools-mcp-${PID}`) requires shell expansion that `claude mcp` doesn't do, and accumulates orphan profile dirs that need their own cleanup pass. The `--isolated` flag handles cleanup automatically when the parent exits.
## Don't
- Don't run this cleanup from a scheduled-task runner. Process-killing is destructive on a shared Mac; the user must opt in.
- Don't `rm -rf ~/.cache/chrome-devtools-mcp/chrome-profile/` while a session is active — corrupts the running Chromium's state.
- Don't `pkill -f chrome-devtools-mcp@latest` blindly — kills your active session's parent too.
## Refs
- Card #223: https://trello.com/c/CvjIx0qZ
- Sibling skill (Claude-in-Chrome extension): `/fix-chrome-connection`
- Permanent fix landed: `~/.claude.json` chrome-devtools args now `["chrome-devtools-mcp@latest", "--isolated"]` (2026-05-06)
Versions
The database has no other skills named chrome-devtools-mcp-cleanup.
Database snapshot: 13.11.2026 · package version 6965f60099ed (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100browser-testing-with-devtools
Real browser testing via Chrome DevTools MCP — DOM inspection, console analysis, network requests, performance profiling. Use when debugging anything browser-rendered. Requires the chrome-devtools MCP server. - 100browser-testing-with-devtools
Real browser testing via Chrome DevTools MCP — DOM inspection, console analysis, network requests, performance profiling. Use when debugging anything browser-rendered. Requires the chrome-devtools MCP server. - 100chrome-devtools
Uses Chrome DevTools via MCP for efficient debugging, troubleshooting and browser automation. Use when debugging web pages, automating browser interactions, analyzing performance, or inspecting network requests. This skill does not apply to `--slim` mode (MCP configuration). - 100chrome-devtools-cli
Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI. - 100chrome-devtools-cli
Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI. - 95chrome-devtools-cli
Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI.