Claude Codeの/insights — セッション利用をHTMLレポート化するコマンド

Claude Codeの/insightsは何をするコマンドか

/insightsは、このマシン上の直近のセッションを分析してHTMLレポートを書き出すコマンドです。トークン使用量を数える/usageとは役割が違います。見るのは「何にどれだけ使ったか」ではなく、「どう働いているか」です。

レポートに入るのは、取り組んでいるプロジェクト、指示の誤解やバグといったつまずき、使い方を改善する機能の提案です。数値の集計というより、自分の使い方を振り返るためのコマンドと考えると分かりやすいでしょう。

起動できるのはセッションの中だけです。v2.1.287のclaude --helpを確認すると、サブコマンド一覧にinsightsはありません。ターミナルからclaude insightsのように呼ぶ形ではなく、対話セッションで次のように打ちます。

/insights

1回の実行で分析するのは、まだ見ていないセッションのうち最大200件です。極端に短いセッションは除外されます。除外が出ると、レポートの見出しに200 sessions (412 total)のように分析件数と総件数が並びます。

実行からレポートが消えるまでの流れ

レポートは実行のたびにファイルとして残り、一定期間で消えます。この流れを知らないと、過去のレポートを探しても見つからないことがあります。

cleanupPeriodDaysを大きくすれば残る期間は延びます。ただしこの設定はレポートだけでなく、セッションの記録を含むデータ全体の保持期間を決めます。最小値は1で、0はバリデーションエラーになります。削除はセッション開始後にバックグラウンドで走り、画面にメッセージは出ません。古いレポートがいつの間にか消えていても、通知は来ない仕様です。レポートだけ長く残したいなら、タイムスタンプ付きのコピーを別の場所に移しておくほうが副作用がありません。

組織で管理設定からcleanupPeriodDaysが配布されている場合は、その値で削除が走ります。個人の設定で延ばしても効かないため、保持期間はまず管理者に確かめることになります。

削除が走らないケースもあります。claude -pを--bare付きで実行したセッションでは、この掃除は動きません。Claude Codeが保持期間を安全に判断できないときも、掃除は一時停止します。ただし管理設定がcleanupPeriodDaysを配布している場合は、どちらの場合も管理設定の値で掃除が走ります。

レポートには何が載るか

公式が挙げる柱は3つです。取り組んでいるプロジェクト、指示の誤解やバグが出た場面などのつまずき、Claude Codeをもっと活用するための提案です。

加えて、auto modeが使えるセッションで直近の作業の多くがauto modeなしで進んでいた場合は、auto modeなら何回分の許可プロンプトを肩代わりできたかの見積もりが入ることがあります。許可プロンプトの多さに悩んでいる人には、見直しのきっかけになる項目です。

何が提案されるかは、セッション履歴の中身で毎回変わります。自分の履歴で一度実行して確かめるのが早い方法です。

レポートの数字を読むときの落とし穴

/insightsの出力は、そのまま「自分の働き方の実態」と受け取れるとは限りません。GitHubのissueには、集計の前提を知らないと誤読しやすい報告があります。いずれも報告の段階で、挙動が今後変わる可能性があります。

プロジェクトを絞って分析する機能はない

issue #95543では、/insightsがマシン上の全セッションを対象にし、1つのプロジェクトだけに絞る方法がない点が機能要望として出ています。報告者の環境(v2.1.278)では、セッションの記録が約4,300件、プロジェクトのパスが600超に分かれていました。注目したいプロジェクトは全体の1%強にすぎず、見出しには4,956 sessions total · 490 analyzedのように、総数のうち一部だけを分析した件数が出ていたとのことです。

つまり、特定のリポジトリの様子を知りたくても、レポートは全プロジェクトを混ぜた全体像になります。複数のリポジトリを行き来する人は、レポートの指摘がどのプロジェクトの話なのか、元のセッションで確かめる前提で読む必要があります。1人の環境での実測なので、割合は人によって変わります。

読み方の工夫はシンプルです。サブエージェントを多用している人は、「目標未達」の件数が多くても、自分のセッションの結果とは限りません。数字は傾向をつかむ材料にとどめ、気になる点は実際のセッションを開いて確かめるのが安全です。

