Claude Code Monitorツールの使い方 — WebSocketとログの監視

Claude CodeのMonitorツールは、会話を止めずに裏側で何かを見張り続け、変化が起きたときだけ声をかけてくるツールです。ログの監視やCIステータスのポーリングだけでなく、WebSocketで届くイベントをそのまま受け取ることもできます。v2.1.195で追加されたWebSocketソースは、サーバー側がすでにイベントを配信している場合に、Claudeがポーリング用スクリプトを書かずに直接つなぎに行ける経路です。

Monitorツールは何を監視できるか

Monitorツールの基本形は、Claudeが小さなスクリプトを書いてバックグラウンドで実行し、出力される行を1行ずつ受け取るというものです。次のような依頼に使えます。

• ログファイルをtailしてエラー行が出たら知らせる
• PRやCIジョブのステータスをポーリングし、変化したときだけ報告する
• ディレクトリの変更を監視する
• 実行に時間がかかるスクリプトの出力を追い続ける
• WebSocketのフィードに接続し、届いたメッセージをそのまま報告する

会話は止まりません。監視中も普段通り作業を続けられ、イベントが来たタイミングでClaudeが割り込んで知らせます。監視を止めたいときは、Claudeに解除を頼むかセッションを終了すれば止まります。

WebSocketソースで何が変わるか

サーバーがすでにイベントをプッシュしている場合、Claudeはポーリングスクリプトの代わりにWebSocketを直接開けます。この経路には固有の挙動があります。

• テキストメッセージは1件につき1イベントとして扱われます。複数行にまたがるメッセージでも1件です
• バイナリメッセージはそのまま渡されず、[binary frame, 512 bytes]のようなプレースホルダー行に置き換わります
• 1MiBを超えるメッセージを受け取ると監視は終了します。大きなペイロードが想定されるフィードでは、あらかじめ絞り込まれた小さいフィードを選ぶ必要があります
• ソケットが閉じると監視は終了し、Claudeはクローズコードを受け取ります

WebSocketを使うときはcommandの代わりにwsパラメータを渡します。1回のMonitor呼び出しでcommandとwsを同時に指定することはできません。wsは次の2つのフィールドを持ちます。

timeout_msとpersistentはコマンド版と同じ挙動です。persistentを指定しない限り、監視は期限で終了します。TaskStopを使えば早期にキャンセルできます。この機能はClaude Code v2.1.195以降が必要です。

WebSocketを開く操作は承認プロンプトの対象です。auto modeが有効なときは分類器が代わりに判断します。ただしこのプロンプトには「同じホストへの以後の確認を省略する」という選択肢がありません。ドメイン単位の許可ルールを一度作って終わり、という運用はWebSocket接続では成立しない設計です。

コマンド実行の権限判断はBashと同じ

Monitorがコマンドを実行するときは、Bashと同じ権限ルールが適用されます。Bash用に設定したallow/denyパターンはMonitorにもそのまま効きます。ルールの書き方自体はClaude Codeの/permissionsコマンドで扱っている内容と変わりません。たとえばBash(npm run *)という許可ルールは、名前にBashと書かれていてもMonitorのコマンド実行にそのまま適用されます。npm run buildの出力をMonitorで監視する設定を書くときも、Bash側ですでに許可済みのパターンを二重に書き直す必要はありません。一方でフックのmatcherフィールドは、このToolName(specifier)形式ではなく裸のツール名を使うため、Monitor向けのフックを書くときは括弧書きのパターンではなくMonitorという名前そのものを指定します。

auto modeが有効なときの扱いには注意が必要です。Monitorという名前そのものを対象にした広い許可ルールは、auto modeが他の広い許可ルールと同様に一時的に外します。結果として、分類器はMonitorのコマンドもBashのコマンドと同じ基準で審査します。「Monitorを全部許可」というルールを書いても、auto mode下では素通りにはなりません。分類器がコマンドを1つずつ評価する仕組みはClaude Codeのauto mode分類器は何を止めているかで詳しく扱っています。

