Claude Code Monitor Tool実践ガイド — ポーリングを捨てイベント駆動でログ監視・デプロイ検知・エラー自動修正を実現する
Claude Codeの自動化には3つのレイヤーがある。Hooksは「Claudeの行動」に、/scheduleは「時計」に、そして2026年4月9日に追加されたMonitor toolは「外部イベント」に反応する。kubectl logsを眺める無駄なポーリングループ、Vercelデプロイの完了をsleepで待つ苦肉の策——Monitor toolはこれらを根本から解決する。本記事では、パラメータ仕様から実務パターン、トークン効率設計まで、実際に動くコード付きで解説する。
Monitor toolとは何か — 3つの自動化レイヤーの位置づけ
Hooks・/schedule・Monitorの三角対比
v2.1.98（2026-04-09）のCHANGELOGに「Added Monitor tool for streaming events from background scripts」と記載されたこの機能は、既存の自動化手段とは明確に異なるレイヤーに位置する。
| Hooks | /schedule | Monitor tool | |
|---|---|---|---|
| トリガー | Claudeのアクション（ファイル保存、コマンド実行） | cron式の時間指定 | 外部プロセスのstdout出力 |
| ユースケース | lint強制、commit前チェック | 定期レポート、バッチ処理 | ログ監視、デプロイ検知、テスト結果の追跡 |
| トークン効率 | アクション発生時のみ | 時間間隔ごとに固定消費 | イベント発生時のみ（待機中ゼロ） |
| 設定場所 | settings.json | CLIコマンド | Claude会話内 or CLAUDE.md |
「外部イベント駆動」という新しい概念
Hooksは「Claudeが何かしたとき」に発火する受動的なフックであり、/scheduleはイベント発生タイミングとのズレが避けられない。Monitor toolは外部プロセスのstdoutをストリーム監視し、出力があった瞬間にClaudeへ通知するイベント駆動ツールだ。ポーリングとの本質的な違いは、トークン消費がイベント発生時のみに限定される点にある。
パラメータ仕様とパーミッション
4つのパラメータ詳解
Monitor toolのパラメータは4つとシンプルだ。
{
"description": "K8s本番Podのエラーログを監視。エラーが検出されたら原因を調査してください",
"command": "kubectl logs -f deploy/api --since=1m | grep -i --line-buffered 'error\\|exception'",
"timeout_ms": 600000,
"persistent": false
}
- description（string, 必須）: Claudeが通知の文脈を理解するための説明文。「エラーが出たら原因を調査してください」のように指示を含めると、検知後の行動精度が上がる
- command（string, 必須）: 実行するシェルコマンド。stdoutの各行が1通知になる
- timeout_ms（number, デフォルト300000）: ミリ秒指定。最大3,600,000（1時間）。デプロイ監視なら600,000（10分）、ログ常時監視ならpersistentを使う
- persistent（boolean, デフォルトfalse）: trueならTaskStopで手動停止するまで永続実行
重要な仕様として、stdoutの200ms以内に到着した複数行は1通知にバッチされる。stderrはファイルに書き出されるがイベントをトリガーしない。パーミッションはBashツールと同じallow/denyパターンが適用される。
なお、Amazon Bedrock、Google Vertex AI、Microsoft Foundryでは利用できない。
実務パターン3選 — すぐ使えるユースケース
パターン1: kubectl logsでエラー検知→自動調査
{
"description": "本番APIサーバーのエラーログを監視中。エラーを検出したら、該当コードを特定し原因を報告してください",
"command": "kubectl logs -f deploy/api-server --since=1m | grep -i --line-buffered 'error\\|exception\\|panic'",
"timeout_ms": 3600000,
"persistent": true
}
--line-bufferedは必須だ。パイプ接続時、grepはデフォルトでブロックバッファリング（通常4KB〜8KB）に切り替わる。これがないと、エラーが発生してもバッファが溜まるまで通知が遅延する。
パターン2: Vercelデプロイログ監視→完了検知→動作確認
{
"description": "Vercelデプロイの進捗を監視中。'Ready'が表示されたらデプロイ完了。curlでヘルスチェックを実行してください",
"command": "vercel deploy --prod 2>&1",
"timeout_ms": 600000,
"persistent": false
}
ここで2>&1を付けているのは、Vercel CLIがステータス情報の一部をstderrに出力するためだ。これがないとデプロイの進捗が見えない。
パターン3: vitest --watchのテスト失敗→自動修正ループ
{
"description": "vitestのwatch実行を監視中。テスト失敗が検出されたら、失敗したテストファイルと該当するソースコードを読み、修正してください",
"command": "npx vitest --watch --reporter=verbose 2>&1 | grep --line-buffered -E 'FAIL|Error|✗'",
"timeout_ms": 3600000,
"persistent": true
}
正直、このパターンが一番気に入っている。コードを書く→テストが落ちる→Claudeが修正する→テストが通る、という流れが完全に自動化される。
トークン効率とフィルタリング設計
ポーリング vs Monitor のトークン消費比較
ポーリング方式で同等の監視を実現する場合のコードを見てみよう。
# ポーリング方式（Bash tool + sleepループ）
while true; do
kubectl logs deploy/api --since=10s | grep -i 'error'
sleep 10
done
この方式では、10秒間隔×5分で30回のBash呼び出しが発生する。イベントがなくてもコンテキストに空の結果が積み上がり、トークンを消費し続ける。Monitor方式ではイベント発生時のみ通知されるため、待機中のトークン消費はゼロだ。実務では70〜90%のトークン削減が期待できる。
grep・awk・sedで通知量を制御する
Monitor toolの鍵はcommand側でのフィルタリング設計にある。Claudeに渡す前にノイズを除去することで、トークン効率とレスポンス精度の両方が向上する。
# フィルタリングの実装例
kubectl logs -f deploy/api --since=1m \
| stdbuf -oL grep -i 'error\|exception' \
| stdbuf -oL awk '{print strftime("%H:%M:%S"), $0}'
grep --line-bufferedの代わりにstdbuf -oLを使う方法もある。stdbufはcoreutilsに含まれるコマンドで、任意のプログラムの出力バッファリングをラインバッファリングに強制できる。grepだけでなくawk、sed、cutなどにも適用できるため、複雑なパイプラインではこちらが汎用的だ。
出力が多すぎるとMonitorは自動停止される（閾値は非公開）。適切なフィルタでノイズを除去しておくことが安定運用の前提になる。
ハマりポイントと設計上の注意
よくあるトラブルと対処法
stderrが拾えない: Monitor toolはstdoutのみを監視する。エラー出力を検知したい場合は2>&1でstdoutにリダイレクトする。
# stderrもキャプチャする
some-command 2>&1 | grep --line-buffered 'error'
パイプのバッファリング問題: パイプで繋いだコマンドはデフォルトでブロックバッファリングになる。これが原因でイベントが数十秒〜数分遅延するケースがある。
# stdbufでラインバッファリングを強制
stdbuf -oL tail -f /var/log/app.log | stdbuf -oL grep 'ERROR'
timeout_msの設定ミス: デフォルトの5分（300,000ms）では、CIパイプラインやデプロイの監視には短すぎることが多い。用途に応じた目安は以下の通り。
- テスト監視: 300,000（5分）〜600,000（10分）
- デプロイ監視: 600,000（10分）〜1,800,000（30分）
- ログ常時監視: persistent: trueを使用
複数Monitor同時実行時の考慮事項
複数のMonitorを同時に起動することは可能だが、通知が同時に到着した場合の処理順序は保証されない。クリティカルな監視は1つに絞るのが安全だ。
また、Bash toolのrun_in_backgroundとの違いも押さえておきたい。run_in_backgroundはコマンド完了時に1回だけ通知するのに対し、Monitorはストリームの各行で継続的に通知する。「完了を待つ」なら前者、「経過を追う」なら後者を選ぶ。
3レイヤー統合 — Hooks × /schedule × Monitorの組み合わせ設計
組み合わせパターン例
3つのレイヤーを組み合わせることで、開発ワークフロー全体をイベント駆動で制御できる。
/scheduleで毎朝9時にデプロイを起動
→ Monitorがデプロイログを監視
→ 失敗検知時にClaudeが自動修正
→ Hooksがcommit前にlint/typeチェックを強制
CLAUDE.mdに方針を記述しておけば、Monitor検知時の行動指針をプロジェクト単位で統一できる。
# CLAUDE.md に追記する例
## Monitor検知時の対応方針
- テスト失敗: 該当ファイルを修正し、ビルドが通ることを確認してから報告
- デプロイエラー: ログの最後の20行を読み、原因を特定。自動修正はせず報告のみ
- 本番エラー: 該当コードを特定し、影響範囲を報告。修正はユーザーの承認後に実施
自動化レベルの段階的引き上げ
いきなり3レイヤーを全部導入する必要はない。まずMonitor単体でvitest --watchやkubectl logsを手動起動してみる。慣れたら/scheduleで定期化し、最後にHooksで前後処理を追加する。この段階的なアプローチが、過剰自動化でデバッグが困難になる罠を避ける現実的な道筋だ。
Monitor toolは「外部イベントへの反応」という、Hooksと/scheduleでは埋められなかった自動化の隙間を埋める。最大の恩恵はトークン効率——ポーリングの無駄な消費をゼロにできる点にある。まずはvitest --watchやkubectl logsなど、日常的に「ターミナルを眺めて待つ」作業から置き換えてみてほしい。3つの自動化レイヤーを適材適所で組み合わせることで、Claude Codeは単なるコーディング補助から、開発ワークフロー全体を駆動するイベント駆動エンジンへと進化する。