文章の節が空だったときは、使える材料が足りなかったのか、生成が失敗したのかをレポートからは区別できません。原因はissueでも確定していません。

初回に実行するときの目安

履歴がほとんどない状態で実行しても、材料が少ないので得られるものは多くありません。Claude Codeを入れたばかりなら、Claude Codeの全体像を押さえて実際の作業を重ねてから実行したほうが、レポートの中身は具体的になります。逆に200件を超えるセッションがたまっている場合は、1回の実行で拾われない分が残るため、続けて実行すると未分析のセッションが順に対象になります。

/insightsが使えない場面

/insightsはクラウドセッションでは使えません。公式のコマンド一覧にも、クラウドセッションでは利用できないと明記されています。

さらに、分析の対象は「このマシンのセッション」に限られます。他のデバイスやclaude.aiでのセッションは含まれません。ノートPCとデスクトップの両方で作業しているなら、それぞれのマシンで実行して別々のレポートを読むことになります。

チームや組織全体の利用傾向を見たい場合も、/insightsでは完結しません。その用途には、次の節の組織向けの仕組みが用意されています。

/usage・組織向けの分析との使い分け

/insightsと混同しやすい仕組みが2つあります。知りたいことに応じて選びます。

/usageはその場の数字を見る用途です。/insightsはまとまった期間の働き方を振り返る用途で、組織向けの2つは継続的に計測する用途です。組織向けのダッシュボードは、Claude for TeamsとEnterpriseならclaude.ai/analytics/claude-codeで、AdminとOwnerが見られます。受け入れた行数・提案の採用率・日次アクティブユーザー・セッション数に加え、GitHub連携を設定すればClaude Code経由のPRや行数も追えます。この貢献指標はパブリックベータで、Zero Data Retentionが有効な組織では使えません。

APIのClaude Console利用者の画面は、platform.claude.com/claude-codeです。ユーザー別のトークン数やコストの見積もりは、このダッシュボードでなくOpenTelemetryの出力か、組織の分析設定から出せる支出レポートで確認します。コスト管理の基盤を作り込むなら、OpenTelemetryの出力をRoutinesで定期集計する設計もあります。

定期的に振り返る運用にする

/insightsは手動で打つコマンドで、/loopに渡して一定間隔で回す形は使えません。/loopなどの定期実行でコマンドとして動くのは、Claudeが自分で呼び出せるskillだけです。/insightsのような組み込みコマンドは、ただの文字列としてClaudeに渡ります。

定期的に振り返るなら、履歴がたまった週次や月次の単位で自分の手で実行する運用になります。

もうひとつ気にしたいのがコストです。分析処理もセッションとしてトークンを消費します。毎回のセッションで回すより、ある程度履歴がたまった単位でまとめて実行するほうが、消費と得られる情報のつり合いは取りやすくなります。

よくある質問

レポートのリンクを押しても開けないときは

Claude Desktopのコードタブで、レポートへのリンクを押すと「Couldn't find this file」と表示される事例がissue #93355で報告されています。レポートが作業ディレクトリの外(~/.claude/usage-data/)にあるため、アプリがリンクを解決できないという報告です。ファイル自体は存在するので、ブラウザでそのパスを直接開けば表示できます。

Windowsでレポートのリンクが壊れるときは

Windowsでは、/insightsが出力するレポートのURLがfile:///C:/...でなくfile://C:\...の形になる不具合がissue #90759で報告されています。リンクを押しても開けない場合は、エクスプローラーでusage-dataフォルダを開き、report.htmlをブラウザにドラッグすれば表示できます。

usage-dataの中にはレポート以外も入っていますか

公式のディレクトリ解説によると、usage-data/にはreport.htmlとタイムスタンプ付きのコピーのほか、レポートを作るために使うセッションごとの分析データのキャッシュも入ります。レポートのHTMLだけを別の場所へ移しても、このキャッシュは元の場所に残り、cleanupPeriodDaysの対象として削除されます。

まとめ

今のセッションの消費を見るなら/usage、まとまった期間の働き方を振り返るなら/insights、チームや組織の計測なら分析ダッシュボードかOpenTelemetryと、知りたい範囲で選び分けます。/insightsはこのマシンのセッションだけが対象で、クラウドセッションでは動きません。レポートは保持期間で消えるため、残したいものは別の場所へ移しておきます。