Claude Codeのブラックボックスを解消する──devtools・OpenTelemetry・cmuxで内部動作を可視化する

Claude Codeを使い込んでいると、ある種の「もやもや」が蓄積されてきます。処理が長時間続いているとき「いったい何をやっているのか」「このまま待つべきか止めるべきか」が分からない。サブエージェントが並列で動いているのに、どれが詰まっているか特定できない。課金明細を見て「なぜこんなにコストがかかったのか」が追えない。

これらはすべて、Claude Codeが内部動作を十分に見せてくれないことに起因します。ターミナルには「Read 3 files」「Searched for 1 pattern」といった要約しか表示されず、実際に何をどれだけ処理したかは見えません。

本記事では、この「ブラックボックス問題」に対応する3種類のアプローチを比較します。claude-devtools（ローカルログの可視化）、OpenTelemetry連携（外部観測基盤への送信）、cmux（複数セッション管理）の特徴と使いどころを整理します。

3つのアプローチを俯瞰する

まず全体像を把握するために比較表を示します。

「今すぐ何が起きているか調べたい」ならclaude-devtools、「チームで継続的に改善したい」ならOpenTelemetry、「複数エージェントを並列で動かしている」ならcmuxが出発点になります。

claude-devtools──「なぜそのトークン数になったか」が分かる

claude-devtoolsは「The missing DevTools for Claude Code」を謳うデスクトップアプリです。Claude Codeが~/.claude/に保存するJSONLログを読み取り、ブラウザの開発者ツールのようなUIで内容を再構築します。

最大の特徴はAPIキー不要・Claude Code本体への変更なしで動く点です。ローカルのログファイルを読むだけなので、外部への通信は一切発生しません。

インストール方法

brew install --cask claude-devtools

docker compose up
# → localhost:3456 でアクセス

Linux（AppImage / .deb / .rpm）およびWindowsの.exeインストーラーもGitHubから入手できます。

主な機能

① Context Reconstruction（コンテキスト内訳）

ターン（1回のやり取り）ごとに、トークン消費を7カテゴリに分解して表示します。

この内訳を見ることで「入力トークンの約40%がファイル読取結果だった」「CLAUDE.mdが想定以上の比重を占めている」といった事実を数値で把握できます。実際にこの可視化を利用してCLAUDE.mdを約30%削減し、コストを下げた事例が報告されています。

② Compaction Visualization（コンパクション可視化）

コンテキスト圧縮（コンパクション）の境界を検出し、圧縮前後のトークン変化を可視化します。「いつコンパクションが走ったか」「どの程度圧縮されたか」を把握することで、コンテキスト管理の効率化に役立てられます。

③ Tool Call Inspector（ツール呼び出し検査）

ターミナルでは「Read 3 files」としか表示されなかった操作が、claude-devtoolsでは以下のように詳細表示されます。

④ Team & Subagent Trees（サブエージェントツリー）

Taskツール（サブエージェント）の呼び出しを独立した実行ツリーとして展開します。6並列のうち1つだけが異常にトークンを消費していたケースや、サブエージェントが同じファイルを繰り返し読んでいたケースも、このビューで即座に発見できます。各サブエージェントのトークン量・コスト・所要時間が個別に表示されます。

⑤ Notification Triggers（アラート）

正規表現ベースのアラートを設定できます。たとえば.envファイルへのアクセスや、特定のトークン数を超えた場合に通知するデフォルトルールが用意されています。

OpenTelemetry連携──メトリクスで定量改善する

Claude CodeはOpenTelemetry（OTel）プロトコルによる外部監視を公式サポートしています。メトリクスとイベント（ログ）をGrafana・Datadog・Prometheusなどの既存観測基盤に送ることができます。

claude-devtoolsとの決定的な違いはリアルタイム性と継続監視です。開発中の「今のセッション」を事後分析するのがdevtools、数週間にわたるコスト推移やチーム全体の利用状況を定量的に監視するのがOTelという使い分けになります。

OpenTelemetryの詳細設定についてはClaude Code OpenTelemetry連携ガイドを参照してください。ここでは可視化という観点で要点を整理します。

有効化の基本設定

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

取得できるメトリクス一覧

取得できるイベント一覧

主要バックエンドとの接続

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-north-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic [YOUR_BASE64_TOKEN]"

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus
# Claude Codeがlocalhost上にPrometheusエンドポイントを公開する

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

チームIDの付与（マルチチーム環境）

