How to use the Memory Leak Debugger for Qwen Code agent skill

What does the memory-leak-debug skill make the agent do?

The skill sets out a step-by-step leak investigation. The agent starts the Qwen Code CLI in a tmux terminal session with a flag that lets it save V8 heap snapshots on a signal. It then sends that signal at several points during a workload, so you get a series of snapshots taken over time.

The agent loads those snapshots with the chrome-devtools command-line tool, compares which object classes grow in count or retained size, and traces what keeps the growing objects alive. From that it suggests likely root causes and how to verify a fix by rerunning the same workload.

• Captures snapshots at a baseline and after activity, to show a growth trend
• Lists class-level counts and retained sizes, and compares them across snapshots
• Traces retainer chains to show what holds an object in memory
• Suggests common causes such as unbounded arrays, listener leaks, closures and module-level caches

How do you install the memory-leak-debug skill?

Download the skill ZIP from this page and unzip it. Put the resulting folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

The skill folder contains SKILL.md, a scripts/ folder with find-leaf-node.sh, and an examples/ folder with a worked example. The SKILL.md commands refer to .qwen/skills/ paths, which match the layout of the Qwen Code repository, so check the paths before running them in another project.

What do you need before you start?

The skill lists these requirements. Check each one before you ask the agent to run an investigation.

• Node.js 22 or newer, because the heap snapshot signal flag needs it
• The chrome-devtools CLI from the chrome-devtools-mcp npm package. If it is missing, the agent offers to install it globally with npm, and only after you confirm
• tmux, which the agent uses to run the CLI in a session you can drive
• The tmux-real-user-testing helper skill from the same repository. The source references it but does not include it in the provided files, so you may need to get it from the repository separately

How do you trigger the skill with a natural request?

You do not need a special command. Describe the symptom in plain language and the agent should match it to the skill. The skill description says it applies when you are investigating high memory usage, unbounded growth, or suspected object retention issues.

Good requests name the symptom and the repository, for example asking the agent to check whether memory keeps growing while you use the Qwen Code CLI in this repo. Naming the workload helps the agent choose what to exercise between snapshots.

• Memory keeps climbing during long sessions in the CLI. Can you find the leak?
• Heap usage is high after many renders. Use the memory-leak-debug skill to find which objects are retained.
• Check whether the number of PerformanceMeasure objects grows as I use the TUI.

What does a typical investigation look like?

The agent starts the CLI in tmux with the snapshot signal enabled, finds the innermost node process, takes snapshots during activity, and then analyses them. The core commands come from the skill's own steps.

Snapshots are written to the CLI's working directory as Heap.timestamp.pid.seq.heapsnapshot files. Compare the class aggregates across snapshots first, then inspect instances of the class that grows, then follow its retainer chain to the root.

• Take a snapshot after the baseline, after activity and after more activity
• Load each snapshot and compare class counts and maxRetainedSize in the CSV output
• Use get_nodes_by_class with a class uid, then get_node_retainers with a node id

How do you verify a fix and clean up?

After you apply a fix, rebuild with npm run bundle, repeat the same snapshot workflow with the same workload, and confirm the leaking class count stops growing with activity. The worked example in the skill shows a leak in PerformanceMeasure objects that grew from 184 to about 150,700 instances over a session of normal use.

When you finish, the skill's cleanup steps close the tmux session, stop the chrome-devtools daemon and remove snapshot files you no longer need. Delete snapshots only when you no longer need them, because they can be large.