Claude Code: 長いテストやビルドが2分で切れるなら BASH_DEFAULT_TIMEOUT_MS を延ばす

どんな時に使う？

• npm test や cargo build が毎回途中で止まり、Claude が「タイムアウトしたので分割します」と回り道をする
• CI 相当のテストを手元のエージェントに一気に流させたい
• claude -p で無人実行するときに、長い処理が背景に回されて時間切れになる

設定

プロジェクト（.claude/settings.json）か自分用（~/.claude/settings.json）に書く。値はミリ秒の文字列。

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "BASH_MAX_TIMEOUT_MS": "1200000"
  }
}

• BASH_DEFAULT_TIMEOUT_MS: Claude が timeout を指定しなかったときの待ち時間（既定 120000＝2分）
• BASH_MAX_TIMEOUT_MS: Claude が自分で指定できる上限（既定 600000＝10分）。実際の上限は2つのうち大きい方
• PowerShell ツールも同じ2つの変数を読む
• settings.json の env は保存すると実行中のセッションにも反映される

無人実行（-p・SDK・CI・クラウド）での背景コマンド

v2.1.285 以降、無人のセッションでは背景に回ったコマンドにも時間制限がある（既定30分、最大2時間）。

• BASH_DEFAULT_TIMEOUT_MS を 1800000（30分）より大きくすると、その値が背景コマンドの既定にもなる
• 2時間を超えて動かしたいときは BASH_MAX_TIMEOUT_MS を 7200000 より大きくする
• 小さい値を入れても制限は短くならない（既定のまま）

注意点

• 延ばしすぎると、固まったコマンドを長く待つことになる。テストが無限ループする恐れがあるなら、コマンド側にも timeout 900 npm test のような上限を付ける
• v2.1.311 からは、時間切れになったコマンドもそこまでの出力が返り、背景で動き続けていることが伝わるようになった
• 開発サーバーのような終わらないプロセスは延長ではなく背景実行か別の仕組みへ: 開発サーバーや長いコマンドは pueue のキューに入れ、エージェントにはログだけ読ませる、Claude Code: Monitor ツールで開発サーバーのログや CI を見張らせ、作業を続ける

出典

• @oswrav 2026-10-27「Claude Code 小技 No.13」: @oswrav · 2026-10-27
• 公式: code.claude.com 、 code.claude.com （Time limit for background commands）