Claude Codeのsession-reportプラグインで消費トークンをHTML化する

session-reportは、~/.claude/projectsに残るセッション記録(トランスクリプト)を集計し、トークン消費を1枚のHTMLにまとめる公式プラグインです。マーケットプレイスの説明では、トークン・キャッシュ効率・サブエージェント・スキル・最も高くついたプロンプトを、操作しながら読めるレポートにするとされています。

「今週どのプロジェクトがトークンを食ったのか」を、/usageの合計値ではなく内訳で知りたいときに向きます。この記事では導入と実行、レポートの読み方、集計の数え方、使う前に知っておきたい制約を扱います。

session-reportは何を集計するプラグインか

プラグイン本体はスキル1つ(skills/session-report)で、中身は3ファイルです。

数字を出すのはスクリプトで、Claudeは雛形にJSONを埋め込み、所見の文章を書く役です。マーケットプレイスのページにはAnthropic verifiedの表示があり、提供元はAnthropicとなっています。

導入して実行する

公式マーケットプレイスのプラグインなので、claude-plugins-officialを指定して入れます。Claude Codeは初めて対話セッションを起動したときに公式マーケットプレイスを登録するため、追加の手順は要りません。

claude plugin install session-report@claude-plugins-official

セッション内なら/plugin install session-report@claude-plugins-officialです。この場合はすぐには入らず、/pluginパネルの詳細画面が開くので、内容を確かめてスコープを選びます。claude.comのマーケットプレイスにある「Claude Code」ボタンは、上のシェル形式のコマンドをコピーします。

集計スクリプトはnodeコマンドで動くため、Node.jsが入っていない環境ではレポートを作れません。Claude Code本体のネイティブ版はNode.jsを使わないので、これまで入れていなかった人はここで別途用意します。バージョンの下限は、プラグイン側に記載がありません。

プラグインのスキルは/プラグイン名:スキル名の形で呼ばれます。このプラグインなら/session-report:session-reportです。

/session-report:session-report 30d

期間の指定は、SKILL.mdが例に挙げる24h・30d・allです。指定がなければ直近7日が対象になります。完了すると、カレントディレクトリにsession-report-日付-時刻.htmlが保存され、パスが報告されます。SKILL.mdは、Claudeにそのファイルを開いたり描画したりさせないと定めているので、ブラウザで自分で開きます。

実行中にClaudeが何をしているか

押さえておきたいのは、JSONを読むのも所見を書くのもClaude自身という点です。表やグラフの数字はスクリプトの出力そのままですが、「このプロジェクトが全体の4割を使った」といった所見の文章はモデルが生成します。所見の数字は、レポートの表と見比べて確かめると安心です。

SKILL.mdは所見の書き方も指定しています。数字は全トークン(入力合計と出力の和)に対する割合で示し、赤(無駄・異常)、緑(良好)、青(中立)の3色で分類します。探す対象として挙がっているのは次のとおりです。

• 1つのプロジェクトやスキルが全体の大きな割合を占めている
• キャッシュヒット率が85%未満
• 1つのプロンプトが全体の2%を超えている
• 1回の呼び出しで平均100万トークンを超えるサブエージェント
• キャッシュ切れの集中

レポートの構成と読む順番

雛形のセクションは、上から次の順に並びます。

1. findings(所見)
2. summary(全体の合計)
3. tokens by project(プロジェクト別の割合)
4. session timeline by day(日別のセッション時間帯)
5. most expensive prompts(高くついたプロンプト。クリックで文脈が開く)
6. cache breaks(キャッシュ切れ)
7. projects / subagent types / skills & slash commands(表)
8. recommendations(改善提案)

最初に見るのはtokens by projectです。割合の偏りが分かれば、以降はその行に絞って、most expensive promptsで原因のプロンプトを探します。キャッシュヒット率は雛形のコードで85%を境に色分けされており、85%以上なら正常、未満なら警告の色で表示されます。

サブエージェントとスキルの表は、「どの仕組みがトークンを使ったか」を切り分ける場所です。スキルの行は、呼び出しから次の人間のメッセージまでのトークンを、そのスキルに帰属させて数えます。サブエージェントを並列に走らせるスキルが上位に出たら、/usageの内訳(詳しくはLoopの内訳から消費トークンを特定する方法)と照らして原因を追えます。

集計の数え方を知っておく

スクリプト冒頭のコメントとコードから、数字の前提が読み取れます。

キャッシュ切れの閾値は、スクリプトを直接実行するときの--cache-breakで変えられます。レポートの見出しにある「>100k uncached」は既定値です。

また、集計されるのはトークン数だけで、料金への換算はありません。ドルでの金額が必要なときは、別の手段で見積もります。

実際にスクリプトを動かして出力を確かめる

スクリプトは単体で実行できます。公開されているコードの挙動を確かめるため、手作りの小さなトランスクリプトで走らせました。以下は、2回のやり取りだけを書いた合成データの結果で、実際の作業記録ではありません。1回目で15万トークンのキャッシュを作り、2回目でそれを読み出す想定です。

