BASH_DEFAULT_TIMEOUT_MSでBashコマンドのタイムアウトを変更する

BASH_DEFAULT_TIMEOUT_MSは、Claude CodeのBashツールが1つのコマンドに与える既定のタイムアウトをミリ秒単位で変更する環境変数です。既定値は120000(2分)で、長時間かかるビルドやテストを頻繁に実行すると、この2分で頻繁に打ち切られます。上限を決めるBASH_MAX_TIMEOUT_MSとの関係、タイムアウトに達したときの挙動、設定方法までをまとめます。関連する環境変数を用途別に見渡したい場合はClaude Code環境変数リファレンスも参照してください。

BASH_DEFAULT_TIMEOUT_MSが決めるもの

Bashツールで実行するコマンドはすべてタイムアウト付きで動きます。タイムアウトの管理はClaudeが行い、既定より長い時間が必要だと判断すると、そのコマンド呼び出しにtimeoutパラメーターを渡します。ユーザーがコマンドごとに個別のタイムアウトを設定する仕組みはありません。

BASH_DEFAULT_TIMEOUT_MSが効くのは、Claudeがtimeoutパラメーターを渡さなかったときです。この既定値を伸ばしておくと、ビルドやテストのような時間のかかるコマンドで打ち切りが起きにくくなります。

似た名前のAPI_TIMEOUT_MSと混同しやすい点に注意します。API_TIMEOUT_MSはモデルへのAPIリクエスト自体のタイムアウト(既定600000、10分)で、Bashツールの実行時間とは無関係です。遅いネットワークやプロキシ経由で「Request timed out」というエラーが出る場合はAPI_TIMEOUT_MS側の調整が対処になります(詳しくはClaude Code Request timed outエラーを参照)。手元でBashコマンドが打ち切られる場合はBASH_DEFAULT_TIMEOUT_MSを調整します。目的が違う2つの変数です。

シェルのtimeoutコマンドと混同しないことも大切です。Claude Codeの権限ルールは、timeout・time・nice・nohup・stdbufといったコマンドの前置きを一度取り除いてから、Bash(npm test *)のような許可ルールと突き合わせます。つまり自分でtimeout 30 npm testと書いても、許可ルールの判定には影響しません。一方でそのtimeout 30という指定自体は、Claudeが渡すtimeoutパラメーターとは別物で、BASH_DEFAULT_TIMEOUT_MSが管理する打ち切り時間には影響しません。

上限を決めるBASH_MAX_TIMEOUT_MSとの関係

BASH_MAX_TIMEOUT_MSは、Claudeが自分で長いタイムアウトを要求してきたときの上限です。既定値は600000(10分)。実際に効く上限は「BASH_DEFAULT_TIMEOUT_MSとBASH_MAX_TIMEOUT_MSの大きい方」になります。2つの変数は役割が違います。BASH_DEFAULT_TIMEOUT_MSはClaudeが何も指定しなかったときに使われる値、BASH_MAX_TIMEOUT_MSはClaudeが指定してきた値を頭打ちにする値です。

たとえばBASH_DEFAULT_TIMEOUT_MSを900000(15分)に伸ばし、BASH_MAX_TIMEOUT_MSを既定の600000のままにした場合、実際の上限は大きい方の900000が採用されます。既定タイムアウトだけを伸ばしたつもりが、実質的な上限まで一緒に伸びる、という組み合わせです。逆にBASH_MAX_TIMEOUT_MSだけを1800000(30分)に伸ばし、BASH_DEFAULT_TIMEOUT_MSを既定の120000のままにした場合は、Claudeが明示的に長いタイムアウトを要求したときだけ最大30分まで許容され、何も指定されない通常のコマンドは引き続き2分で打ち切りの判定に入ります。既定と上限を両方大きく取りたいときは、BASH_MAX_TIMEOUT_MS側も明示的に指定しておくと意図が伝わりやすくなります。

タイムアウトに達すると何が起きるか

バックグラウンドへの移行には2つの経路があります。dev serverやwatchビルドのように最初から終わらないとわかっているコマンドは、Claudeがrun_in_background: trueを指定して最初からバックグラウンドタスクとして起動します。この場合、BASH_DEFAULT_TIMEOUT_MSは関与しません。

もう1つが本記事の主題である、フォアグラウンドで実行していたコマンドがタイムアウトに達したケースです。この場合、Claude Codeはそのコマンドを止めるのではなくバックグラウンドへ移します。Claudeは作業を続けながら、そのコマンドの完了を後から確認できます。

結果には何が起きたかが明示されます。「Command did not complete within its 120s timeout and was moved to the background」という形式で、適用されたタイムアウトの秒数、タスクID、出力の書き込み先パスまで含まれます。移されたコマンドの中にcd・pushd・popd・chdirが含まれていても、ディレクトリの変更はセッションに引き継がれません。結果には「Session cwd remains <dir>」と明示され、実際には起きていないディレクトリ変更をClaudeが引きずらないようになっています。

自動でバックグラウンドへ移さず、その場で打ち切る例外が3種類あります。

