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

BASH_DEFAULT_TIMEOUT_MSは、Claude CodeのBashツールが1つのコマンドに与える既定のタイムアウトをミリ秒で変える環境変数です。既定は120000(2分)で、ビルドやテストが長引くとこの2分で区切られます。ただし区切られたコマンドは止まらず、バックグラウンドへ移ります。実際に困るのは、その先にある時間制限のほうです。

関連する環境変数を用途別に見渡したい場合はClaude Code環境変数リファレンスも参照してください。

BASH_DEFAULT_TIMEOUT_MSが決めるもの

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

BASH_DEFAULT_TIMEOUT_MSが効くのは、Claudeがtimeoutを渡さなかったフォアグラウンドのコマンドです。PowerShellツールも同じ規則で、同じ2つの変数を読みます。

名前の似たAPI_TIMEOUT_MSはモデルへのAPIリクエストのタイムアウトで、既定は600000(10分)、最大は2147483647です。Bashの実行時間とは関係がありません。「Request timed out」が出るなら調整先はAPI_TIMEOUT_MSで、詳しくはClaude Code Request timed outエラーにあります。

シェルのtimeoutコマンドとも別物です。Claude Codeの権限ルールは、timeout・time・nice・nohup・stdbufなどの前置きを取り除いてからBash(npm test *)のような許可ルールと照合します。timeout 30 npm testと書いても許可の判定は変わらず、BASH_DEFAULT_TIMEOUT_MSが管理する時間にも影響しません。

値を伸ばしても足りないとき:BASH_MAX_TIMEOUT_MSとの関係

BASH_MAX_TIMEOUT_MSは、Claudeが長いタイムアウトを要求してきたときの頭打ちの値です。実際に効く上限は、この値とBASH_DEFAULT_TIMEOUT_MSの大きい方になります。

既定と上限の両方を大きく取りたいときは、設定ファイルに2つとも書いておくと意図が読み取りやすくなります。

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

フォアグラウンドのコマンドが時間内に終わらないと、Claude Codeはそのコマンドを止めずにバックグラウンドへ移します。Claudeは作業を続けられます。

移されたコマンドの中にcd・pushd・popd・chdirがあっても、ディレクトリの変更はセッションに引き継がれません。結果にはSession cwd remains <dir>と書かれ、起きていない変更をClaudeが前提にしないようになっています。

例外はsleepで始まるコマンドで、バックグラウンドへ移らずタイムアウトで止まります。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1を設定した場合と、--bareで起動した場合も同じです。自動バックグラウンド化を含むバックグラウンド機能が丸ごと無効になり、タイムアウトに達したコマンドはすべて停止します。

バックグラウンドに移ったコマンドの寿命

移った先の時間制限は、フォアグラウンドのタイムアウトとは別の設定で決まります。Claudeが最初からバックグラウンドで起動したコマンド(run_in_background: true、dev serverやwatchビルドなど)は30分です。この時間制限は、Claudeが渡したtimeoutで最大2時間まで延ばせます。この場合BASH_DEFAULT_TIMEOUT_MSの120000は使われません。

2つの変数は、この時間制限を引き上げる手段にもなります。

つまりBASH_DEFAULT_TIMEOUT_MSを3600000(1時間)にすると、2分で区切るつもりの値が、移ったあとの寿命まで1時間に変えます。この動きはv2.1.285以降のものです。それより前は、メインの会話が起動したバックグラウンドコマンドに時間制限がありませんでした。サブエージェントが起動したものには1時間の制限があり、これはv2.1.260で撤廃されています。

値を下げても時間制限は短くなりません。30分の既定と2時間の最大はそのまま残ります。作業がまだ終わらないときは、Claudeがより長いtimeoutを付けてコマンドを起動し直せます。

コマンドの寿命は、誰が起動したかでも変わります。

