Memory Leak Hunting skill for Claude Code

Done well means: growth is demonstrated with a repeatable action loop, a heap comparison identifies the object type that accumulates, its retainer chain names the exact reference keeping it alive, the fix removes that reference, and the same loop afterwards returns to a flat baseline.

Ground rules

• Distinguish a leak from normal behavior first: caches warming up, lazy initialization, and GC that has not run yet all look like growth. A leak grows per repeated action and survives forced GC.
• Measure with repetition. One action proves nothing; 10–50 repetitions of the same action with a forced GC before each snapshot proves accumulation.
• Find the retainer, not just the leaked object. “50,000 Order objects” is a symptom; “held by listeners array on the singleton EventBus via closure in OrderWidget” is the cause.
• Heap snapshots pause the process and can be large (roughly heap size). On production servers take the instance out of rotation and get explicit approval first; snapshots may contain user data and secrets — handle them as sensitive files.

Workflow

- [ ] 1. Confirm growth: memory over time across repeated identical actions, after forced GC
- [ ] 2. Identify the kind: JS heap, native/external (Buffers, ArrayBuffers), DOM, or RSS only
- [ ] 3. Three snapshots: baseline -> after N actions -> after N more actions
- [ ] 4. Compare: object types whose count grows by ~N per round
- [ ] 5. Follow retainers from a leaked instance up to a GC root
- [ ] 6. Fix the retaining reference; add cleanup
- [ ] 7. Re-run the same loop; confirm flat memory

1–2. Confirm and classify

Node:

setInterval(() => {
  const m = process.memoryUsage();
  console.log(JSON.stringify({
    rss: m.rss >> 20, heapUsed: m.heapUsed >> 20, external: m.external >> 20, arrayBuffers: m.arrayBuffers >> 20,
  }));
}, 10_000).unref();

Growing	Where to look
heapUsed	JS objects: heap snapshots
external / arrayBuffers	Buffers, streams not consumed, native addons
rss only, heap flat	Native allocations, fragmentation, thread stacks, or the allocator not returning memory (check whether it plateaus)
Browser: JS heap in Performance monitor / Memory panel	Heap snapshots, detached DOM
Browser: DOM node count rising	Detached elements, unbounded lists

Force GC for clean measurements: Node node --expose-gc then global.gc(); DevTools has a “Collect garbage” button (trash icon) in the Memory and Performance panels.

3–4. Three-snapshot technique

Browser (Chrome DevTools > Memory > Heap snapshot):

1. Load the page, do the action once (warm caches), collect garbage, take snapshot 1.
2. Repeat the action N times (e.g., open and close the modal 10 times), collect garbage, take snapshot 2.
3. Repeat N more times, collect garbage, take snapshot 3.
4. Select snapshot 3, view “Comparison” against snapshot 2 (or “Objects allocated between snapshots 1 and 2” in the Summary view filter). Sort by ”# Delta” or “Size Delta”.
5. Look for constructors whose delta is a multiple of N: your classes, Detached HTMLDivElement, closures ((closure)), arrays, strings with recognizable content.

Filter “Detached” in the class filter to find DOM nodes removed from the document but still referenced from JS. Recent Chrome versions also offer a “Detached elements” profiling type in the Memory panel.

Node: take the same three snapshots via node --inspect and DevTools (chrome://inspect > Memory), or programmatically:

import { writeHeapSnapshot } from "node:v8";
// call after global.gc(): writes Heap-<timestamp>.heapsnapshot in cwd; open in DevTools Memory tab
const file = writeHeapSnapshot();

node --heapsnapshot-signal=SIGUSR2 app.js lets you trigger snapshots with kill -USR2 <pid>; --heapsnapshot-near-heap-limit=2 captures automatically before an out-of-memory crash.

Automate browser scenarios with MemLab (Meta): write a scenario with url, action, and back functions, run npx memlab run --scenario scenario.js, and it reports leaked objects with retainer traces. Useful for CI regression checks on SPAs.

5. Read retainers

In the snapshot, click a leaked instance and read the Retainers pane bottom-up to a GC root (Window, global, a module-level variable, an active timer, an event listener list).

• Ignore weak references and internal (system) / (compiled code) edges at first.
• The first object in the chain you own (your module, class, or closure) is where the fix goes.
• Closures show as context edges: a function retains its entire lexical scope, so an inner callback can keep a large outer variable alive.

6. Common leak patterns

Pattern	Fix
Event listener added on mount, never removed (window, document, emitters, sockets)	Remove in cleanup; use AbortController signal: addEventListener("resize", fn, { signal }) then controller.abort()
setInterval / setTimeout loops never cleared	Store handles, clear on teardown
Unbounded Map/object cache keyed by request, user, or URL	LRU with max size and TTL; WeakMap when keyed by objects whose lifetime you do not control
Subscriptions (RxJS, stores, WebSocket handlers) without unsubscribe	Unsubscribe in cleanup / takeUntil / effect return
React effect without cleanup	Return a cleanup from useEffect; abort fetches
Detached DOM held by a JS array or closure	Drop references when removing nodes; avoid caching DOM nodes globally
Global arrays used as logs/queues	Bound them or flush
Promises that never settle, each holding a closure	Timeouts with AbortSignal.timeout(ms); reject on teardown
Per-request data stored on long-lived objects (app.locals, singletons)	Keep request data in request scope / AsyncLocalStorage
Node streams not consumed or not destroyed	pipeline() from node:stream/promises; destroy on error
MaxListenersExceededWarning	A listener added per request/operation; fix the add, do not raise the limit

For the per-runtime catalog (Python, Go, JVM, browser frameworks) with tool commands, read references/leak-patterns.md when the leak is outside JavaScript or the common patterns above do not match.

7. Prove the fix

Repeat the exact loop from step 3 with the fix. Pass criteria: after forced GC, heap size at round 3 equals round 2 within noise (a few percent), and the leaked constructor’s delta is zero.

Gotchas

• DevTools itself retains objects: console-logged objects stay referenced. Clear the console and avoid console.log(obj) during measurements.
• Development builds (React StrictMode, HMR, source maps) retain extra objects; confirm in a production build.
• Snapshots taken without GC show garbage as growth.
• A WeakMap only helps when keys are objects whose lifetime ends elsewhere; it does not make values collectable while keys live.
• In Node containers, an OOMKilled pod may be heap limit vs. container limit mismatch rather than a leak: set --max-old-space-size to about 75% of the container memory and re-test.
• Memory that climbs and plateaus is usually a cache or pool at its cap, not a leak; check configured max sizes.

Report template

**Symptom:** dashboard tab grows ~40 MB/hour; Chrome kills it after ~6 h
**Repro:** switch between Overview and Reports 20x, collect garbage, snapshot (x3)
**Growth:** +20 `ChartInstance`, +20 Detached HTMLCanvasElement per 20 switches
**Retainer chain:** window -> resizeHandlers (Array) -> closure in useChart.ts:31 -> ChartInstance -> canvas
**Fix:** effect cleanup removes the resize listener (AbortController) and calls chart.destroy()
**After:** heap flat at 38 MB across 3 rounds; detached canvas count 0