Claude Code の Monitor ツール完全ガイド — バックグラウンドプロセスをリアルタイム監視する仕組み

はじめに

Claude Code を使って開発していると、こんな場面に遭遇することはないでしょうか。

• 「CI のジョブが走っているけど、完了したか 5 分おきにブラウザを開いて手動で確認している」
• 「デプロイ後にログを tail -f で流しつつ Claude に別の作業を頼みたいけど、ターミナルが埋まってしまう」
• 「長時間かかるテストスイートの結果を待ちながら、何もできずに時間だけが過ぎていく」

Monitor ツール は、こうした「待ちの時間」を解消する Claude Code のリアルタイム監視機能です。バックグラウンドでプロセスを走らせ、その出力を Claude がリアルタイムに受信して反応する — 会話を中断することなく、長時間のタスクを見守ることができます。

この記事では、以下の内容を解説します。

• Monitor ツールの基本的な仕組み
• パラメータと設定
• Bash run_in_background との違い
• ログ監視・CI ポーリング・ファイル変更検出などのユースケース
• 効果的に使うための実践 Tips

Monitor ツールとは

Monitor ツールは、Claude Code に組み込まれたバックグラウンド監視機能です。Claude が監視用のシェルコマンドを生成し、バックグラウンドで実行しながら、その stdout をリアルタイムにストリーミング受信します。

動作の流れは次のとおりです。

1. ユーザーが監視したい対象を Claude に伝える（例:「CI の完了を監視して」）
2. Claude が監視用のシェルコマンドまたはスクリプトを生成する
3. Monitor ツールがコマンドをバックグラウンドで実行する
4. stdout の各行がイベント通知として Claude にリアルタイムで送信される
5. Claude がイベントを受け取り、報告や対処を行う

ポイントは、監視中も会話は継続できる ということです。Claude はバックグラウンドでイベントを受け取りながら、ユーザーとの対話や他の作業を並行して進められます。

200ms 以内に連続して出力された複数行は、1 つの通知にバッチ処理されます。高頻度の出力でもコンテキストが無駄に消費されにくい設計です。

## パラメータ

Monitor ツールは以下のパラメータを受け取ります。

command

Monitor が実行するシェルコマンドです。パイプやリダイレクトも使えるため、tail -f と grep を組み合わせたフィルタリングなども可能です。

description

通知に付与される説明文です。複数の Monitor を同時に走らせている場合に、どの監視からの通知かを区別するために重要です。具体的な内容を書きましょう。

# 良い例
"本番環境のエラーログを監視中"

# 曖昧な例
"ログ監視"

timeout_ms

デフォルトは 5 分（300,000ms）、最大 1 時間（3,600,000ms）です。指定した時間が経過すると Monitor は自動で停止します。

persistent

true に設定すると、timeout_ms に関係なくセッションが終了するまで監視を継続します。ログの長時間監視や、セッション全体を通じて変更を検出したい場合に使います。

persistent: true は timeout_ms を上書きします。長時間のセッションでは出力量に注意してください。コンテキストウィンドウを圧迫する可能性があります。

## Bash `run_in_background` との違い

Claude Code にはもう 1 つ、バックグラウンド実行の仕組みとして Bash ツールの run_in_background オプションがあります。Monitor とは役割が異なります。

使い分けはシンプルです。

• 結果だけ分かればいい → run_in_background
• 経過をリアルタイムに追いたい → Monitor

たとえば npm install の完了を待つだけなら run_in_background で十分です。一方、デプロイ後のログにエラーが出た瞬間に対処したい場合は Monitor が適しています。

ユースケースと実例

ログ監視

デプロイ後にアプリケーションログを監視し、エラーが発生したら即座に報告してもらうケースです。

tail -n 0 -f /var/log/app/production.log | grep --line-buffered "ERROR\|WARN"

tail -n 0 -f は既存の内容をスキップして新しい行のみを出力します。grep --line-buffered はパイプ経由でもバッファリングせずに行単位で出力するオプションで、Monitor との組み合わせには必須です。

Claude はこの Monitor からエラーログを受け取り、エラーの内容を解析して原因の調査や修正提案を行えます。

CI/PR ステータスのポーリング

GitHub Actions のジョブ完了を定期的にチェックし、完了したら結果を報告するスクリプトです。

