Agent Profiler：セッションの時間の行方がわかる Claude Code プロファイラー

Agent Profiler は YeonwooSung による Claude Code プロファイラーで、my-claude-code-mods コレクションの一部です。答えてくれる問いはひとつ、「セッションが遅く感じるとき、時間はどこに消えたのか？」です。各ターンの時間を、モデルの応答待ち、ツールの実行、ブロックするサブエージェント、エンジンのオーバーヘッドに分け、結果を 3 か所に表示します。

• ステータスライン：Claude の作業中にリアルタイムで更新されます。例：model 100% · tools 0% · ▶ model claude-haiku-5-5 12.5s。
• /profile：セッション全体のテキストレポート。/profile turn なら直近のターンだけです。時間のカテゴリ、最初のトークンまでの時間、トークン数、遅いツール、繰り返し読まれたファイル、サブエージェント、短い所見のリストが載ります。
• /profile-pane：進行中のリクエストとツールを見せるライブペイン。/profile-export はセッションを OTLP JSON として書き出します。

この Mod は主張に慎重です。「推論時間」は報告しません。各数値には等級が付きます。measured（ツールの所要時間など Claude Code が渡す値）、observed（Mod がイベントの境界で自分で計った値）、reported（API が報告するトークン使用量）、inferred（残りから計算した値）です。作者の README では Claude Code 2.1.287 以降が必要とされています。

録画では、小さなデモプロジェクトでこの Mod を読み込んだ Claude Code を起動し、README.md を読んでプロジェクトを一文で説明するよう依頼します。ターンの実行中、フッターの上のステータスラインがリアルタイムで進みます。最初は model 92% · tools 0%、続いて model 100% と、実行中のリクエスト ▶ model claude-haiku-5-5 およびその経過秒数です。ターンが終わると /profile を実行します。レポートには、モデル応答待ち 29.0 秒、ツール 5 ミリ秒、最初のトークンまでの時間、入力 82.3k トークン、1 回の Read 呼び出し、そして「モデルの待ち時間がエージェント時間の 100% を占める」という所見が表示されます。

インストールブロックのどの方法でも構いません。いずれも作者自身のマーケットプレイスから直接インストールします。このマーケットプレイスには多数のプラグインがあるので agent-profiler を選んでください。ステータスラインとコマンドは次のセッション開始時に現れます。

モジュール hooks/register.tsx はメモリ上に Profiler オブジェクトを持ち、イベントの境界でデータを渡します。turn.start と turn.complete、turn.step 経由の各モデル呼び出し、tool.call 経由の各ツール、そして classic.PostToolUse から得られる Claude Code 自身のツール所要時間です。tool.call フックは観察するだけです。await next(e) でツールの完了を待ち、結果をそのまま返します。hooks/register.tsx より：

on('tool.call', async ($, e, next) => {
  anonymous += 1
  const id = e.tool_use_id ?? `anonymous-${anonymous}`
  const tool = String(e.tool)
  safe(() => profiler.toolStart(Date.now(), { id, tool, agentId: e.agentId, input: summarizeInput(tool, e as unknown as Record<string, unknown>) }))
  paint($)
  try {
    const answer = await next(e)
    safe(() => profiler.toolEnd(Date.now(), id, toolOutcome(answer)))
    return answer
  } // ...
}).catch(($, e, next) => next(e))

記録のすべてのステップは safe() を通るため、プロファイラー自身のエラーはセッションを壊さず破棄されます。ステータスラインの再描画は 1 秒に最大 2 回です。各ターンの後、Mod は新たに完了したスパンを <outputDir>/<sessionId>/<loadId>-<seq>.otlp.json に書き込み、セッション終了時に残りとセッションのルートスパンを書き込みます。スパン名は GenAI の規約（chat <model>、execute_tool <tool>、invoke_agent <type>）に従います。スパン ID とトレース ID は決定的なので、同じセッションを 2 回送っても同じスパンになります。メモリ上には最大 20,000 件のリクエストとツール呼び出しを保持し、それを超えると完了済みの古いターンから破棄されます。

3 つのオプションが /plugin の設定メニューまたは pluginConfigs にあります。

Jaeger でトレースを見るには、リポジトリの examples/jaeger/docker-compose.yml を起動し、otlpEndpoint を http://localhost:4318 に設定して http://localhost:16686 を開きます。Grafana Tempo も同じ OTLP/HTTP エンドポイントを使えます。