node <見つかったパス>/analyze-sessions.mjs --dir ./fixture --since 7d

OVERALL
  sessions: 1   api calls: 2   human msgs: 2
  input:  302.1k total  (uncached 80, cache-create 152.0k, cache-read 150.0k = 49.7% cached)
  output: 1.3k
  cache breaks >100.0k: 1
CACHE BREAKS (>100.0k uncached input on a single call)
    150.1k uncached /   150.1k total  -demo-app
MOST EXPENSIVE PROMPTS
    152.5k  (in 152.0k 98.7% cached, out 500)  1 calls
    150.8k  (in 150.1k 0.0% cached, out 800)  1 calls

この出力から分かることが2つあります。

• キャッシュ読み取りが入力の約半分でも、全体のキャッシュ率は49.7%と出ます。会話の最初の呼び出しは必ずキャッシュ作成から始まるので、短いセッションは率が低く出やすくなります
• この例では、1回目の呼び出しがそのままキャッシュ切れの1件として数えられました。閾値を超えたかどうかだけで判定しているため、最初のキャッシュ作成も「切れ」に入ります

つまり、cache breaksの件数は、閾値を超えた回数であって、障害の数ではありません。同じプロジェクトで何度も出ているか、直前のやり取りの後に急に出ているかを、tsと文脈を開いて確かめるのが筋です。

レポートを作らずJSONだけ取り出す

HTMLが要らず、数字だけを定期的に記録したいなら、スクリプトを直接呼んでjqで絞る方法があります。スクリプトはanalyze-sessions.mjsというファイル名で、インストール時にプラグインのキャッシュへコピーされます。置き場所は~/.claude/plugins/cache/<マーケットプレイス>/<プラグイン>/<バージョン>/の下で、CLAUDE_CODE_PLUGIN_CACHE_DIRを設定していればそちらが基準です。バージョンごとにディレクトリが分かれるため、パスはアップデートで変わります。毎回探すほうが確実です。

find ~/.claude/plugins/cache -name analyze-sessions.mjs

見つかったパスをnodeに渡して実行します。以下は<見つかったパス>の部分を置き換える書き方です。

node <見つかったパス>/analyze-sessions.mjs --json --since 7d \
  | jq '.by_project | to_entries
        | map({project: .key,
               total: .value.input_tokens.total,
               out: .value.output_tokens,
               cached: .value.input_tokens.pct_cached})'

先ほどの合成データで実行すると、次のようにプロジェクトごとの入力合計・出力・キャッシュ率だけが返りました。

[{ "project": "-demo-app", "total": 302080, "out": 1300, "cached": 49.7 }]

JSONのトップレベルはoverall・cache_breaks・by_project・by_subagent_type・by_skill・top_prompts・by_dayです。日付つきのファイルに追記していけば、30日で消える元データの代わりに、推移を残す軽い記録になります。ここにはプロンプトの文脈を含むtop_promptsとcache_breaksを入れずに、by_projectなどの集計値だけを保存すると、共有時の心配も減らせます。

使う前に知っておきたい制約

残っている記録の分しか集計できない

集計の元は~/.claude/projects/<project>/<session>.jsonlと、その下のsubagents/です。Claude Codeは、これらをcleanupPeriodDaysより古くなったときに自動で削除します。既定は30日、最小は1日です。subagents/のファイルは、親セッションの記録が期限切れになるときに一緒に取り除かれます。ツールの出力やファイルの中身も記録に入るため、保持日数を延ばすとそのぶん平文の履歴が残る点にも注意が要ります。allを指定しても、遡れるのは残っている分だけです。

月をまたいで推移を追いたいときは、レポートのHTMLを定期的に保存しておくと比較できます。

レポートにプロンプトの本文が入る

top_promptsとcache_breaksには、該当するプロンプトの文脈が入ります。出力した例でも、"続けて"のような本文が表示されました。HTMLを共有する前に、機密に当たるプロンプトやプロジェクト名が含まれていないか確認します。

保存先と大きなJSON

HTMLはカレントディレクトリに作られるため、リポジトリの中で実行するとコミット対象に混ざります。.gitignoreにsession-report-*.htmlを足すか、別のディレクトリで実行します。JSONが2MBを超えるときは、top_promptsとcache_breaksを100件に絞ってから埋め込むとSKILL.mdに書かれています。

設定ディレクトリを変えている場合

CLAUDE_CONFIG_DIRでホーム側のファイルの置き場所を変えていると、セッション履歴もそこに移ります。スクリプトの既定の読み取り先は~/.claude/projectsなので、直接実行するなら--dirで場所を渡します。

似た機能との使い分け

/insightsが「どう働いたか」を見るのに対し、session-reportは「何にどれだけ使ったか」の内訳に寄っています。レポートで特定のプロジェクトの消費が突出していたら、原因の切り分けはトークン消費が異常に速いときの原因の切り分け方に進めます。