Claude Code：バックグラウンドコマンドの30分制限

Claude Codeは、無人実行の場合、バックグラウンドコマンドを30分後に停止します。対象となるのは、-pフラグを使った起動、Agent SDKアプリケーション、CIジョブ、クラウドセッションです。Claudeがコマンド自体に実行時間を指定した場合、実行時間は最大2時間です。一方、通常のターミナル、デスクトップアプリ、VS Codeでは、バージョン2.1.288以降、制限はありません。

以前は一日中画面の前に座っていました。エージェントに手順を与え、様子を見て、修正を加え、続きを頼む。それを段階ごとに繰り返していました。コードを書いているのはマシンでも、動かしているのは私でした。今は計画を書き、段階に分け、実装をサブエージェントに任せて夜の間に進め、席を離れます。私がいない8時間、Claudeは計画に沿って調査し、構築し、磨き上げます。朝には、やり直すより、成果を受け入れることに多くの時間を使うようになりました。

ただし、一晩の実行で-pを使う場合や、サーバー上のスケジュール、CI、クラウドで実行する場合、バックグラウンドで動く開発サーバーやビルドは30分で停止します。その後Claude Codeが停止させるため、夜間の作業は途中でつまずきます。どの実行が制限の対象か、引き上げる方法、すでにコマンドが停止している場合の対処を説明します。始めましょう。

サービスの利用方法については、Ailootのドキュメントをご覧ください。

制限の対象#

バックグラウンドコマンドとは、Claudeが開始し、別の作業をしている間も実行し続けるものです。たとえば、npm run devで開始した開発サーバーや、ファイルの変更を監視するビルドなどです。

Claude Codeのドキュメントには次のように記載されています。

つまり、制限はその場にいないときに実行する場合に適用されます。-pを使った実行、Agent SDKアプリケーション、CIジョブ、クラウドセッションが該当します。自分でセッションを操作しているときは、ターミナル、デスクトップアプリ、VS Codeに制限はありません。制限は2.1.285で導入され、2.1.288より前はすべてのセッションに適用されていました。

自分に適用されるかどうかは、次のように判断できます。

• ターミナルまたはVS CodeでClaude Codeを開き、タスクを与えて寝た場合。 バージョン2.1.288以降なら制限はありません。バージョン2.1.285から2.1.287では、この場合も適用されます。最新版への更新方法は別の記事で説明しています。
• スケジュールに従って、独自のAgent SDKアプリケーションから、またはCIでclaude -p "task"を起動する場合。 制限が適用されます。
• タスクがクラウドセッションで実行される場合。 制限が適用されます。

エージェントに独立して作業させるとき、私はプロンプトにこう書きます。「これらの条件と停止する理由を作業計画に記録してください。閉じる予定のウィンドウや、コンピューター自体に依存しないプロセスであることを確認してください。」30分の制限も、停止する理由の一つです。

バックグラウンドコマンドの実行時間#

カウントダウンは、コマンドがバックグラウンドに移った時点で始まります。状況は2通りあります。

Claudeが最初からコマンドをバックグラウンドで開始する場合。 実行時間は30分です。Claudeが開始時に時間を指定した場合（timeoutパラメーター）、その時間が適用されますが、最大2時間です。

Claudeが待っている間にコマンドが完了しない場合。 Claudeは通常のコマンドの完了を2分間待ちます。完了しなければ、Claude Codeは停止せず、バックグラウンドに移します。その時点から30分間実行されます。

時間が経過すると、Claude Codeはコマンドを停止し、Claudeに次のように伝えます。

Background command "<description>" was stopped after reaching its background time limit

作業が完了していなければ、Claudeはより長い時間を指定してコマンドを再実行できます。

-pについてもう一点あります。この種類の実行では、Claudeの最終応答から約5秒後にバックグラウンドコマンドが終了します。-pによる夜間実行で開始したサーバーは、実行そのものが続く間だけ動きます。30分の制限が関係するのは、実行がそれより長い場合です。たとえば、Claudeが開始時にサーバーを立ち上げ、そのサーバーに対して1時間チェックを実行する場合です。

Claude Codeで夜間作業を進める方法#

一日中エージェントを動かすことに疲れたので、代わりにオーケストレーター用のプロンプトを一つ使うことにしました。夕方に開始すると、Claudeは執筆、確認、修正、コミットの段階を順に進め、夜の間ずっと自ら作業します。