複数のチームで共有の観測基盤を使う場合、リソース属性でチームを識別できます。

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

JSOLログを独自解析する──トレースの自作

公式OTelではトレースが出ないため、より深い分析が必要な場合はJSONLログの直接解析が有効です。

~/.claude/projects/配下に、プロジェクトパスから生成したディレクトリ名（非英数字を-に置換）があり、その中にセッションごとの.jsonlファイルが保存されています。

~/.claude/
├── projects/
│   └── -Users-me-myproject/       # CWDのパス（記号→"-"変換）
│       ├── <session-uuid>.jsonl    # セッションログ
│       └── sessions-index.json    # メタデータ
└── settings.json

JSONLの各行にはtype（user/assistant/system）、timestamp、usage（input_tokens等）、message.content（tool_useとtool_resultを含む配列）が含まれています。

このJSONLをDuckDBやPythonで集計することで、「セッション内の130回のツール呼び出しのうちBashが90回、サブエージェント待機が20回だった」「待機は回数が少ないのに総実行時間で支配的だった」といった分析が可能になります。

-- tool_nameごとの呼び出し回数を集計
SELECT
  json_extract_string(content_item, "$.name") AS tool_name,
  COUNT(*) AS call_count
FROM (
  SELECT unnest(
    json_extract(message, "$.content")::JSON[]
  ) AS content_item
  FROM read_json_auto("~/.claude/projects/**/*.jsonl")
  WHERE type = "assistant"
)
WHERE json_extract_string(content_item, "$.type") = "tool_use"
GROUP BY tool_name
ORDER BY call_count DESC;

cmux──複数セッションを「待つだけ」から「管理する」へ

Claude Codeを並列で複数動かすケースが増えるにつれ、「どのセッションが詰まっているか」「どれが入力待ちになっているか」の把握が課題になります。ここでcmuxが登場します。

ただし「cmux」という名前のツールが2種類存在します。用途が全く異なるため区別して把握してください。

manaflow/cmux──セッション観測に特化したターミナル

対象: macOSのみ

manaflow/cmuxはGhosttyをベースにしたネイティブターミナルアプリです。複数のClaudeセッションを同時実行する際、「どのセッションが注意を必要としているか」をサイドバーで一覧管理できます。

brew tap manaflow-ai/cmux
brew install --cask cmux

craigsc/cmux──gitワークツリーのライフサイクル管理

対象: 全OS

craigsc/cmuxはgitワークツリーのライフサイクルを管理するシェルスクリプトです。複数のClaudeエージェントを同一リポジトリで並行動作させる際、ブランチの競合を防ぐためにワークツリーを活用します。

gitワークツリーについてはClaude Code worktreeガイドも参照してください。

curl -fsSL https://github.com/craigsc/cmux/releases/latest/download/install.sh | sh

# 新しいワークツリーを作成してClaudeを起動
cmux new feature/my-feature

# 既存のワークツリーで作業を再開
cmux start feature/my-feature

# アクティブなワークツリーの一覧表示
cmux ls

# メインブランチへのマージ
cmux merge feature/my-feature

# ワークツリーとブランチを削除
cmux rm feature/my-feature

claude-devtoolsの活用パターン

claude-devtoolsで何が見えるかを具体的なシナリオで整理します。

シナリオ①：「簡単な修正のはずが50万トークン超になった」

Context Reconstruction（コンテキスト内訳）ビューを開くと、ツールI/Oカテゴリが全体の60%以上を占めていることに気づきます。Read・Grep・Bashの実行結果がコンテキストを圧迫していた場合、Claude Codeに「このファイルはすでに確認済み。再度読み込まないで」といった指示をCLAUDE.mdに追加することで次回から削減できます。

シナリオ②：「6並列のサブエージェントが終わらない」

Subagent Treesビューを開くと、6つのサブエージェントのうち1つがトークン消費数で突出していることが分かります。そのブランチをドリルダウンすると、同じファイルを繰り返し読み込んでいるツール呼び出しのパターンが見つかります。ループの原因が「ファイルの変更が検知できない」であれば、Hooksで変更通知を明示的に渡す設計が有効です。

シナリオ③：「CLAUDE.mdが重すぎる」

CLAUDE.mdカテゴリのトークン比率が全体の30%を超えている場合、内容の見直しが必要です。実際にCLAUDE.mdのトークンを30%削減してコストが下がった実例があります。コンパクションビューと合わせて、「CLAUDE.mdを読んだ直後にコンパクションが走っている」パターンも確認できます。

