DEV Community

Ahab
Ahab

Posted on • Originally published at indieseek.co

Chrome DevTools MCP 1.7: debug memory leaks without reading raw heap snapshots

#javascript #webdev #ai #debugging

Chrome DevTools MCP 1.7: debug memory leaks without reading raw heap snapshots

Quick answer

Chrome DevTools MCP 1.7 gives AI coding agents a stronger memory-debugging path: a new object-details tool, native-context summaries and filters, an updated first-party memory-leak skill, and fixes that dispose heap-snapshot workers more reliably.

Do not hand a multi-gigabyte .heapsnapshot file to an LLM or ask it to guess from one snapshot. Use a three-snapshot protocol:

baseline -> repeat one suspected action 10 times -> target
         -> reverse/close the action -> final
Enter fullscreen mode Exit fullscreen mode

Start with summaries, compare retained growth, isolate one suspicious class or native context, inspect representative objects and retaining paths, then close every loaded snapshot. A fix passes only when the same replay no longer exceeds a predeclared growth budget.

Who this is for

This guide is for developers using Codex, Claude Code, Cursor, Copilot, Gemini CLI, or another MCP-capable agent to diagnose browser or Node.js memory growth. It assumes you can reproduce one bounded action such as opening and closing a modal, navigating between views, reconnecting a stream, or processing one job.

If you first need the browser access and safety model, use the general Chrome DevTools MCP workflow. This page goes deeper on heap evidence and cleanup; it is not another console/network debugging overview.

What changed in 1.7

The August 10 release adds get_heapsnapshot_object_details, which lets an agent request known metadata for a specific heap node instead of reading a raw snapshot. Snapshot summaries now expose native contexts and their sizes, while get_heapsnapshot_details can filter objects by native context.

The bundled memory-leak skill now routes analysis through native MCP tools: summaries, snapshot comparison, class nodes, retaining paths, dominators, object details, duplicate strings, and category filters. It explicitly recommends capturing baseline, target, and final snapshots, repeating the suspected action ten times, and closing loaded snapshots afterward.

Version 1.7 also fixes two diagnostic-server cleanup paths: workers are disposed when a context tears down and when loading a missing or invalid snapshot fails. Those fixes reduce the chance that the debugger's own worker growth is confused with application growth, but they do not remove your responsibility to close snapshots or verify the active CLI and daemon versions.

Evidence ladder

Stage Question Smallest useful tool output Stop condition
Summary Did retained memory grow? get_heapsnapshot_summary for three snapshots No repeatable growth after cleanup
Comparison Which classes accumulated? compare_heapsnapshots summary, then one class diff Growth is noise or expected cache
Context Which page/frame/context owns it? native-context sizes and filtered details Wrong context or cross-page contamination
Object What is one representative instance? class nodes plus get_heapsnapshot_object_details Object is expected and bounded
Retainer Why is it still reachable? retaining path, retainers, dominators, edges Chain does not reach application code
Fix proof Did the same replay improve? fresh three-snapshot run and budget result Budget still fails

Do not jump directly to a source-code change because a class name looks suspicious. Detached DOM nodes can be intentional caches; large strings can be generated output; framework objects may only be the visible end of a longer retaining chain.

A seven-step workflow

1. Pin the diagnostic boundary

Record the Chrome DevTools MCP version, agent client, browser or Node target, URL/process, commit, and exact reproduction. For this workflow, require 1.7.x on both sides when a daemon is used. The release adds a CLI warning for CLI/daemon version mismatch; treat that warning as a failed preflight.

Use a disposable profile or test account. Heap snapshots can contain application strings and object data, so keep snapshot paths out of source control and external prompts.

2. Define one action and a budget

Choose an action with a reverse operation:

open modal -> close modal
mount route -> navigate away
subscribe -> unsubscribe
start job -> finish and release job
Enter fullscreen mode Exit fullscreen mode

Declare the loop count and pass rule before looking at the result. Example: ten open/close cycles must leave no more than two extra modal roots, no growing listener set, and less than 5 MB of retained growth after cleanup. The numbers are workload-specific; the important part is fixing them before diagnosis.

