Skip to content
Skills Library
Programming · Analysis

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

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

  1. Symptom
  2. When to invoke
  3. Diagnosis
  4. Cleanup — only when ≥2 parents found
  5. Verify
  6. After cleanup — confirm the permanent fix is in place
  7. Why we chose --isolated over per-PID userDataDir
  8. Don't
  9. Refs
Original SKILL.md headings · 128 lines, 747 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.