/heapdump（ヒープダンプ）

Claude Codeが重くなった・パソコンのメモリを食いすぎていると感じている人向け

/heapdump は、Claude Code がメモリ（パソコンが作業に使う一時記憶）をどれくらい食っているか、その内訳を1ファイルに書き出してくれるコマンドです。大きなプロジェクトで長時間作業していると、Claude Code がだんだん重くなることがあります。そのとき「何がメモリを食っているのか」を後で調べられる形で取り出すのがこのコマンドの役目です。

ここで大事なのは、これは重さを直すコマンドではなく、原因を調べるための材料を書き出すコマンドだという点です。叩いてもメモリは減りません。ここを勘違いすると「実行したのに軽くならない」と悩むことになります。

噛み砕くと

例えるなら、調子の悪い車をディーラーに持っていく前に、エンジンの状態を記録した診断シートを1枚プリントするようなものです。シートを印刷しても車は直りません。でも、整備士に渡せば「どこが悪いか」を一緒に見てもらえます。

/heapdump はその診断シートにあたります。書き出されるのは、Claude Code が今どんなデータをどれだけ抱え込んでいるかの記録です。自分でその記録を開いて中身を見ることもできるし、不具合として報告するときに添付して開発元に渡すこともできます。

つまり「重い原因の写真を撮る」コマンド、と思っておくとズレません。

大事な前提：先に試すべき軽くする手順が3つある

公式は「メモリが高いとき、いきなり /heapdump ではない」と順序を示しています。まず次の3つを試します。

• /compact をこまめに叩いて、会話の積み重なり（コンテキスト）を圧縮する
• 大きな作業の区切りで、Claude Code を一度閉じて立ち上げ直す
• サイズの大きなビルド用フォルダを .gitignore に書いて、読み込み対象から外す

この3手を試してもメモリが高いまま、というときに初めて /heapdump の出番です。/heapdump は「軽くする最後の一手」ではなく「3手を尽くしても駄目だった時の調査ツール」という立ち位置になります。

「料理ブログの巨大フォルダで重くなった」を例に、実際の手順を見る

料理ブログの全記事（数百本のテキストと画像）が1つのフォルダに入っていて、そこで何時間も Claude Code を動かしていたら、だんだん反応が遅くなってきた、という場面で追ってみます。

ステップ1: まず公式の3手で軽くなるか試す

/compact を叩いて会話を圧縮し、一度 Claude Code を閉じて立ち上げ直します。画像の入った重い書き出しフォルダがあれば .gitignore に足します。ここで軽くなれば /heapdump は要りません。

ステップ2: それでも重いので /heapdump を叩く

3手を尽くしても反応が重いまま。ここで初めて、Claude Code の入力欄に次のように打ちます。

/heapdump

コマンドの後ろには何も書き足しません。これだけで実行されます。

ステップ3: デスクトップに2つのファイルが書き出される

実行すると、2点セットのファイルが ~/Desktop つまりデスクトップに書き出されます。Linux でデスクトップフォルダが無い環境では、代わりにホーム、つまり利用者ごとの一番上のフォルダに書き出されます。中身はこの2つです。

• JavaScript のヒープスナップショット。拡張子が .heapsnapshot のファイルです
• メモリの内訳。何がどれだけメモリを使っているかの一覧です

ステップ4: 内訳を見て「どっち側の肥大か」を読む

内訳には4つの数字が出ます。実際に使っているメモリ全体を示す resident set size、JavaScript のデータ分にあたる JS heap、まとまったデータの置き場である array buffers、そして内訳に出てこない土台側の分である unaccounted native memory です。

この4つを見ると、肥大しているのが JavaScript のデータ側なのか、それとも土台のプログラム、つまりネイティブコード側なのかを切り分けられます。これが分かるだけで、原因の当たりがだいぶ絞れます。

ステップ5: ここで初心者がやりがちな勘違い

