claude-tapでAIコーディングエージェントの実通信を追う

claude-tapが見るのは画面ではなく通信

liaohch3/claude-tapは、AIコーディングエージェント向けのローカルプロキシ兼トレースビューアーです。CLIをclaude-tap経由で起動するか、ローカルアプリのトランスクリプトを監視し、実際のAPI通信とエージェントの文脈を調べる使い方がREADMEに示されています。対象はシステムプロンプト、会話履歴、ツールスキーマ、ツール呼び出し、ストリーミング応答、トークン使用量、リクエスト間の差分です。

これはエージェントの画面を録画する道具ではありません。どのメッセージやツール定義がリクエストへ入ったか、前のターンから何が変わったかを記録し、挙動の原因を通信単位で追うための道具です。メタデータではPython、MITライセンス、既定ブランチmain、アーカイブ状態falseと記録され、2026年8月16日時点の取得情報には3,140スター、270フォーク、33件のオープンイシューがあります。

複数クライアントを同じ観察面へ置く

READMEが対応クライアントとして挙げるのは、Claude Code、Codex CLI、Codex App、Gemini CLI、Grok Build CLI、DeepSeek Harness、Kimi CLI、Kimi Code CLI、MiMo Code、OpenCode、OpenClaw、Pi、Hermes Agent、Cursor CLI、Qoder CLI、Antigravity CLI、CodeBuddy CLIです。クライアントごとに認証方式と接続先は異なります。Claude CodeではAnthropic API、AWS Bedrock、互換ゲートウェイ、ローカルプロキシ上流を対象にし、Codex CLIではAPIキーまたはChatGPTのOAuthを扱うと説明されています。

Codex AppはフォワードプロキシモードでバックエンドのHTTPとWebSocket本文を捕捉し、Cursorは`cursor-agent`とライブトランスクリプト監視を組み合わせます。Kimi、OpenCode、OpenClaw、Hermesは複数プロバイダーのセッションを想定します。対応表があることは便利ですが、クライアントの更新で通信形式が変わる可能性は残ります。採用時は主に使う一つのクライアントから始め、通常起動、認証エラー、ツール呼び出し、ストリーミング終了までの記録を確認します。

リクエスト差分がデバッグの軸になる

claude-tapの実用的な価値は、隣り合うリクエストを比較できることです。READMEは、どのプロンプト、メッセージ、ツール、パラメーターが変わったのかを特定するデバッグを想定しています。エージェントが同じ指示で違う結果を出した場合、モデルだけを疑うのではなく、システムプロンプトの追加、履歴の圧縮、ツールスキーマの変更、送信パラメーター、途中で得たツール結果を分けて確認できます。

ストリーミング応答は再構成され、トークン使用量も記録対象です。したがって、最終表示だけでは見えない途中の応答や、コンテキストの膨張を調べる材料になります。ただし、トレースを取ることは因果関係を自動で説明することではありません。比較する実行の目的、クライアントの版、上流モデル、作業ディレクトリ、ツール許可を同じ記録に残し、人間が差分と結果を対応付けます。

インストールと最初の観察

必要条件はPython 3.11以上と、追跡したいクライアントです。READMEの推奨手順は`uv tool install claude-tap`、別経路は`pip install claude-tap`です。更新には`claude-tap update`、`uv tool upgrade claude-tap`、`pip install --upgrade claude-tap`が示されています。通常は`claude-tap`でClaude Codeを起動し、`claude-tap --tap-client codex`でCodex CLI、`claude-tap --tap-client gemini -- -p "hello"`でGemini CLIを選びます。`--`の後ろは選択したクライアントへ渡されます。

ライブビューアーは既定で有効で、以前の挙動へ戻す`claude-tap --tap-no-live`も説明されています。最初の確認では、機密性のない作業を一つ実行し、リクエスト本文、ツール定義、ツール結果、ストリーム終端、トークン数がどの順に記録されるかを確認します。失敗時には、クライアント単体、環境変数で指定した上流、プロキシ経由の差を切り分け、トレース自体が原因なのか、上流設定が原因なのかを分けます。

ローカル保存と共有の利便性、その代償

READMEは、各実行がローカルのトレースセッションになり、レビューやアーカイブ用に自己完結したHTMLビューアーへ書き出せると説明します。ホスト型ダッシュボードを必須にせず、手元で一つの成果物を共有できる点は、再現調査やチーム内のレビューに向きます。一般的な認証ヘッダーは記録前に伏せるとも記載されています。

それでも、プロンプト、会話履歴、コード断片、環境変数の一部、ツール結果がトレースへ入り得ます。認証ヘッダーが隠れることを、全ての秘密が消えるという意味に広げてはいけません。保存ディレクトリの権限、HTMLを送る相手、バックアップ対象、保持期間、削除手順を決め、公開用には内容を確認してから共有します。チームの障害報告には生トレースを添付せず、必要なリクエストとマスキング済みの差分だけを切り出す運用が適しています。

上流自動検出とローカルプロキシの関係

Claude Code向けには、`ANTHROPIC_BASE_URL`、`ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`の環境やClaude設定からカスタム上流を自動検出し、特定の宛先だけを変えたいときに`--tap-target`で上書きできるとREADMEにあります。CC SwitchのようなツールがClaude Codeをローカルの`ANTHROPIC_BASE_URL`へ向けている場合も、Claude設定から値を検出し、転送前に通信を記録すると説明されています。

この自動検出は、複数の上流を使う開発者には便利ですが、意図しない接続先を捕捉する余地もあります。環境変数、Claude側設定、ローカルプロキシ、claude-tapの指定がどの順で優先されるかを、使うクライアントごとに確認します。WebSocket本文を扱うクライアントでは、HTTPだけを見て記録が完全だと判断しません。観察対象、転送先、TLS終端、エラー時の挙動を小さなテストで確かめ、業務データを流す前に監査担当へ構成を渡します。

MITライセンスと対応範囲の見極め

claude-tapはMITライセンスです。コードの利用や改変の条件を確認する情報であり、各AIクライアント、モデル提供者、社内データの利用規則を置き換えるものではありません。READMEは、実通信を見られること、ローカルへ保管できること、複数クライアントを横断できることを説明していますが、全てのクライアント版、全ての認証方式、全てのストリーミング形式が将来も同じように動く保証は記載していません。

取得情報のリリース履歴ではv0.1.145、v0.1.144、v0.1.143が並んでいます。更新する際は、現在使うクライアントとプロキシの組み合わせを固定し、認証情報がマスキングされること、リクエスト差分が表示されること、HTML出力の内容が意図した範囲に収まることを確認します。向いているのは、エージェントの挙動を証拠付きで調査したい個人やチームです。機密データを無制限に集約する監視基盤として採用するなら、保存と閲覧の統制を先に設計します。

編集部の結論

claude-tapは、AIコーディングエージェントが実際にどの文脈を受け取り、どのツールを呼び、どの応答を返したかを自分の端末で調べたい開発者に向きます。隣接リクエストの差分、ストリーミング応答、トークン使用量、ローカルHTMLの共有は調査に便利です。ただし、トレースには機密プロンプトや会話、ツール結果が含まれ得るため、保存先と共有範囲を先に決め、対応クライアントごとの転送方式と認証ヘッダーのマスキングを隔離環境で確かめてください。

公式情報源

1. Official README
2. Project repository
3. Release notes