Notification Triggersの設定例

claude-devtoolsのアラート機能を使うと、問題のあるパターンを自動検知できます。

SSH Remote Sessions機能

claude-devtoolsはSSH経由でリモートマシンのClaude Codeセッションも同じUIで検査できます。クラウド上のVMや開発サーバーで動かしているセッションを、ローカルのclaude-devtoolsから確認する使い方が可能です。

# 環境変数でリモートのCLAUDE_ROOTを指定
CLAUDE_ROOT=user@remote-host:/home/user/.claude claude-devtools

OpenTelemetryダッシュボードの構築

OTelを有効化してGrafanaと接続したあとの、実用的なダッシュボードの作り方を整理します。

よく使うGrafanaパネル:

JSONLログの詳細解析──DuckDBで深掘りする

claude-devtoolsとOTel以外に、DuckDBを使ったJSONL直接解析も強力な選択肢です。DuckDBはJSONファイルをそのままSQLで集計できるため、特別なインストールが不要で高速に分析できます。

# インストール
pip install duckdb

# セッション別コスト集計
python3 -c "
import duckdb
conn = duckdb.connect()
result = conn.execute("""
  SELECT
    json_extract_string(message, '$.model') AS model,
    SUM(CAST(json_extract(message, '$.usage.input_tokens') AS INTEGER)) AS input_tokens,
    SUM(CAST(json_extract(message, '$.usage.output_tokens') AS INTEGER)) AS output_tokens
  FROM read_json_auto('$HOME/.claude/projects/**/*.jsonl')
  WHERE type = 'assistant'
    AND json_extract(message, '$.usage') IS NOT NULL
  GROUP BY model
  ORDER BY input_tokens DESC
""").fetchall()
for row in result:
    print(row)
"

SELECT
  json_extract_string(item.value, "$.name") AS tool_name,
  COUNT(*) AS call_count,
  AVG(LENGTH(json_extract_string(item.value, "$.input")::TEXT)) AS avg_input_size
FROM read_json_auto("~/.claude/projects/**/*.jsonl"),
  LATERAL UNNEST(
    json_extract(message, "$.content")::JSON[]
  ) AS item(value)
WHERE type = "assistant"
  AND json_extract_string(item.value, "$.type") = "tool_use"
GROUP BY tool_name
ORDER BY call_count DESC;

このクエリでツール別の呼び出し回数と平均入力サイズが分かります。「Readツールの平均入力サイズが突出して大きい」なら不要なファイル全体読み取りが問題、「Bashが圧倒的に多い」ならコマンド実行の最適化が効果的です。

その他のコスト・トークン分析ツール

claude-devtools・OTel・cmux以外にも、用途に特化した分析ツールが充実しています。

コスト管理の詳細な方法についてはClaude Codeコスト管理ガイドも参照してください。

状況別の選択ガイド

どのツールを選ぶかは「何を知りたいか」によって変わります。

個人の開発環境ではclaude-devtools + ccusageの組み合わせが最もコスト・設定の手間のバランスが良いです。チーム開発ではOpenTelemetryを基盤に置き、devtoolsを個別セッションのデバッグ補助として使う形が効果的です。

よくある質問

まとめ

Claude Codeのブラックボックス問題に対応するツールは、用途によって明確に分かれます。

claude-devtoolsはローカルログを7カテゴリに分解し、トークンの使われ方を可視化します。「なぜこのコストになったか」「どのサブエージェントが詰まっていたか」を事後に分析する用途に最適です。導入コストが低く（Homebrew 1コマンド）、外部通信なしで始められます。

OpenTelemetry連携はGrafanaやDatadogなどの既存観測基盤にメトリクスを送り、継続的な定量改善を支援します。チームでの利用やコスト管理の自動化には欠かせません。ただしトレース出力は非対応な点に注意が必要です。

cmuxは複数セッションの並列運用を支援します。macOS向けのmanaflow/cmuxはどのセッションが入力待ちかを可視化し、全OS対応のcraigsc/cmuxはワークツリーを使ったブランチ競合を防ぎます。

まずはclaude-devtoolsを入れて自分のトークン内訳を確認することをおすすめします。多くの場合、CLAUDE.mdやファイル読み取りが想定以上の比重を占めていることに気づくはずです。その改善だけで、コストと速度の両方を改善できます。

サブエージェントの活用についてはClaude Code サブエージェントガイド、全体的なClaude Codeの使い方はClaude Code完全ガイドも参照してください。