「/heapdump を叩いたのに、まだ重い」と焦る人が多いです。当然です。これは記録を書き出すコマンドであって、メモリを解放するコマンドではありません。書き出した後も重さは続くので、軽くしたいなら再起動や /compact に戻ります。

ステップ6: 自分で開くか、報告に添えるか

.heapsnapshot ファイルは、Chrome の開発者用ツール（Chrome DevTools）の Memory → Load から開けます。そこで「何がそのデータを掴んで離さないか（retainers）」をたどれます。自分で原因を追いたい人向けのルートです。もう一つは、不具合として報告するルートです。

つまり /heapdump は何をしてくれるのか

• やってくれる: 今この瞬間のメモリの中身と内訳を、2つのファイルにしてデスクトップに書き出す
• やってくれない: メモリを減らす・軽くする処理はしない。叩いても重さはそのまま続く
• 意味が薄い場面: まだ /compact も再起動も .gitignore 整理も試していない段階。先にその3手で軽くなることが多い

使いどころ3シナリオ

シナリオ1: 料理ブログの全記事フォルダで丸一日作業して重くなったとき

数百本の記事と画像が入ったフォルダで、朝から晩まで Claude Code を動かしていたら反応がもっさりしてきた。/compact と再起動を試しても戻らない。ここで /heapdump を叩いて内訳を見ると、array buffers が異常に大きければ「画像データを抱え込みすぎ」という当たりが付きます。

シナリオ2: 家計簿アプリの開発中、ビルドのたびに重くなるとき

家計簿アプリを作っていて、組み立て直すたびにメモリがじわじわ増える。.gitignore にビルド用フォルダを足しても改善しない。/heapdump の内訳で JS heap 側が膨らんでいるのか、ネイティブコード側なのかを切り分けてから、どちらを疑うか決められます。

シナリオ3: 「メモリが落ちない」を開発元に報告したいとき

自分で原因まではたどれないけれど、明らかにおかしいので報告したい。そのとき /heapdump で書き出した .heapsnapshot と内訳の両方を、GitHub の不具合報告（anthropics/claude-code の issues）に添付します。記録があるだけで、開発側が状況を再現しやすくなります。

初心者が踏みやすい落とし穴

• 叩いてもメモリは減らない。これは調査用の書き出しコマンドで、軽くする処理はしません。軽くしたいなら /compact や再起動です。
• 重い時の第一手にしない。公式は「まず /compact・再起動・.gitignore 整理の3手、それでも高いままなら /heapdump」という順序を示しています。
• 報告時に片方だけ添付しがち。.heapsnapshot と内訳の両方を添えるのが公式の案内です。片方だと調査材料が足りません。
• 書き出し先を探して迷う。ファイルはデスクトップ（~/Desktop）に出ます。Linux でデスクトップフォルダが無い環境ではホームに出ます。ターミナルの今いる場所には出ません。
• .heapsnapshot をテキストアプリで開こうとする。これはメモ帳では中身が読めません。Chrome DevTools の Memory → Load から開きます。
• こまめに連打するものではない。公式が案内しているのは「3手順を試してもメモリが高いままのとき」に調査用として書き出す使い方です。原因を調べたい場面で1回叩けば材料は揃います。

書き方

/heapdump

やってみるとこうなる

入力

/heapdump

出力例

デスクトップ（~/Desktop、Linuxでデスクトップフォルダが無ければホーム）に2つのファイルが書き出される。1つはヒープスナップショット（.heapsnapshot ファイル）、もう1つはメモリの内訳。内訳には resident set size / JS heap / array buffers / unaccounted native memory の4つが並び、肥大がJavaScriptのデータ側か土台のプログラム側かを切り分けられる。叩いてもメモリ自体は減らない

関連項目

• /doctor（ドクター）
• /compact（コンパクト）
• /clear（クリア）
• /context（コンテキスト）
• /bug（バグ）

公式ドキュメント

https://code.claude.com/docs/en/troubleshooting#high-cpu-or-memory-usage