Claude Code の Bash バックグラウンド実行(run_in_background)実装 ― sleepポーリングをやめて監視する3つのハマりどころ【2026】

はじめに / 対象と前提

想定読者は、Claude Code を業務や個人開発で使っている(あるいは導入検討中の)Web エンジニア。ビルドやテスト用サーバーなど「終わるまで待つしかないコマンド」を Claude Code に投げるたびに、エージェントが sleep 5 && ls のようなポーリングを繰り返して無駄にやり取り(ターン)を消費した経験がある人向けに書く。

前提環境は macOS(Darwin)、Claude Code CLI(2026年7月時点の環境で動作確認)、シェルは zsh。

TL;DR

• Claude Code の Bash ツールには run_in_background: true という引数があり、コマンドを裏で走らせたまま次の作業に移れる
• 出力の確認や停止は専用ツール(BashOutput / KillBash 相当)で行う。手動の sleep ポーリングより速く、無駄なターン消費もない
• ただし「セッションが終わってもプロセスは生き続ける」「対話的入力を待つコマンドは固まる」「ログ差分の取得漏れ」の3つのハマりどころがある

手順 / 動かし方

具体例として、npm run dev のような終了しない開発サーバーを起動しつつ、別の作業を並行して進めたいケースを考える。

Claude Code に対しては、こんな指示を出すだけでいい。

開発サーバーをバックグラウンドで起動して、起動ログに error が出ていないか確認してから次のタスクに進んで

このときエージェント側では、概ね次のような Bash ツール呼び出しが発生する(トランスクリプト表示で中身を確認できる)。

{
  "command": "npm run dev",
  "run_in_background": true,
  "description": "Start dev server in background"
}

レスポンスにはバックグラウンドプロセスを指す ID(shell_id 相当)が返る。エージェントはこの ID を使って、必要なタイミングで差分ログだけを取りに行く。

{
  "bash_id": "abc123",
  "filter": "error|Error"
}

ログが落ち着いた、あるいは作業が終わったタイミングで明示的にプロセスを止める。

{ "bash_id": "abc123" }

自分の手元では、これを使うようになってから「ビルドが終わるまで会話が固まる」状態がなくなり、体感のレスポンスがかなり良くなった。特に watch モードのビルドやローカルサーバー起動は、フォアグラウンドで待たせる意味がほぼない。

流れを整理すると以下のようになる。

ハマりどころ

1. セッションが終わってもプロセスは死なない

バックグラウンドで起動したプロセス(特に npm run dev のような開発サーバー)は、Claude Code の会話セッションを閉じても OS 上では動き続ける。翌日また同じポートで起動しようとして EADDRINUSE になり、「あれ、誰がこのポート使ってるんだ」と lsof -i :3000 で犯人探しをする羽目になった。バックグラウンド実行を使ったら、作業の最後に明示的に停止させるところまでを1セットとして扱うのが安全。

2. 対話的入力を待つコマンドは無反応のまま固まる

npm init のようにプロンプト入力待ちが発生するコマンドをバックグラウンドで投げると、出力が全く進まないまま待機し続ける。フォアグラウンド実行なら「入力待ちだな」とすぐ気づけるが、バックグラウンドだと単に「反応がない」ようにしか見えず、原因の切り分けに時間がかかった。バックグラウンド実行は、サーバー起動・ビルド・テスト実行のような非対話コマンドに限定するのが安全側の運用。

3. ログが多いと差分取得のタイミング次第で見落とす

長時間動くコマンドほどログ量が多くなるため、差分ログを取りに行くタイミングが空くと、大量の出力が一気に返ってきてエラーメッセージが埋もれることがあった。エラーだけ拾いたいときは正規表現フィルタで絞り込むようにすると、見落としがかなり減る。全件を毎回読もうとせず、フィルタ前提で設計するのがコツ。

背景・補足

そもそもなぜこの機能がありがたいかというと、AI エージェントが sleep 5 を繰り返すようなポーリングは、その分だけ会話のやり取り(トークン)を消費してしまうから。終了を待つだけの単純ループは特に無駄が大きい。

バックグラウンド実行+完了通知(または差分ログ取得)の組み合わせにすることで、エージェントは「投げっぱなしにして他の仕事を進め、終わったタイミングで報告を受け取る」という、人間の非同期的な仕事の進め方に近い挙動ができるようになる。ビルドやサーバー起動のたびに待たされていたストレスが、地味だが確実に減った。

まとめ

• Claude Code の Bash ツールは run_in_background: true で裏実行でき、専用ツールで監視・停止ができる
• sleep ポーリングをエージェントにやらせるより速くて確実、トークンの無駄遣いも防げる
• 「プロセスが生き残る」「対話コマンドは固まる」「ログ差分の取得漏れ」の3点は運用上気をつけたい
• 開発サーバーやウォッチモードのビルドなど、終わらないコマンドを扱うときに特に効果を発揮する