• フォアグラウンドのサブエージェントが起動したコマンドは、そのサブエージェントの実行が終わった時点で止まる
• メインの会話やバックグラウンドのサブエージェントが起動したコマンドは、最終応答のあとも終了・停止・時間制限のいずれかまで動く
• 非対話モード(claude -p)では、バックグラウンドのBashタスクは最終結果を返してから約5秒後に終了する

バックグラウンドのサブエージェントやワークフローを起動した場合は、その完了まで-pは開いたままです。待ちは連続10分の無動作で終わり、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MSで変えられます(0で無制限)。Claudeがバックグラウンドの結果を処理するたびに、無動作の数え直しが始まります。

10分で待ちが切れると、Claude Codeはまだ動いているものを止め、途中結果を捨てます。この待ちは、通常のバックグラウンドシェルに適用される5秒の猶予とは別の上限です。

設定のしかた

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

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として読まれ、タイムアウトが1になることがありました(環境変数ページの記述)。古いバージョンでは桁そのままで書くと確実です。

設定ファイルのenvは、Claude Codeが起動方法に関係なくファイルから直接読みます。実行中のセッションでも、保存すると新しい値や変更が環境に反映されます。ただし変数を消しても実行中のセッションでは解除されず、次にclaudeを起動したときに効きます。

シェルのexportが残っていても、同じ変数をenvに書けば設定ファイル側の値が使われます。プロジェクトの.claude/settings.jsonに書いてチームで揃えたいとき、各自のシェルに古い値があっても影響しません。

例外はClaudeデスクトップアプリやself-hostedの環境ランナーから起動した場合です。起動側が組み立てた環境が優先され、その変数を起動側が設定済みなら、設定ファイルのenvの値は無視されます。

v2.1.287で見えるもの

手元のClaude Code(v2.1.287)で、タイムアウトを指定する入口がどこにあるかを見ました。

claude --version

2.1.287 (Claude Code)

claude --helpの出力には、Bashのタイムアウトを指定するオプションがありません。timeoutを含む行は無く、backgroundを含む行は--bgやclaude agentsなどバックグラウンドセッション関連のものだけでした。起動時に値を渡す手段は環境変数と設定ファイルのenvの2つで、Claudeが指定する場合は呼び出しごとのtimeoutパラメーターです。

長時間コマンドで次に当たる出力上限

タイムアウトを伸ばして長いコマンドを最後まで走らせると、次は出力量の上限に当たります。出力が5GBを超えたコマンドはその時点で終了させられます。

Claudeへ渡る量は、結果が成功扱いか失敗扱いかで変わります。

終了コード1が成功扱いになるのは、grep・rg・egrep・fgrep・find・diff・test・[、それにgit diffとgit grepだけです。pgrepやjq -eのように1が普通の結果として返るコマンドでも、失敗扱いになって上限が約10,000文字に下がります。

BASH_MAX_OUTPUT_LENGTHは読み戻しウィンドウの大きさを変える変数で、既定30,000・最大150,000です。引き上げても上の「約30,000文字」というインラインの上限は動かず、超えた分はファイルパスとプレビューで届きます。インライン上限と読み戻しウィンドウをまとめて変えるのはbashOutputMaxChars設定で、最大128,000文字です(v2.1.261以降。設定するとBASH_MAX_OUTPUT_LENGTHは無視されます)。

よくある質問

CLAUDE_CODE_TOOL_MEMORY_LIMITもタイムアウトと関係しますか

別の変数です。LinuxとWSLで、BashとPowerShellのツール(v2.1.246以降はMonitorも)が使えるメモリー量を4Gのように制限します。0またはoffで無効になります。時間ではなくメモリー使用量が対象です。

秒で考えて設定すると何が起きますか

単位がミリ秒なので、300と書くと0.3秒です。5分にしたいなら300000です。

桁を増やしすぎる間違いもあります。API_TIMEOUT_MSは最大の2147483647を超えるとタイマーがあふれ、モデルへのリクエストが即座に失敗します。