サブエージェントのグループがコードを書きます。それぞれが別々のファイルを担当し、互いの作業を妨げないようにします。次に、新しい別のグループが成果を受け入れるための作業をします。コードレビュー、セキュリティチェック、実環境でのチェックを行います。問題が見つかればすぐに修正し、チェックを再実行します。プロンプトには次の一文を含めます。「コンテキストが尽きたら、状態を記録してください。次の実行で続きを進めます。」

ここで説明した例では、3日間で14段階中8段階をこの方法で完了しました。

覚えておくべき点は2つだけです。オーケストレーターがあなたの代わりに考えてくれるわけではありません。まず段階を含む詳細な計画を書き、それから夜間の作業を開始してください。また、サブスクリプションの利用枠を大量に消費するため、小さなタスクにこの仕組みを設定しても意味はあまりありません。試行回数には必ず上限を設けてください。そうしないと、エージェントが一晩でサブスクリプションの利用枠を使い切ることがあります。利用枠の上限設定方法は別の記事で説明しています。

制限を引き上げる方法#

方法1：Claudeに頼む。 特定のコマンドの実行時間はClaudeが決めます。自分で設定することはできません。ただし、タスクに「開発サーバーを2時間バックグラウンドで動かしてください」と書くことはできます。この方法で2時間を超えることはできません。

方法2：設定ファイルの変数を使う。 値の単位はミリ秒です。制限を30分や2時間より短くすることはできません。引き上げることだけができます。

• BASH_DEFAULT_TIMEOUT_MSを1800000（30分）より大きく設定すると、30分の既定値が変わります。これは、Claudeが時間を指定せずにバックグラウンドで開始するコマンドと、タイムアウト後にバックグラウンドへ移すコマンドの両方に適用されます。7200000（2時間）より大きく設定すると、上限も引き上げられます。
• BASH_MAX_TIMEOUT_MSを7200000（2時間）より大きく設定すると、2時間の上限が引き上げられます。30分の既定値は変わらないため、個別の時間を指定していないコマンドは引き続き30分後に停止します。

BASH_DEFAULT_TIMEOUT_MSには副作用があります。同じ変数で、通常のコマンドをバックグラウンドへ移す前にClaudeが待つ時間も設定します。1時間に設定すると、Claudeは2分ではなく1時間待ちます。夜間作業には影響しませんが、日中に時間のかかるコマンドを実行すると、応答を待つ時間が長くなります。

細かい設定を避けたい場合、通常のコマンドと上限の両方に3時間必要なら、BASH_DEFAULT_TIMEOUT_MSを10800000に設定してください。これで十分です。2つ目の変数は必要ありません。

設定ファイルはホームディレクトリの.claudeフォルダーにあります。macOSとLinuxでは~/.claude/settings.json、Windowsでは%USERPROFILE%\.claude\settings.jsonです。ファイルがなければ作成してください。1時間の制限は次のように設定します。

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

すでにenvブロックがある場合は、その中に行を追加してください。実行中のセッションは、ファイルを保存すると新しい値を読み込みます。変数を削除した場合、その変更が有効になるのは次にclaudeを起動したときです。

設定ファイルはエージェントが実行されているマシン上に必要です。エージェントを夜間に作業させるには、コンピューターをスリープさせないでください。あるいは、Claude Codeをリモートサーバーで実行し、そちらに設定を置きます。

コマンドがすでに停止している場合#

手作業で何かする必要はありません。Claude Codeはコマンドが停止した理由をClaudeに伝えるので、まず何が起きたか尋ねてください。

その後、次の手順で進めます。

1. 最長2時間の一度限りの長時間実行。 Claudeに、実行時間を長くしてコマンドを再実行するよう頼みます。
2. コマンドが定期的に30分を超える場合。 上記の例のように、設定ファイルでBASH_DEFAULT_TIMEOUT_MSを1800000より大きく設定します。2時間を超える時間が必要なら、そこでBASH_MAX_TIMEOUT_MSも7200000より大きく設定します。
3. コマンドをもう一度実行する。 変更前からバックグラウンドで実行していたコマンドについて、ドキュメントは保証していません。
4. 次の実行結果を確認する。 Claudeの報告に「バックグラウンドの時間制限に達したため停止しました」というフレーズが再び含まれている場合、その設定はそのコマンドに適用されていません。

サブエージェントとルーティンが、離れている間もエージェントの作業を続けさせます。

エージェントを一晩中ループ実行する方法は別の記事で説明しています。また、Claude Codeが夜の間にプロジェクトを壊さないよう設定する方法はこちらで説明しています。

夜間実行のどの段階で停止するのかを確認し、その理由を上記の制限と照らし合わせてください。

Ailootを知ってください。