memory-leak-debug

name	memory-leak-debug
description	Diagnose memory leaks in the Qwen Code CLI using heap snapshots and the chrome-devtools CLI. Use when investigating high memory usage, unbounded growth, or suspected object retention issues.

Memory Leak Debugging

Diagnose memory leaks in the Qwen Code Node.js CLI by capturing heap snapshots and analyzing retained object sizes via chrome-devtools CLI tooling.

Prerequisites

• chrome-devtools CLI (from chrome-devtools-mcp package). If not found, install with: npm i chrome-devtools-mcp@latest -g after user confirmation. See https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md
• Node.js 22+ (for --heapsnapshot-signal support)

Step 1: Start the CLI with Snapshot Signal

Use tmux so you can interact with the TUI and trigger snapshots from another pane. Use the tmux-real-user-testing helper script:

HELPER=.qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh
eval "$(bash "$HELPER" start memleak . \
  env QWEN_CODE_NO_RELAUNCH=true NODE_OPTIONS=--heapsnapshot-signal=SIGUSR2 \
  npm run dev)"
echo "SESSION=$SESSION OUTDIR=$OUTDIR"

The eval exports SESSION and OUTDIR. Note: shell environment does not persist across separate tool calls — save the session name from the output and use it explicitly in subsequent commands.

Notes:

• npm run dev runs from TypeScript source via tsx — no build step needed and changes to core/cli are reflected immediately.
• QWEN_CODE_NO_RELAUNCH=true prevents the CLI from spawning a child process, so PID management is simpler.
• NODE_OPTIONS propagates the flag through npm → tsx → node.

Get the PID of the actual node process. With npm run dev, there's a process chain (npm → node scripts/dev.js → tsx → node CLI), so walk the tree to the innermost node child:

NODE_PID=$(bash .qwen/skills/memory-leak-debug/scripts/find-leaf-node.sh "<session-name>")

To profile the production bundle instead (e.g., verifying tree-shaking): npm run bundle first, then use env QWEN_CODE_NO_RELAUNCH=true node --heapsnapshot-signal=SIGUSR2 dist/cli.js as the command. Since node is the direct pane process, PID discovery is simpler:

NODE_PID=$(tmux list-panes -t "<session-name>" -F '#{pane_pid}')

Step 2: Exercise the Suspected Leak

Drive the TUI via tmux (see tmux-real-user-testing skill for patterns). Take snapshots at intervals to compare:

kill -USR2 $NODE_PID   # snapshot 1 (baseline)
# ... use the CLI via tmux send-keys ...
kill -USR2 $NODE_PID   # snapshot 2 (after activity)
# ... more activity ...
kill -USR2 $NODE_PID   # snapshot 3 (confirm growth trend)

Snapshots are written to the CLI's working directory as Heap.<timestamp>.<pid>.<seq>.heapsnapshot.

Step 3: Start chrome-devtools Daemon

chrome-devtools start --experimentalMemory --headless --no-usage-statistics

This starts the daemon in file-analysis mode — no browser or live Node connection is needed. The memory tools work entirely on .heapsnapshot files.

Step 4: Identify the Leak

Load and summarize

chrome-devtools load_memory_snapshot /abs/path/to/snapshot.heapsnapshot

Returns total heap size, V8 heap breakdown, node count.

Get class-level aggregates with retained sizes

chrome-devtools get_memory_snapshot_details /abs/path/to/snapshot.heapsnapshot

Output is CSV: uid, className, count, selfSize, maxRetainedSize.

Compare across snapshots to find classes whose count or retained size grows unboundedly.

Inspect instances of a leaking class

chrome-devtools get_nodes_by_class /abs/path/to/snapshot.heapsnapshot <uid>

Where <uid> is from the get_memory_snapshot_details output. Returns individual instances with their id, retainedSize, and nodeIndex.

Trace retainer chains

chrome-devtools get_node_retainers /abs/path/to/snapshot.heapsnapshot <nodeId>

Where <nodeId> is the id field from get_nodes_by_class. Shows what holds the object alive — follow the chain to find the root retention path.

Step 5: Identify Root Cause

Common patterns:

• Unbounded buffer/array: An array that accumulates entries without eviction (e.g., performance.measure() → measureEntryBuffer).
• Event listener leak: Listeners registered on long-lived emitters without cleanup.
• Closure capture: A closure inadvertently captures a large object that outlives its intended scope.
• Module-level cache: A Map/Set at module scope that grows with usage.

The retainer chain tells you what holds the object; the class aggregate growth rate tells you how fast it leaks.

Step 6: Verify Fix

After applying the fix:

1. Rebuild: npm run bundle
2. Repeat Steps 1-4 with the same workload.
3. Confirm the leaking class count stabilizes (no longer grows with activity).

Cleanup

HELPER=.qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh
bash "$HELPER" finish "<session-name>" "<outdir>"
chrome-devtools stop
rm *.heapsnapshot  # if no longer needed

Worked Example

See examples/react-reconciler-performance-measure-leak.md for the ink 7 upgrade leak that caused ~143 MB retention from PerformanceMeasure objects.