Claude Codeで長いテストやビルドを動かす時、バックグラウンドに回せるのはかなり便利です。
ずっと画面を眺めていなくていい。別の作業を進められる。終わったら結果を見ればいい。
これだけ聞くと最高なのですが、無人運用をしていると少し話が変わります。
「バックグラウンドに回したから、あとはClaude Codeがいい感じに気づいてくれるだろう」と思い込むと、意外と危ないです。私も自動ループを回す時は、ここをかなり慎重に扱っています。
今回はClaude Codeのバックグラウンドbashを、公式docsで確認できる範囲に絞って整理します。
Ctrl+Bでbashを裏に回せる
Claude Codeのinteractive mode docsには、background bash commandsの説明があります。
Bashコマンドをバックグラウンドで走らせる方法は主に2つです。
- 最初からバックグラウンド実行するようClaude Codeに頼む
- 通常のBash実行中に
Ctrl+Bを押してバックグラウンドに送る
tmuxを使っている場合は、tmux側のprefixとぶつかるので Ctrl+B を2回押す必要がある、と公式docsに書かれています。
こういう地味な注意点、かなり大事です。tmux上で「効かないな？」となった時に、原因がClaude Codeではなくキーバインド衝突だったりします。
裏に回ると何が起きるのか
バックグラウンドに回したコマンドは非同期で動きます。
Claude Codeはすぐに背景タスクIDを返し、会話側は次の指示を受け付けられるようになります。つまり、コマンドが終わるまで待たずに先へ進めます。
公式docsで確認できるポイントはこのあたりです。
- 出力はファイルに書かれる
- ClaudeはRead toolで後から出力を読める
- 背景タスクには追跡用の一意なIDが付く
- Claude Code終了時に背景タスクはクリーンアップされる
- 出力が5GBを超えると自動終了し、stderrに理由が残る
5GBで止まるのは、かなり現実的な安全装置ですね。
テストを流したらログが爆発した。開発サーバーが延々と同じエラーを吐いた。そういう時に、何も制限がなければディスクを食い潰してしまいます。
とはいえ5GBは十分に大きいです。普段のテストログでそこまで行くなら、まずログの出し方を疑った方がよいと思います。
Agent SDKではrun_in_backgroundがある
Claude Code Agent SDKのPython referenceを見ると、Bash toolの入力に run_in_background というbooleanがあります。
{
"command": "npm test",
"timeout": 600000,
"description": "Run test suite",
"run_in_background": true
}これを使うと、アプリ側から明示的にバックグラウンド実行を指定できます。
戻り値には shellId が含まれることがあります。背景プロセスを追うためのIDですね。
ここまで見ると、仕組みとしてはかなり整っています。長いコマンドを投げて、IDを受け取り、後でログを読む。簡単ですね。
ただし、ここからが本番です。
「裏で動いている」と「管理できている」は違う
バックグラウンド実行の怖いところは、画面から消えた瞬間に安心してしまうことです。
例えばこんなコマンドを裏に回したとします。
npm run dev開発サーバーなら、これは終わりません。終わらないのが正常です。
ではこれはどうでしょう。
npm testこれは普通は終わるはずです。ですが、テストの中でブラウザが固まったり、外部API待ちになったり、入力待ちのコマンドを呼んでしまったりすると、想定よりずっと長く残ることがあります。
バックグラウンドに回すと会話は進められますが、コマンドが本当に終わったか、失敗したか、待ち続けているかは別途見に行く必要があります。
ここを雑にすると、「裏で動かしたつもりが、実はずっと止まっていた」ということが起きます。無人ループだと特に痛いです。
私は長い仕事ほどrun-reportに寄せる
このブログの裏側では、毎日いくつかの定期タスクを自動で回しています。
その中で長い処理を動かす時は、ただバックグラウンドに投げっぱなしにはしません。進捗をファイルに残すようにしています。
CHECKPOINT: done=296,298,300 next=333こういう行をrun-reportに残しておくと、途中で止まっても再開できます。
「背景タスクが生きているか」だけに頼らず、「どこまで終わったか」を別の永続ファイルに残す。これがかなり効きます。
バックグラウンドbashは便利ですが、プロセス管理の仕組みです。作業の意味までは覚えてくれません。
どの単位が終わったのか。次はどこからなのか。そこは自分で記録した方が安全です。
スケジュールタスクでは復元されないものもある
Claude Codeのscheduled tasks docsには、session-scoped schedulingの制約も書かれています。
その中に、Background Bashとmonitor tasksはresume時に復元されない、という注意があります。
これも大事です。
「Claude Codeをresumeしたら、前に走らせた背景bashも元通り見えるだろう」と思うとズレます。会話やタスクの一部は戻っても、背景で走っていたコマンド自体をそのまま復元するものではありません。
だから、長い作業を本当に無人で継続したいなら、背景bashだけに寄せない方がよいです。
- 作業単位ごとに成果物を書く
- 再開位置をファイルに残す
- 失敗しても次回読めるログを残す
- 外部に反映した処理は、反映済みとして記録する
このあたりをセットにして、初めて「止まっても続きからできる」になります。
Agent viewの背景セッションとは別物です
Claude Codeにはagent viewもあります。
claude agents で複数の背景セッションを管理したり、claude --bg で最初から背景セッションとして起動したりできます。
これはbashコマンドを裏に回す話とは別です。
background bashは、今の会話の中で実行したシェルコマンドを裏に回す仕組みです。
agent viewのbackground sessionは、Claude Codeのセッション自体を背景で動かす仕組みです。
名前が似ているので少し紛らわしいですが、管理したい対象が違います。
- 長いコマンドを待たずに進めたい → background bash
- 複数のClaude Code作業を並列に走らせたい → agent view / background session
この切り分けで見ればOKです。
無効化したい場合も用意されている
背景タスク機能を全部止めたい場合は、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定できます。
組織やチームによっては、裏でプロセスが残ること自体を嫌う場合があります。共有端末、厳しめのCI、監査が必要な環境では、無効化できること自体に意味があります。
便利機能は、禁止できるところまでセットで信頼できます。
まとめ
Claude Codeのバックグラウンドbashは超便利です。
長いテスト、ビルド、開発サーバー起動を待たずに、会話を続けられます。出力はファイルに残り、背景タスクIDで追跡できます。5GB超のログで止まる安全装置もあります。
ただし、「裏に回した」ことと「最後まで管理できた」ことは別です。
無人運用や長い自動化では、背景bashだけに頼らず、run-report、CHECKPOINT、ログ、成果物の再読みに寄せた方が安全です。
Claude Codeに任せるところと、自分で記録するところを分ける。結局ここが一番大事だと思います。
というわけで、長いコマンドはバックグラウンドに回してOKです。ただし、終わったかどうかはちゃんと見ましょう。
コメント