Claude Codeバックグラウンド実行 — Ctrl+Bで長時間コマンドを裏に回す
Claude CodeでビルドやテストをCtrl+Bで裏に回し、会話を止めずに進める方法と、30分・2時間・5GBといった停止条件、無効化の手順を解説します。
Claude Codeは実行中のBashコマンドをCtrl+B一つで裏に回し、ビルドやテストを走らせたまま次の指示を出せます。出力は自動でファイルに書き出され、Claudeが完了後にReadツールで拾い直すので、npm run buildが終わるのをターミナルの前で待つ必要がありません。webpackやvite、jest、開発サーバーのような数分単位のコマンドで特に効きます。
裏に回したコマンドは放置しても永遠には残らず、時間や出力量で止まります。この記事では、裏へ回るきっかけと止まる条件、無効にする設定を扱います。Claude Code v2.1.287の実機の出力と、公式docsで確かめた内容です。
裏に回るきっかけは3つある
コマンドがバックグラウンドへ移るきっかけは、Claudeへの指示、Ctrl+B、タイムアウトの3通りです。どれで移ったかによって、制限時間の数え方が変わります。
どの経路で裏に回ったかで制限時間が変わる
Claudeが最初から裏で起動
「バックグラウンドで実行して」と頼むと、Claudeはrun_in_backgroundを付けて起動します。時間制限は既定30分で、Claudeがtimeoutを渡せば最大2時間まで延びます。
途中から裏へ移した
手前で動いていたコマンドをCtrl+Bで移した場合も、タイムアウトで自動的に移った場合も、移した時点から30分です。
Ctrl+Bはキー1つで済むので、走らせてみて長引いたコマンドに向きます。tmuxを使っている場合はCtrl+Bがtmuxのプレフィックスキーと衝突するため、2回連続で押す必要があります。1回目はtmuxが受け取り、2回目でClaude Codeに届きます。ほかのキーとの衝突はClaude Codeショートカット一覧で確認できます。
> npm run build を実行して
# 実行中に Ctrl+B(tmux利用時は2回)を押すとバックグラウンドへ移行裏に回ったあともClaudeは新しいプロンプトに応答し続けます。ビルドの完了確認だけを最後にまとめて行う運用も組めます。
裏のコマンドはどう管理されるか
Ctrl+Bを押すと、Claude Codeはそのコマンドを非同期実行に切り替え、バックグラウンドタスクのIDを返します。標準出力と標準エラーはファイルに書き出され続け、Claudeが後からReadツールで読みます。IDは追跡と出力の取得に使われるので、複数のコマンドを同時に裏で走らせても混ざりません。実行中のタスクの一覧と停止は/tasksから行えます。
出力はファイルに書かれ、会話には表示されません。状況を知りたいときはClaudeに尋ねるか、/tasksで見ます。/tasksから止めたタスクは、Claudeがそれ以上待たずに次の作業へ進みます。
裏に回す価値が高いのは、完了まで時間がかかり、途中経過をAIが逐次確認する必要のない処理です。
| 用途 | 向き不向き | 理由 |
|---|---|---|
| ビルド・バンドル(webpack / vite) | 向き不向き◎ | 理由数十秒〜数分の待ち時間を会話の継続に回せる |
| テストスイート(jest / pytest) | 向き不向き◎ | 理由完了後にログを読ませて結果を判定できる |
| 開発サーバー | 向き不向き◎ | 理由起動したまま別のファイル編集を進められる |
| 標準入力を待つコマンド | 向き不向き△ | 理由入力待ちで止まったままになりやすい |
数秒で終わるlsやgit status | 向き不向き✕ | 理由切り替えの手間のほうが大きい |
裏のコマンドはいつ止まるか
止まる条件は4つあり、それぞれ対象が違います。
バックグラウンドコマンドの止まり方
時間制限
30分
裏に入った時点から数える。Claudeが起動した場合は最大2時間
出力量
5GB
超えると自動終了し、理由がstderrに残る
メモリ逼迫
アイドル30分
macOS・Linuxのみ。v2.1.193以降
サブエージェント
実行終了まで
フォアグラウンドのサブエージェントが起動した場合
時間制限に達すると、Claude Codeはコマンドを止めます。ClaudeにはBackground command "<説明>" was stopped after reaching its background time limitという通知が渡ります。Claudeはもっと長いtimeoutを付けて再起動できます。制限を伸ばしたいときはBASH_DEFAULT_TIMEOUT_MSを1800000より大きくすると、30分の既定値がその値に置き換わります。最大の2時間はBASH_MAX_TIMEOUT_MSを7200000より大きくすると引き上げられます。どちらも短くする方向には働きません。BASH_DEFAULT_TIMEOUT_MSは手前で動かすコマンドの既定タイムアウトでもあるので、1800000より大きくすると、手前のコマンドも自動で裏へ移るまでその時間だけ待ちます。7200000より大きくした場合も、最大の2時間が同じように引き上がります。このバックグラウンド向けの時間制限はv2.1.285で入りました。
メモリ逼迫による停止は、OSが危険水準のメモリ逼迫を通知したときに、セッションが30分以上アイドルでターンもサブエージェントも動いていない場合にだけ起きます。作業中のセッションは巻き込まれません。止めたくなければCLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAPを1にします。この仕組みはv2.1.193で入りました。v2.1.274より前は軽度の逼迫でも止まりましたが、いまは危険水準のときだけです。デバッグログには止めた理由や、逼迫が起きても止めなかった理由が残ります。
サブエージェントが起動したコマンドは扱いが違います。フォアグラウンドのサブエージェントが起動したものは、そのサブエージェントの実行が終わった時点で終了します。成功・失敗・中断のどれでも同じです。メインの会話やバックグラウンドのサブエージェントが起動したものは、最終応答のあとも、終了するか停止されるか時間制限に達するまで動き続けます。
以前は、サブエージェントの裏コマンドに60分で止まる上限があり、CLAUDE_SUBAGENT_BG_SHELL_MAX_MSで調整できました。この変数はv2.1.260で削除され、いまは設定しても何も起きません。さらにv2.1.218より前は、Ctrl+Bで手動バックグラウンド化したコマンドには回収ルールが及ばない経路がありました。v2.1.218で、ほかの経路と同じ上限がかかるようになっています。古いバージョンで運用しているなら、この差が挙動の違いの原因になりえます。
タイムアウトしたコマンドも自動で裏へ移る
Ctrl+Bを押さなくても、Claudeが実行したコマンドがタイムアウトに達すると、Claude Codeは止めずにバックグラウンドへ移します。タイムアウトの既定は2分(BASH_DEFAULT_TIMEOUT_MSの既定値120000ミリ秒)で、Claudeが必要に応じて呼び出しごとにtimeoutを渡します。利用者が呼び出しごとに設定する必要はありません。
ただしsleepで始まるコマンドは自動で移らず、タイムアウトで停止します。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1にした場合や、bareモードで起動した場合も、自動バックグラウンド化は無効になって、タイムアウトで止まります。
移ったときの結果には、Command did not complete within its 120s timeout and was moved to the backgroundのような文言が付きます。続けて、タスクIDと出力ファイルのパスが示されます。秒数は適用されたタイムアウトの値です。移されたコマンドの中のcd・pushd・popd・chdirは、セッションの作業ディレクトリに反映されません。結果にその旨のメッセージが付くので、Claudeは実際には起きていない移動を前提に動かずに済みます。
セッションごと裏に回すと何が続くか
Claude Codeを終了すると、実行中のバックグラウンドタスクは通常そこで片付けられます。セッション自体を裏に回した場合は別で、動いているシェルコマンドやバックグラウンドのサブエージェントはそのまま引き継がれます。ただしMonitorは引き継がれず、停止します。
セッションを裏に回すとき
- 1
裏に回す
/background(エイリアス/bg)を実行します。/bg テストスイートを実行して失敗を直してのように指示を添えると、もう1つ指示を出してから裏に回せます。起動時から裏にしたいときはclaude --bgで、IDを返してすぐ戻ります。 - 2
終了時のダイアログで選ぶ
実行中の作業がある状態で終了しようとすると、
Background work is runningというダイアログが出ます。Move to background and exitを選ぶと、/backgroundと同じ扱いで裏へ回り、シェルに戻れます。agent viewを無効にしていると、この選択肢は表示されません。 - 3
あとから見に行く
claude agentsが裏のセッションの一覧です。claude attach <id>で開き直し、claude logs <id>で直近の出力を読み、claude stop <id>で止められます。
引き継ぎを避け、実行中の作業を止めたい場合は、CLAUDE_DISABLE_ADOPTを1にします。←や/backgroundで裏に回す前にClaude Codeが確認を求め、了承すると引き継がれるはずだった作業を止めてから回します。スクリプトから操作する方法は、claude agents --jsonでバックグラウンドセッションを操作するで扱っています。
v2.1.287でclaude --helpを見ると、裏に関するオプションとサブコマンドは次のとおりです(抜粋)。
$ claude --version
2.1.287 (Claude Code)
$ claude --help
--bg, --background Start the session in the background and return immediately.
Prints the id that `claude attach`, `logs`, `stop` and `rm` take; ...
agents [options] Manage background agents
attach <id> Open a background session in this ...
logs <id> Print a background session's recent ...
stop|kill <id> Stop a background session. ...裏のコマンドを丸ごと使わせない
CI環境や検証でバックグラウンド実行そのものを止めたいときは、環境変数CLAUDE_CODE_DISABLE_BACKGROUND_TASKSを1にします。Bashとサブエージェントのrun_in_background、自動バックグラウンド化、Ctrl+Bが全部止まります。個別の停止条件だけ外したい場合は、前節のCLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAPなどを使い分けます。ほかの変数との関係はClaude Code環境変数リファレンスにあります。
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claudeバックグラウンド実行を残したまま、動いているサブエージェントをClaudeに定期確認させる方法もあります。サブエージェントの確認間隔の設定を参照してください。
出力が長いときと-p実行での扱い
裏で動くコマンドの出力は、いったん作業用ファイルに流れ続け、ClaudeがReadツールで読みます。Bashツールの結果としてClaudeに返る量には上限があり、コマンドの終了後に読み戻す出力は約3万文字までがそのまま渡されます。それを超えると、保存先のパスと先頭2,000文字ほどのプレビューが返り、残りはClaudeがファイルを読むか検索して取りに行きます。読み戻す窓の大きさはBASH_MAX_OUTPUT_LENGTHで変えられ、既定は30,000文字、上限は150,000文字です。ただしbashOutputMaxChars設定があるとこの変数は無視され、この変数でインラインの上限が上がることもありません。冗長なビルドログを裏で流す場合は、この窓が効いてきます。
非対話のclaude -pで実行している場合は事情が違います。裏のコマンドは、実行の最終結果が出てから間もなく終了します。-pのスクリプトでは、裏に回した処理が最終結果のあとも動き続ける前提で組まないでください。
!プレフィックスのシェルモードとの違い
入力の先頭に!を付けるシェルモードは、Claudeの判断や承認を介さずにコマンドを直接実行し、結果を会話の文脈に自動で追加します。! npm testのように使います。シェルモードのコマンドもCtrl+Bで裏に回せます。自分で叩きたいが時間がかかる、という場面ではこの組み合わせが使えます。
まとめ
長いコマンドは、走らせてみて長引いたらCtrl+Bで裏に回すのが手軽です。30分を超えると分かっているなら、Claudeにrun_in_backgroundで起動させてtimeoutを付けてもらいます。BASH_DEFAULT_TIMEOUT_MSで既定値を伸ばしておく方法もあります。どちらも途中で止められるのを避ける手段です。