Claude Codeの/heapdumpでメモリ使用量の高さを診断する
/heapdumpはヒープスナップショットと診断用JSONを書き出す隠しコマンドです。会話全体と資格情報が含まれる共有禁止の理由と、報告・自己調査の手順をまとめます。
/heapdumpは何をするコマンドか
/heapdumpは、Claude Codeのメモリ使用量が高止まりしたときに使う診断コマンドです。実行すると2ファイルを書き出します。1つはJavaScriptヒープスナップショット(<セッションID>.heapsnapshot)、もう1つはメモリの内訳をまとめた診断用JSON(<セッションID>-diagnostics.json)です。保存先は~/Desktopで、Linuxでデスクトップフォルダーが無い環境ではホームディレクトリになります。
コマンドメニューには出てきません。/を打っても候補に表示されないため、/heapdumpと全部タイプして実行する必要があります。
/heapdump実行すると会話内にもサマリーが表示されます。中身はRSS(常駐セットサイズ)・JSヒープ・array buffers・分類できないネイティブメモリの内訳です。加えて、メモリ増加率の異常な高さや開いているハンドル数の異常な多さといったリーク兆候があれば、それも一緒に表示されます。このサマリーは、メモリの大半がJSヒープ(スナップショットが捕捉できる範囲)にあるのか、ネイティブメモリ(スナップショットには映らない範囲)にあるのかを教えてくれます。
サマリーの4つの内訳が指すもの
会話内に表示されるサマリーは、OSから見たプロセス全体の専有メモリ量を示すRSS(常駐セットサイズ)を起点に、その中身を3つに分けて示します。JSヒープはNode.jsのV8エンジンが管理するJavaScriptオブジェクトのメモリで、会話履歴や文字列データの多くはここに乗ります。array buffersは画像やファイルなどのバイナリデータを保持する領域です。残りがネイティブメモリで、V8の外側でNode.jsの内部処理やネイティブモジュールが確保しているメモリを指します。
この分類が重要なのは、.heapsnapshotが捕捉できるのはJSヒープだけだからです。array buffersとネイティブメモリはスナップショットに映らないため、サマリーが「大半はネイティブメモリ」と示している場合、DevToolsでスナップショットを開いても原因は見えません。この場合は自己調査を諦めて報告に回ったほうが早く解決します。
メモリの重さとコンテキストウィンドウの逼迫は別物
「Claude Codeが重い」と感じたとき、原因はプロセスのメモリ使用量とは限りません。コンテキストウィンドウ(会話に読み込まれているトークン量)が上限に近づいている場合も、応答が遅く感じられたり、圧縮(/compact)が頻発したりします。この2つは仕組みがまったく別です。
コンテキストウィンドウの逼迫は/contextで内訳(システムプロンプト・ツール・メモリファイル・メッセージ)を確認でき、/compactで圧縮します。一方/heapdumpが扱うのはOSレベルのプロセスメモリで、コンテキストウィンドウのサイズとは独立した指標です。長時間セッションでは両方が同時に膨らむこともあります。「重い」と感じたら、まず/contextでトークン内訳を見ます。コンテキストではなくメモリそのものが問題だと分かってから/heapdumpに進むと無駄がありません。
いつ使うべきか — 手前の切り分けを先に済ませる
公式のトラブルシューティングガイドは、/heapdumpをメモリ・CPU使用量が高いときの最終手段として位置付けています。重さを感じたらまず次の順で切り分けます。
/compactで会話を定期的に圧縮する(Not enough messages to compact.と出たらターン数不足のサインで、大きな貼り付け1回でも起きうる)- 大きな作業を終えるたびにClaude Codeを再起動する
- 大きなビルドディレクトリを
.gitignoreに追加する claude --safe-modeで再起動し、プラグイン・MCPサーバー・Hookが原因かどうかを確認する
これらを試してもメモリ使用量が高いままなら、/heapdumpで実際に何が滞留しているかを見に行く番です。--safe-modeとの役割の違いは、safe modeが「カスタマイズが原因かどうか」を切り分けるのに対し、/heapdumpは「メモリの中身そのもの」を見る点にあります。safe modeの詳しい使い方はClaude Code safe modeで「壊れた」設定を1コマンドで切り分けるにまとめています。
.heapsnapshotは絶対に公開共有しない
/heapdumpが書き出す2ファイルのうち、.heapsnapshotには取り扱い注意の情報が入ります。プロセス内の文字列がすべて含まれる形式のため、これまでの会話内容と、環境変数やAPIキーなどの資格情報がまるごと収まっています。公開のGitHub Issueに添付したり、Slackやチャットに貼ったりしてはいけません。
これは実務上、/heapdumpを使ううえで最も重要な注意点です。メモリ調査のために書き出したファイルが、そのまま情報漏えいの経路になってしまうケースは珍しくありません。
2ファイルの使い分け
| ファイル | 中身 | 外部共有 |
|---|---|---|
<セッションID>.heapsnapshot | 中身プロセス内の全文字列を含むJSヒープの完全なスナップショット | 外部共有不可(会話・資格情報を含む) |
<セッションID>-diagnostics.json | 中身RSS・JSヒープ・array buffers・ネイティブメモリの内訳とリーク兆候の統計情報 | 外部共有可(GitHub Issue報告用) |
自分で原因を調べる — Chrome DevToolsでスナップショットを開く
会話内のサマリーで「メモリの大半はJSヒープにある」と出た場合は、.heapsnapshotを自分で開いて原因を絞り込めます。手順はシンプルです。
- 任意のタブでF12(またはCmd+Option+I)を押してChrome DevToolsを開く
- Memoryタブを選ぶ
- Loadから
.heapsnapshotファイルを読み込む - Retained Size(保持サイズ)の降順でソートし、上位のオブジェクトから確認する
保持サイズの大きいオブジェクトが、会話履歴の蓄積なのか、特定のツール呼び出し結果の滞留なのか、MCPサーバーとのやり取りに由来するのかを見ていくと、リークの候補が絞れます。
サマリーが「メモリの大半はネイティブメモリにある」と示している場合は、この方法では原因を追えません。.heapsnapshotはJSヒープしか捕捉しないためです。この場合は次の「報告する」に進み、サマリーのリーク兆候をそのまま添えて報告する方が早く解決します。
GitHub Issueで報告する
自分で追いきれない、あるいはネイティブメモリ側の問題だと分かった場合は、GitHub Issueを開いて診断用JSONだけを添付します。サマリーに出ていたリーク兆候(メモリ増加率・開いているハンドル数など)をコメントに書き添えると、原因調査が早く進みます。
# 添付するのは -diagnostics.json のみ
# .heapsnapshot は手元で確認するか削除する
ls ~/Desktop/*-diagnostics.json/heapdumpが有効な状況・そうでない状況
メモリ調査は環境によって効き方が変わります。以下は状況別の目安です。
| 状況 | /heapdumpの効き方 |
|---|---|
| 長時間セッションで体感的に重くなってきた | /heapdumpの効き方明確な恩恵あり。まず会話サマリーで内訳を確認する |
| プラグイン・MCPサーバー導入後からメモリが増えた | /heapdumpの効き方条件次第。--safe-modeとの併用で原因を絞りやすい |
| 単発の重い処理中に一時的に重くなっただけ | /heapdumpの効き方ほぼ影響なし。処理完了後に解消するなら診断は不要 |
| サマリーが「ネイティブメモリが大半」と示している | /heapdumpの効き方.heapsnapshotでは追えない。診断用JSONとリーク兆候を添えて報告する側に回る |
大きなテーブル表示との違いに注意する
メモリが高いのと紛らわしい別の症状として、ターミナルの表示が重いケースがあります。200行を超えるMarkdownテーブルは先頭200行だけが表示され、残りは省略行になります。これは表示上の制限であり、会話内には全行が保持されたままで/copyでも全行コピーされます。メモリの実測値そのものが高いわけではないため、/heapdumpで調べても解決しません。読みにくいだけなら、ファイルに書き出すよう頼む方が早く解決します。
よくある質問
/heapdumpはいつ追加された機能か
公式ドキュメントには追加バージョンの明記がなく、現行のトラブルシューティング手順に組み込まれています。
コマンドメニューに出てこないのはなぜか
/heapdumpはコマンドメニューの候補には表示されません。/だけを打って一覧をスクロールしても見つからないので、フルネームで直接入力します。
.heapsnapshotはどのくらいの大きさになるか
サイズは会話の長さやセッション中に扱ったファイルの量に左右され、公式ドキュメントに具体的な目安の記載はありません。会話が長いセッションほど、含まれる文字列(=会話内容)も増えるため、大きくなりやすいと考えられます。
Windowsでも保存先は~/Desktopか
公式ドキュメントは保存先を「~/Desktop、Linuxでデスクトップフォルダーが無い環境はホームディレクトリ」とだけ説明しています。Windows固有の例外は明記されていないため、通常のユーザープロファイル配下のデスクトップフォルダーに書き出されると考えられます。
まとめ
/heapdumpはメモリ使用量が高いときの最終診断手段です。.heapsnapshotと-diagnostics.jsonの2ファイルを書き出します。前者には会話内容と資格情報がまるごと含まれるため公開共有は厳禁で、後者だけがGitHub Issue報告に使える統計情報です。使う前に/compact・再起動・.gitignore整理・--safe-modeで切り分けを済ませておくと、/heapdumpが本当に必要な場面かどうかが分かります。環境変数でメモリ関連の挙動を制御したい場合はClaude Code環境変数リファレンス、それ以外の起動エラー全般はClaude Codeでよくあるエラー10選が近い距離の関連記事です。