このログファイルを監視して、ERRORという行が出たらすぐ教えて

メモリー上限はいつからMonitorにも及ぶか

Linux・WSLではCLAUDE_CODE_TOOL_MEMORY_LIMIT(v2.1.233以降)でBash・PowerShellが使えるメモリーの上限を設定できます。Monitorのコマンドがこの上限に含まれるようになったのはv2.1.246からで、それより前のバージョンではMonitorのコマンドは上限の外で動いていました。暴走したビルドが1つ、セッション全体のメモリーを食いつぶす事故を防ぐための仕組みで、いまはMonitorも同じセッションの1コマンドとして数えられます。

CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE(v2.1.246以降)を使うと、上限から除外するプロセスの種類をカンマ区切りで指定できます。all-newを指定すると、Bash・PowerShell・Monitorのコマンドだけが上限の対象になり、それ以外の種類(MCPサーバーやLSPプロセスなど)は対象外になります。逆にnoneを指定すればすべての種類が上限の対象です。この3つのツールについては、除外リストに何を書いても上限の対象から外れません。

Monitorが使えない環境

Monitorツールは、Amazon Bedrock・Google Cloud's Agent Platform(旧Vertex AI)・Microsoft Foundry経由のセッションでは利用できません。DISABLE_TELEMETRYまたはCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定している場合も同様に使えなくなります。テレメトリーを絞る設定をしているチームは、Monitorも一緒に無効化されている可能性を意識しておくとよさそうです。

プラグインの側からMonitorを起動する経路もあります。プラグインは監視をあらかじめ宣言しておき、プラグインが有効化されたタイミングで自動的に監視を開始できます。ユーザーが都度Claudeに頼まなくても、プラグイン導入時点で監視が立ち上がる運用です。

Ctrl+Bのバックグラウンド実行とは何が違うか

Claude CodeにはCtrl+Bで長時間コマンドを裏に回す、別のバックグラウンド実行の仕組みもあります。どちらも会話を止めずに何かを走らせ続ける点は同じですが、主導権と反応のタイミングが違います。使い分けはClaude Codeバックグラウンド実行の内容と合わせて見ると分かりやすくなります。

エラー監視や状態変化への即応が目的ならMonitor、処理を裏に逃がして自分のペースで確認したいならCtrl+Bのバックグラウンド実行、という使い分けになります。裏に送ったビルドの出力をさらにMonitorで監視する、という組み合わせも可能です。

よくある質問

Monitorを途中で止められますか

Claudeに監視の解除を頼むか、セッションを終了すれば止まります。専用のキャンセルコマンドを覚える必要はありません。

persistentを指定すると何が変わりますか

timeout_msで決まる期限が来ても監視が終了しなくなります。WebSocketでもコマンド実行でも同じ挙動で、TaskStopで明示的にキャンセルするまで動き続けます。

protocolsは必須ですか

任意です。サーバー側がサブプロトコルのネゴシエーションを要求する場合にだけ指定します。指定しない接続も可能です。

auto modeでも確認は省略できますか

プロンプト自体は分類器が判断しますが、「このホストは以後確認しない」という設定はWebSocket接続には存在しません。ドメインを都度許可リストに追加する運用とは別の確認フローだと考えておくと安全です。

まとめ

Monitorツールは、ログの監視からWebSocketの購読まで、Claudeが会話を止めずに変化を待ち受けるための仕組みです。コマンド実行はBashと同じ権限判断を受け、v2.1.246以降はメモリー上限にも組み込まれています。Bedrock・Google Cloud's Agent Platform・Microsoft Foundryでは使えず、テレメトリーを絞る環境変数を設定していても無効になる点は覚えておく価値があります。エラーへの即応にはMonitor、処理を裏へ逃がすだけならCtrl+Bのバックグラウンド実行、と場面で使い分けると迷いません。既存のBash向け許可ルールをそのまま流用できる設計なので、Monitorを使い始めるために権限設定を書き直す手間はかかりません。