Claude Codeのai-adoptionプラグインでtoken-doctorを使い利用履歴を診断する
ai-adoptionプラグインのtoken-doctorは、手元のClaude Code履歴からトークンの行き先を診断します。出力ファイル、診断の2段階、プライバシー、task-profileとの違いまで。
ai-adoptionは、手元に残ったClaudeの会話履歴を読んで、トークンの使い方を診断するプラグインです。スキルは2つあり、/token-doctorが支出の行き先を、/task-profileが「自分は何にAIを使っているか」を調べます。
履歴の解析はすべてローカルのディスク上で行われ、API呼び出しも認証も要りません。ここでは/token-doctorを中心に、出力されるファイル、診断の2段階、プライバシーの扱い、結果の読み方を説明します。
token-doctorは何を診断するか
token-doctorは、Claude CodeとCoworkのセッション履歴から、支出の傾向を医師の診断書のような形で出力するスキルです。マーケットプレイスの説明では、見る項目として次の6つが挙がっています。
診断される6つの観点
長さの分布
セッションが何ターンで終わるかの分布です。1〜5ターン、6〜20ターン、と区切って1,000ターン超までのバケットに分けています。
マラソン率
300ターン以上続いたセッションの割合です。READMEは、この300ターンを提供元の組織内分布の95パーセンタイルと説明しています。
サブエージェントの扇形展開
サブエージェントをどれだけ並列に起動しているかを見ます。
モデルの内訳
どのモデルにトークンを使っているかを集計します。
キャッシュの再構築
キャッシュを作り直した回数とコストです。ターン5以降でキャッシュ書き込みが2万トークンを超えた出来事を「遅れて起きるコンテキストの発生」として数えます。
プロジェクト別の健全度
作業ディレクトリごとに、問題なし、マラソン、再構築、ゾンビ(壁時計で4時間以上)、複数該当のいずれかに分類します。
コストは履歴に残ったトークン数に、公開されている料金表のレートを掛けて計算されます。請求書の数字そのものではなく、履歴からの推計です。Codexの履歴もあれば、OpenAIの公開レートで計算されます。
インストールと最初の実行
導入の経路は2つあります。Claude Codeのマーケットプレイスから入れる方法と、リポジトリのinstall.shを使う方法です。
/plugin/pluginのメニューでai-adoptionを探して有効化します。マーケットプレイスのページには「Anthropic verified」の表示があります。リポジトリを手元に取得して入れる場合は、次のコマンドです。
./install.sh ai-adoption動作要件は次のとおりです。
| 項目 | 内容 |
|---|---|
| Python | 内容3.10以上(標準ライブラリのみ、pip installは不要) |
| Claude Code | 内容2.x以上。汎用のサブエージェントとHaikuが使えること |
| Cowork | 内容分析する場合のみ必要。Claude Code CLIだけでも動く |
| OS | 内容macOSが主対象。WindowsはCoworkのパス解決に対応。LinuxはClaude Codeのみ |
入れたら、Claude Codeで次のように呼びます。
/token-doctor「diagnose my Claude habits」「why is my Claude spend so high」「where are my tokens going」といった言い方でも起動します。出力は実行したディレクトリの./out/に置かれます。
診断は2段階で進む
token-doctorは、必ず出る第1段階と、任意の第2段階に分かれています。
token-doctorの流れ
- 1
第1段階: ターミナルに診断書を出す
10秒以内に終わります。履歴を数えて集計し、信号機の色分けやASCIIの棒グラフ付きでターミナルに表示します。
- 2
第2段階: 深掘りを任意で実行する
第1段階の結果を見たうえで、深掘りに進むかを選びます。進むと、コストの大きいセッションなど約14本を選び、Haikuのサブエージェントを並列に走らせます。
- 3
推奨事項のレポートを受け取る
最後に最終レポートが書き出されます。
第2段階で選ばれる約14本の内訳は、コスト最大、ドリップフィード型の最大、マラソン最長、キャッシュ作り直しの多いもの、そして「うまくいっている例」3本です。良い例を混ぜるのは、自分のデータで良い使い方を見られるようにするためとされています。
第1段階の集計には、長さの分布やマラソン率のほか、ゾンビ率(壁時計で4時間以上続いたセッションの割合)、キャッシュ再構築のコスト、再読み込み比率も含まれます。プロジェクト別の健全度は、問題なし、マラソン、再構築、ゾンビ、複数該当の5分類です。
「ドリップフィード型」という語は、深掘り対象の選定基準に出てきます。ただ、リポジトリのREADMEには定義が載っていません。選定の4枠が「コスト最大」「ドリップフィード最大」「マラソン最長」「キャッシュ作り直し最多」と並ぶ構成から、細切れの入力が積み重なって膨らむ型を指す呼び名と推測できますが、確かな意味はわかりません。信号機の色分けも同様で、何が赤や黄になるかのしきい値はREADMEにありません。数値で確かな基準は、マラソンの300ターン(提供元の組織内95パーセンタイル)とゾンビの4時間の2つです。
第2段階では、Haikuのサブエージェントが各セッションを5段階の手順で分類し、1〜2文の診断、きっかけになった場面、習慣の提案、判定を返します。判定は、アンチパターン、混在、良い例の3種類です。
出力ファイルは次のとおりです。
| ファイル | 内容 |
|---|---|
out/sessions.jsonl | 内容セッションごとのトークン使用量、ピーク時のコンテキスト、所要時間 |
out/user-stats.json | 内容長さの分布、マラソン率、キャッシュ再構築、ディレクトリ別の健全度 |
out/hotspots.json | 内容深掘り対象に選ばれた約14本 |
out/payloads/<sid>.json | 内容サブエージェントに渡す入力(トークンの形のみ) |
out/analyses/<sid>.json | 内容セッションごとの診断と習慣の提案 |
out/recommendations.md | 内容最終レポート。続けたい習慣と変えたい習慣、セッション別の表 |
診断結果をClaude Codeの運用に結びつける
診断書の数字は、そのままでは何を直せばよいかを教えてくれません。ここでは、指標と過去記事で扱った設定を結びつけて読む例を示します。以下の対応は編集上の読み方であり、プラグインが出す推奨文ではありません。
- マラソン率が高い場合は、1つのセッションを長く使い続けている可能性があります。圧縮の挙動はidle compactionの止め方としきい値とv2.1.299の自動圧縮にまとめています
- サブエージェントの扇形展開が大きい場合は、並列度の上限や圧縮の設定を見直す余地があります。autoCompactWindowが関係します
- キャッシュの再構築が目立つ場合は、キャッシュ書き込みを寿命別に分けて見るOpenTelemetryの属性で、再構築の発生源を詰められます
- プロジェクトに入れたプラグイン自体の重さが気になるなら、claude plugin detailsでコンテキスト消費を測れます
token-doctorは過去の履歴を一度に振り返る道具です。日々の集計はccusageのようなCLIが向き、リアルタイムの計測はOTelが向きます。診断書は月に一度の健康診断として使うと、日々の集計やリアルタイム計測と役割が重なりません。
プライバシーの扱い
履歴には機密を含む会話があるので、取り扱いを先に確認しておく価値があります。
- 履歴はディスクから出ません。第2段階のサブエージェントに渡るのは、トークン数、ツール呼び出しの名前、ターン番号、120文字のタイトルで、ユーザーのプロンプトやモデルの出力は含まれません
- 第2段階に渡す前と出力する前に、APIキー、トークン、JWT、秘密鍵ブロック、メールアドレス(ローカル部)、電話番号・カード・IBANの形式が正規表現で除去されます
- 定期実行タスクやsdk-cliのサブエージェントなど、自動化由来のセッションは分析から除外されます。除外した件数はフッターに残ります
- READMEは、生成後に高エントロピーの文字列が残っていないか手作業で確認するよう勧めています。正規表現で取りこぼす可能性があるためです
診断書を同僚に見せる場合は、recommendations.mdにプロジェクト名やパスが含まれていないかを先に読んでおくと安心です。
task-profileとの違い
同じプラグインに入っているもう1つのスキルが/task-profileです。token-doctorが「お金がどこへ行ったか」を見るのに対し、task-profileは「どんな仕事にAIを使ったか」を、頻度と成功度、つまずきで分けて見ます。
| 比べる点 | token-doctor | task-profile |
|---|---|---|
| 目的 | token-doctor支出の診断 | task-profile作業の棚卸し |
| 所要時間 | token-doctor第1段階は10秒以内 | task-profile5〜10分(目安) |
| 主な出力 | token-doctor端末の診断書とrecommendations.md | task-profileexplorer.html、profile.csv、スキル提案、コーチングカード |
| 深掘りの担当 | token-doctor任意でHaikuを約14本 | task-profileクラスタごとにHaikuを並列 |
task-profileは約40〜80のクラスタに履歴をまとめ、それぞれをHaikuのサブエージェントが分析します。Haikuを大量に走らせる設計なので、実行にもトークンを使います。支出を調べるために支出が増える点は、先に知っておく価値があります。
つまずきやすい点
- Antigravityのセッションには対応していません。ツールが「利用できません」というメッセージを出して終わります
- Linuxでは、Coworkの分析ができずClaude Codeの履歴のみが対象になります
- 以前
ai-adoptionに含まれていたsession-searchは、別プラグインのsession-toolsに移りました。./install.sh session-toolsで入れます - 出力は常に
./out/に置かれます。リポジトリの中で実行すると、out/がGitの管理対象に混ざります。診断用の別ディレクトリで実行すれば避けられます
まとめ
token-doctorは、履歴から支出の偏りを数字で出し、必要なら深掘りまで進める診断ツールです。まず第1段階だけを走らせ、マラソンとキャッシュ再構築の数字を見るところから始めると、負担が小さく済みます。深掘りに進むかどうかは、その結果と、サブエージェントを走らせるトークンの出費を比べて決められます。
プラグインの提供元はTechWolfのリポジトリです。履歴を読ませるツールなので、導入前にリポジトリの中身を読んで、自分の履歴を扱ってよいかを確かめる手もあります。