while true; do
  status=$(gh run view 12345 --json status -q '.status' 2>/dev/null || echo "unknown")
  echo "$(date '+%H:%M:%S') CI status: $status"
  if [ "$status" = "completed" ]; then
    conclusion=$(gh run view 12345 --json conclusion -q '.conclusion' 2>/dev/null || echo "unknown")
    echo "CI completed: $conclusion"
    break
  fi
  sleep 30
done

30 秒間隔でポーリングし、完了時に結論（success / failure）を出力して終了します。Claude はこの結果を受けて、失敗していればログの確認や修正の提案を自動的に行えます。

ファイル変更の検出

ビルドプロセスの出力ディレクトリを監視し、新しいファイルが生成されたら通知するスクリプトです。

touch /tmp/last-check
while true; do
  changes=$(find ./dist -newer /tmp/last-check -type f 2>/dev/null)
  if [ -n "$changes" ]; then
    echo "変更検出: $changes"
  fi
  touch /tmp/last-check
  sleep 1
done

1 秒間隔でローカルファイルシステムをチェックし、前回チェック以降に更新されたファイルがあれば出力します。ビルド完了の検知やホットリロードの確認に活用できます。

テストの進捗追跡

大規模なテストスイートの実行中に、PASS / FAIL の結果だけをリアルタイムに追跡するケースです。

npm test 2>&1 | grep --line-buffered -E "^(PASS|FAIL|Tests:|Test Suites:)"

テストの全出力ではなく、結果のサマリ行だけをフィルタリングして Monitor に流すことで、出力量を抑えつつ進捗を把握できます。テストが失敗した場合、Claude はすぐに該当するテストファイルを調査して修正に取りかかれます。

実践 Tips

出力量を制御する

Monitor は stdout の各行を Claude に送信するため、出力量が多すぎるとコンテキストウィンドウを圧迫します。grep --line-buffered で必要な行だけにフィルタリングするのが基本です。

# 全ログを流すのではなく、エラー関連のみに絞る
tail -f app.log | grep --line-buffered -i "error\|exception\|fatal"

また、tail -n 0 -f を使えば既存のログ内容をスキップし、監視開始以降の新しい行のみを対象にできます。

ポーリング間隔の目安

監視対象によって適切なポーリング間隔は異なります。

リモートサービスへのポーリングは API のレート制限に注意してください。特に GitHub API は認証なしだと 1 時間あたり 60 リクエストに制限されています。

### 一時的なエラーを握りつぶす

ネットワーク経由のポーリングでは一時的な接続エラーが発生しがちです。Monitor スクリプトが途中で停止しないよう、|| true や 2>/dev/null でハンドリングしましょう。

# ネットワークエラーで止まらないようにする
status=$(curl -s "$URL" || echo "unreachable")

persistent を使い分ける

• ワンショット監視（persistent: false）: CI の完了待ちなど、条件を満たしたら終了する監視
• セッション全体の監視（persistent: true）: ログの常時監視、ファイル変更の継続検出

デフォルトの persistent: false は timeout_ms 経過後に自動停止するため、終了忘れの心配がありません。

grep --line-buffered を忘れない

Monitor と grep をパイプで組み合わせる場合、--line-buffered を付け忘れると grep がバッファリングを行い、リアルタイムに通知が届かなくなります。これは最もよくあるハマりポイントです。

# NG: バッファリングによりリアルタイム通知されない
tail -f app.log | grep "ERROR"

# OK: 行単位で即座に出力される
tail -f app.log | grep --line-buffered "ERROR"

複数の Monitor を走らせすぎない

Monitor は同時に複数実行できますが、それぞれの出力が Claude のコンテキストを消費します。同時に走らせるのは 1〜2 個に抑え、description で区別しやすい名前を付けましょう。

まとめ

• Monitor ツール は Claude Code がバックグラウンドプロセスの stdout をリアルタイムにストリーミング受信する仕組み
• 200ms 以内に連続した出力はバッチ処理され、コンテキストの消費を抑える
• Bash run_in_background が「完了通知型」なのに対し、Monitor は「リアルタイム監視型」
• ログ監視、CI ポーリング、ファイル変更検出、テスト進捗追跡が主なユースケース
• grep --line-buffered でフィルタリング、適切なポーリング間隔、|| true によるエラーハンドリングがベストプラクティス
• 監視中も会話は継続でき、Claude は他の作業を並行して進められる

参考

• Claude Code tools reference — Anthropic Docs
• Claude Code overview — Anthropic Docs