実行する前に、プラグインが実行しうるファイルを確認しました。.claude-plugin/plugin.json、hooks/hooks.json、そして hooks/register.tsx と Jaeger の compose ファイルは全文です。hooks/core/ の 11 モジュールのうち、export.ts、otlp.ts、redact.ts と profiler.ts の入力要約部分は全文を読み、すべてのモジュールでネットワーク、プロセス、ファイル、eval、import()、環境変数の呼び出しを検索しました（該当は register.tsx のみです）。テストファイルは一覧を確認しただけで、中身は読んでいません。package.json、インストールスクリプト、バイナリ、バンドルや minify されたコード、eval、動的 import() はありません。hooks/ のソースにゼロ幅文字や隠し文字はなく、ASCII 以外の文字は █、░、·、⏱ などの表示用のステータス・レポート記号だけです。プロンプトやツール結果にテキストを注入することはありません。

主な所見：

• デフォルトでファイルを書き込みます。 各ターンの後とセッション終了時に $.fs.write を呼び、outputDir を設定しない限り ~/.claude/agent-profiler/<sessionId>/ に書き込みます。これはプラグイン自身のフォルダで、settings.json やシェルのファイルではありませんが、確認なしで書き込まれます。ファイルには所要時間、トークン数、モデル名、ツール名、Read/Edit/Write のファイルパス、各 Bash コマンドのカテゴリ（test や build など）が含まれます。ファイルパスは常にエクスポートされます。プロンプト、Bash コマンド、検索パターンは exportCommandText が有効なときだけエクスポートされます。
• ネットワークは、あなたが選んだ場合のみ。 $.http.fetch は otlpEndpoint が空でないときだけ呼ばれ、同じトレース JSON を <endpoint>/v1/traces に POST するだけです。ホストは入力したものがそのまま使われます。リモートのコレクターを指定すると、ファイルパスと、exportCommandText が有効ならマスク済みのコマンドがマシンの外に出ます。README は、マスクは可能な範囲での対応だと注意しています。
• 環境変数は HOME を 1 つ読みます。 outputDir の ~ を展開するためです。
• ツール呼び出しを横取りしますが、変更はしません。 tool.call と tool.check は観察されてそのまま通され、どちらにも .catch のガードがあります。拒否や書き換えは行いません。claude plugin validate は classic.* フックも .catch なしのゲーティングフックとして挙げますが、実際には next(e) を返す観察用です。validate によると、組織が Claude Code を管理している環境では classic.* フックは動かないため、その環境ではレポートが不完全になる場合があります。
• プロセス、デーモン、モデル呼び出しはありません。 コマンドは実行せず、バックグラウンドサービスもありません。使うのはセッション内のタイマーだけです。
• 任意の外部サービス。 Jaeger や Tempo はトレースを閲覧したいときだけ必要です。compose ファイルは jaegertracing/all-in-one:latest を取得しますが、Mod 自身が実行することはありません。
• ライセンス。 Apache-2.0（リポジトリ直下の LICENSE）。

claude plugin validate はエラーも警告も報告せず、上記のノートだけでした。作者の 11 ファイル・67 件のテストは、Claude Code 2.1.303 上の claude plugin test ですべて通過しました。

macOS 上の Claude Code 2.1.303 で、validate、作者のテスト、デモの録画を確認しました。README によると、作者自身のエンドツーエンド検証は 2.1.280 で行われ、イベントの形は 2.1.292 の型宣言に従っています。ペインとステータスラインはターミナルとデスクトップの Code タブで描画されますが、VS Code のチャットパネルと claude -p では描画されません。/profile のテキストはどこでも動きます。

• ステータスラインやコマンドが出ない。 claude --version が 2.1.287 以降であることを確認し、起動中のセッションにインストールした後は /reload-plugins を実行してください。
• トレースファイルがない。 セッション ID が分かるまで何も書き込まれません。書き込みに失敗するとトーストが 1 回表示されるので、outputDir に書き込めるか確認してください。
• ホットリロード後に数値がリセットされる。 メモリ上の状態はやり直しになりますが、書き込み済みのバッチは古いロード ID の下でディスクに残ります。
• Bash 経由で変更されたファイル。 繰り返し読み取りの検出には見えません。
• モデルサーバー内部の時間（キュー待ち、プリフィル、デコード）は、どのクライアント側ツールでも分けられません。最初のトークンまでの時間にはまとめて含まれます。