3. Capture baseline, target, and final

Stabilize the app, then capture baseline. Repeat the action ten times and capture target. Perform the reverse action, leave the app idle long enough for normal cleanup, and capture final.

Keep the same build, profile, page, input, and loop count. A reload between snapshots changes the experiment and makes the comparison hard to defend.

4. Compare summaries before drilling down

Run get_heapsnapshot_summary on all three snapshots. Compare total size, object counts, dominant classes, and native contexts. Then use compare_heapsnapshots for baseline-to-target and baseline-to-final.

Target growth alone does not prove a leak. The stronger signal is growth that remains in final after the reverse action. If a separate native context owns most of the increase, filter to it before asking for individual objects.

5. Follow one representative retaining chain

For a suspicious class, list instances with get_heapsnapshot_class_nodes. Pick a representative node from the final snapshot and request get_heapsnapshot_object_details. Then inspect retainers, retaining paths, dominators, and edges until the chain reaches application-owned state.

Use category filters to test specific hypotheses: objects retained by detached DOM nodes, event handlers, execution contexts, or console references. Use duplicate-string analysis only when string growth dominates the comparison.

6. Make the smallest ownership fix

Fix the first application-owned edge that should have been released: remove a listener, clear a timer, unsubscribe, bound a cache, delete a map entry, release an observer, or break a stale closure. Do not delete framework state merely because it dominates the heap.

Pair the change with a durable regression check where practical. The agent-instruction guide shows how to require evidence before edits, while the package-vetting workflow helps when the retaining path enters a new dependency.

7. Replay, close, and record

Restart from a clean process or page state and run the identical three-snapshot protocol. Compare the same metrics and class/context. Close every loaded snapshot with close_heapsnapshot, including snapshots from failed hypotheses.

Report pass only when the replay meets the predeclared budget. Otherwise report the remaining growth and next retaining-chain hypothesis.

Common mistakes

  • Feeding a raw .heapsnapshot file into the model and exhausting context.
  • Treating one large snapshot as proof of a leak.
  • Changing the action, loop count, profile, or build between baseline and replay.
  • Fixing a detached node without checking whether it is an intentional cache.
  • Comparing browser RSS to heap-retained size as if they were the same metric.
  • Forgetting that DevTools, extensions, console references, and the diagnostic server can retain objects.
  • Leaving snapshots loaded after the investigation.
  • Publishing a fix without a fresh, identical replay.

The WebMCP security checklist is useful when the inspected page exposes agent-callable actions; memory diagnosis does not relax write or data-access boundaries.

Copyable evidence record 

date / owner / commit:
agent_client:
chrome_devtools_mcp_cli / daemon_version:
target_url_or_process:
snapshot_storage / retention:
suspected_action / reverse_action:
loop_count: 10
pass_budget:
baseline_summary:
target_summary:
final_summary:
largest_native_context_delta:
suspicious_class / representative_node_id:
retaining_path_to_application_code:
fix / regression_check:
replay_result: pass | fail
snapshots_closed: yes | no
remaining_risk / next hypothesis:
Enter fullscreen mode Exit fullscreen mode

FAQ

Can an AI agent read the raw heap snapshot directly?

It should not. The first-party skill says raw heap snapshots are extremely large and recommends native MCP summary, comparison, class, object, and retaining-path tools instead.

Does target-snapshot growth prove a leak?

No. The action may intentionally allocate memory. Stronger evidence is retained growth that survives the reverse action in the final snapshot and points through a retaining chain to application-owned state.

Why inspect native contexts?

A browser process can contain multiple pages, frames, extensions, or execution contexts. Version 1.7 can summarize their sizes and filter details by context, helping the agent avoid blaming the wrong page.

Does 1.7 eliminate memory leaks in Chrome DevTools MCP itself?

No. It fixes specific worker-disposal paths. You still need matched versions, valid paths, bounded experiments, and explicit close_heapsnapshot cleanup.

Sources

Top comments (0)