この記事ではAIエージェントに特化して解説します。AIエージェント全般は AIエージェントフレームワーク比較2026年版 をご覧ください。
何が起きたか
GitHubプロジェクト「agents-observe」がHacker Newsで注目を集めている。これはClaude Codeのマルチエージェント実行を可視化するリアルタイムダッシュボード。ローカル/リモートで動作するサーバーと、WebSocketでリアルタイム接続するReact製ダッシュボードで構成。フィルタリング、検索、エージェント階層の表示、イベントペイロード表示など、デバッグに必要な全機能を搭載している。
背景と経緯
Claude Codeが複数のサブエージェントを並列実行する際（Claude Codeのベストプラクティス参照）、ターミナルには最終結果のごく一部しか表示されない。サブエージェントの動作は完全に不可視。ツール呼び出しが複雑に絡み合い、深い階層で問題が発生した場合、事後的にログを読むしかない状況が続いていた。オブザーバビリティがないため、エージェントの実際の動作（Bashコマンド実行、ファイル読み書き、grepパターン）と、助言者の要約出力のギャップが埋まらなかった。このニーズに応えるプロジェクトとして登場。
主な機能と仕様
コア機能
- リアルタイムイベントストリーム：ツール呼び出し前後（PreToolUse → PostToolUse）の結果を即座にキャプチャ
- エージェント階層表示：親エージェントから生成されたサブエージェントの関係を視覚化
- フルペイロード表示：コマンド、実行結果、ファイルパスなど完全なイベント情報を展開可能
- 履歴検索と時間軸ジャンプ：タイムラインアイコンをクリックして特定イベントへ移動
- セッション管理：人間が読める名前でセッション保存
アーキテクチャ
Node.js + SQLite"] C -->|"parse & store"| D["SQLite DB
events metadata"] C -->|WebSocket| E["React Dashboard
live update"] E -->|HTTP GET| C F["/observe status"] -->|CLI command| C G["Full payloads"] -->|filtered| E
データフロー：
- Hook層：Claude Codeのイベントをstdinで受け取り、プロジェクト名を付与してPOST
- API層：イベントをパースしてSQLiteに保存。エージェントメタデータ（名前、種類、親子関係）を抽出
- ダッシュボード層：WebSocket経由でリアルタイムイベント購読。REST APIで初期ロード実行
インストール手順と使用方法
プラグイン経由（推奨）
# Claude Codeの組み込みマーケットプレイスから追加
claude plugin marketplace add simple10/agents-observe
# プラグインをインストール
claude plugin install agents-observe
# Claude Codeを再起動
# → 次のセッションで自動的にDockerコンテナが起動
# → http://localhost:4981 でダッシュボードにアクセス可能
開発環境での実行
git clone https://github.com/simple10/agents-observe.git
cd agents-observe
# リポジトリをセットアップしてサーバーを起動
# 詳細は公式ドキュメントを参照
# ダッシュボードへアクセス
# http://localhost:4981
使用可能なCLIコマンド：
| コマンド | 機能 |
|---|---|
/observe |
ダッシュボードURLを開く |
/observe status |
サーバーの健全性確認 |
技術的な詳細
HooksがOTelの代わりに使われる理由
HooksはエージェントアクションについてOTelの代わりに、全体像をキャプチャするために使用される。OpenTelemetryでは見落とされるサブエージェント生成タイミングやメタデータ変化をキャッチできる。リアルタイムフィルタリングで無関係なイベントを即座に除外。
イベント処理フロー
- イベント発生：Claude Code実行中にツール呼び出しやエージェント生成が発生
- Hook実行：observe_cli.mjsがstdinでイベントを受け取る
- フィルタリング：エージェントID、ツールタイプで分類
- Storage：SQLiteに永続化。セッションメタデータ更新
- Broadcasting：購読中のWebSocketクライアント（ブラウザタブ）に配信
- UI更新：イベント追加をローカルキャッシュに反映。デデュプ処理（PreToolUse + PostToolUseを1行に統合）
クライアント側の状態管理
すべてのエージェント状態（ステータス、イベント数、タイミング）はイベントストリームから派生。サーバーは単なるダムストア。これにより：
- キャッシュ不整合がない
- 過去セッション再生可能
- リアルタイム性能が優れている
依存環境と必須要件
| 要件 | 理由 |
|---|---|
| Docker | サーバーはコンテナで動作。ホストの環境汚染を防止 |
| Node.js | Hook実行スクリプトの実行基盤 |
| ポート4981 | API & ダッシュボードのデフォルトバインド |
トラブルシューティング
Dockerが起動しない場合
# Docker Desktopまたはdaemonが実行中か確認
docker ps
# スタックしたコンテナを削除
docker stop agents-observe && docker rm agents-observe
# Claude Code再起動
ポート4981が使用中の場合
# 別プロセスを確認
lsof -i :4981
# 不要なコンテナを削除
docker stop agents-observe && docker rm agents-observe
イベントが取得されない
/observe statusで サーバー動作確認- プラグインが正しくインストールされているか確認
- Claude Codeを再起動
WebSocket切断時の動作
クライアントは3秒ごとに自動再接続。サイドバーに「Disconnected」表示。再接続後にイベントをリフェッチ。
オブザーバビリティがもたらす価値
マルチエージェント作業の可視性
コーディネーターが複数の並列エージェント（code reviewer、test runner、documentation agent）を起動する場合、終了後の結果だけでなく、各エージェントの動作プロセスをリアルタイムで監視。問題の早期発見が可能。
ツール呼び出しは真実
助言者の自然言語出力は要約。実際のBashコマンド、ファイル読み書き、grepパターンといったツール呼び出しこそが真実の記録。本ダッシュボードは両方を表示。
デバッグのタイムトラベル
サブエージェントが不適切なファイル編集や破壊的なコマンド実行をした時、イベントストリームから完全なシーケンスと全ペイロードを追跡。原因特定が容易。
パターン認識
複数セッション履歴の蓄積により、エージェントの癖、好むツール、詰まりやすいポイントが可視化。継続改善のデータベース化。
今後の展望
MIT ライセンスで公開されており、コミュニティによる拡張が期待される。AIエージェントフレームワーク比較でも触れたマルチエージェント開発において、可視化ツールの需要は高まっている。特に以下の方向性が考えられる：
- メトリクス分析：エージェント効率、ツール呼び出し頻度の統計化
- アラート機能：異常なパターン（無限ループ等）の検出
- 複数プロジェクト統合ビュー：組織全体のエージェント活動集約
- AI分析：エージェント動作のボトルネック自動検出
参考リンク
この記事はAI業界の最新動向を速報でお届けする「AI Heartland ニュース」です。