• sleepで始まるコマンド
• どこかにgitを含むコマンド
• Claude Codeが単純なコマンドへ分解しきれない複合コマンド

これらはタイムアウトで停止し、バックグラウンドには移りません。gitコマンドが常に対象になるのは、リポジトリの状態を変える操作を宙ぶらりんのまま裏で走らせないための扱いです。

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1を設定すると、この自動バックグラウンド化を含めたバックグラウンドタスク機能全体を無効にできます。無効にした場合、タイムアウトに達したコマンドはすべて打ち切りの扱いになります。

バックグラウンドへ移ったコマンドにも寿命はあります。foregroundで動くサブエージェントが開始したコマンドは、そのサブエージェントが最終応答を返した時点で終了します。メインの会話やbackgroundのサブエージェントが開始したコマンドはそのまま動き続けます。/tasksでバックグラウンドタスクの一覧表示と停止ができます。非対話モード(-pフラグ)では、実行結果に含まれるバックグラウンドタスクは最終ターンの後もしばらく待たれますが、無期限ではありません。

設定のしかた

シェルの環境変数として渡します。

export BASH_DEFAULT_TIMEOUT_MS="300000"
claude

チームで揃えたいときは設定ファイルのenvキーに書きます。

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_TIMEOUT_MS": "900000"
  }
}

数値は300000のような桁そのままの表記のほか、3e5のような指数表記や64_000のような桁区切り表記でも読み取れます。v2.1.211より前のバージョンでは、この指数・桁区切り表記が意図せず小さい値に化けるバグがありました(1e6が1ミリ秒として設定されるなど)。古いバージョンを使っている場合は、桁そのままの表記で設定するのが安全です。

シェルと設定ファイルの両方に値を書いた場合は、設定ファイルのenvブロックが勝ちます。Claude Codeが起動時と設定ファイル変更時にenvブロックの値をプロセス環境へ書き込み、シェルから引き継いだ値を上書きするためです。プロジェクトの.claude/settings.jsonに値を書いてチーム全体で揃えたい場合、開発者ごとのシェル設定に古いexportが残っていても、プロジェクト側の値がそのまま使われます。

タイムアウトを伸ばすと同時に確認したい出力上限

タイムアウトを伸ばして長時間コマンドを最後まで走らせられるようにすると、次にぶつかりやすいのが出力量の上限です。出力が5GBを超えたコマンドはその時点で強制終了されます。タイムアウトを長く取るほど、この出力上限に先に到達する可能性も上がる点は覚えておくと役立ちます。

コマンドの結果がClaudeへどこまで渡るかは、成功扱いか失敗扱いかでも変わります。

BASH_MAX_OUTPUT_LENGTHは、この読み戻しウィンドウの大きさそのものを変える変数です。既定30,000文字・上限150,000文字で、verboseなビルドログやテストスイートの全出力のように出力が膨らむコマンドをタイムアウトまで走らせられるようにしても、この上限までしか読み戻されません。長時間コマンドを扱うときは、タイムアウトと出力上限の両方を実行するコマンドの特性に合わせて見積もっておくと、タイムアウトより先に出力上限で結果が欠ける事態を避けられます。

よくある質問

BASH_DEFAULT_TIMEOUT_MSを伸ばせば長時間コマンドは必ず最後まで走りますか

BASH_MAX_TIMEOUT_MSとの大きい方が実質的な上限になるため、既定値だけを伸ばしても上限を超えるコマンドは変わらずタイムアウトします。両方の値を確認してから調整します。

タイムアウトで打ち切られたコマンドの結果は消えますか

バックグラウンドに移された場合は消えません。出力は指定されたファイルパスに書き込まれ続け、Claudeはタスクの完了を後から確認できます。打ち切り対象の3種類のコマンド(sleep起点・git含む・複合コマンド)だけは、その場で停止し、それ以上の出力は追加されません。

この変数はBashツール以外にも効きますか

BASH_DEFAULT_TIMEOUT_MSとBASH_MAX_TIMEOUT_MSはBashツールの実行時間を管理する変数で、モデルへのAPIリクエストには関与しません。API側のタイムアウトはAPI_TIMEOUT_MSが別に受け持ちます。名前の似たCLAUDE_CODE_TOOL_MEMORY_LIMITはBashとPowerShellの両方のツールが使えるメモリー量を制限する変数で、こちらはタイムアウトではなくメモリー使用量が対象です。

単位はミリ秒ですか秒ですか

ミリ秒です。既定値の120000は2分、600000は10分に相当します。秒数で考えて1000倍し忘れると、意図した長さの1000分の1のタイムアウトになるので注意します。

特定の1コマンドだけタイムアウトを長くしたいときはどうしますか

コマンドごとに個別のタイムアウトをユーザー側で指定する仕組みはありません。Claudeが既定より長い時間が必要と判断した場合に、そのコマンド呼び出しへtimeoutパラメーターを渡します。常にゆとりを持たせたいコマンドが多いなら、BASH_DEFAULT_TIMEOUT_MS自体を伸ばすのが唯一の手段です。