Claude Code がシェルコマンドを実行するときに使うのが組み込みの Bash ツールです。普段は意識しなくても使えますが、「export した変数が次のコマンドで消えている」「長いビルドが途中でバックグラウンドに回った」「テストログの後半が見えていない」といった挙動には、すべて決まったルールがあります。この記事では、公式ドキュメント「Tools reference」の Bash ツールの節をもとに、コマンド間で引き継がれるもの、タイムアウト、出力の上限、バックグラウンド実行の時間制限と、それぞれを変える環境変数・設定を整理します。
コマンド間で引き継がれるもの
Bash ツールはコマンドを1回ごとに別のプロセスで実行します。そのため、何が次のコマンドに残り、何が残らないかが決まっています。
- 作業ディレクトリ(cd): メインのセッションで Claude が
cdすると、移動先がプロジェクトのディレクトリか、--add-dir・/add-dir・設定のadditionalDirectoriesで追加した作業ディレクトリの中である限り、以降の Bash コマンドにも引き継がれます。あとから送ったメッセージに応じて実行するコマンドも同じです。- サブエージェントのセッションでは、作業ディレクトリの変更は引き継がれません。
- それらのディレクトリの外へ
cdした場合はプロジェクトのディレクトリに戻され、ツール結果の末尾にShell cwd was reset to <dir>が付きます。 - 毎回プロジェクトのディレクトリから始めたいときは
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1を設定します。
- 環境変数: 引き継がれません。あるコマンドで
exportしても、次のコマンドでは使えません。 - エイリアス・シェル関数: 使えます。Claude Code はセッション開始時に、シェルに応じて
~/.zshrc・~/.bashrc・~/.profileのいずれかを読み込み、そこで定義されたエイリアス・関数・シェルオプションを取り込んで、すべての Bash コマンドに適用します。
virtualenv や conda の環境は、Claude Code を起動する前に有効化しておくのが公式の案内です。環境変数を Bash コマンドの間で持続させたい場合は、起動前に環境変数 CLAUDE_ENV_FILE にシェルスクリプトのパスを設定するか、SessionStart フックでその内容を動的に用意します。
タイムアウトの既定値と上限
各コマンドにはタイムアウトがあり、その管理は Claude 自身が行います。既定より長く待ちたいコマンドでは、Claude がその呼び出しに timeout パラメータを付けます。利用者がコマンドごとにタイムアウトを指定することはありません。
フォアグラウンドで実行するコマンドについては、次の2つの環境変数で範囲を変えられます(単位はミリ秒)。
| 環境変数 | 意味 | 既定値 |
|---|---|---|
BASH_DEFAULT_TIMEOUT_MS | Claude が timeout を付けなかったときのタイムアウト | 120000(2分) |
BASH_MAX_TIMEOUT_MS | Claude が指定できるタイムアウトの上限 | 600000(10分) |
実際に効く上限は、BASH_MAX_TIMEOUT_MS と BASH_DEFAULT_TIMEOUT_MS の大きいほうです。PowerShell ツールも同じタイムアウトのルールに従い、同じ2つの変数を読みます。
フォアグラウンドのコマンドがタイムアウトまでに終わらなかった場合、Claude Code はそのコマンドを止めずにバックグラウンドへ移します(sleep で始まるコマンドは除く)。その場合の結果には、たとえば Command did not complete within its 120s timeout and was moved to the background のように、適用されたタイムアウトの秒数とともに移動したことが明記され、タスク ID と出力の書き込み先ファイルのパスが続きます。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定するか bare モードで動かすと、この自動移動は行われず、タイムアウトに達したコマンドはそこで止まります。
出力の上限と失敗時の扱い
コマンドの出力は実行中に作業用ファイルへ書き出され、終了後にそのファイルから読み戻されます。出力が 5 GB を超えたコマンドは強制終了されます。Claude にどれだけの出力がそのまま(インラインで)渡るかは、結果が「正常」か「失敗」かで変わります。
| 結果 | Claude が受け取るもの |
|---|---|
| 正常 | 既定でおよそ 30,000 文字まではインライン。それを超えると、セッションディレクトリに保存したファイルのパス(64 MiB を超える部分は切り捨て)と先頭最大 2,000 文字のプレビューが渡り、残りが必要なら Claude がそのファイルを読むか検索する |
| 失敗 | およそ 10,000 文字まではインライン。超える場合は、読み戻した範囲から切り出した先頭と末尾の抜粋のみ(ファイルのパスは付かない) |
注意したいのは終了コード 1 の扱いです。Bash ツールが終了コード 1 を「正常」とみなすのは、それが無害な結果だと Claude Code が認識しているコマンドだけで、grep・rg・egrep・fgrep・find・diff・test・[、それに git diff と git grep が該当します。それ以外は、たとえば一致なしの pgrep や jq -e、差分ありの cmp のように意味としては無害でも「失敗」扱いになり、出力は約 10,000 文字の抜粋に絞られます。
出力量の調整方法は2つあります。
- 環境変数
BASH_MAX_OUTPUT_LENGTH: 作業用ファイルから結果へ読み戻す文字数です。既定 30,000、上限 150,000。冗長なビルドログやテストスイート全体のログが頻繁にあふれる場合に引き上げます。失敗時の抜粋もこの範囲から切り出されますが、正常時のインラインの上限は変わらないため、それを超えた正常結果はこの変数に関係なくパスとプレビューで渡ります。 - 設定
bashOutputMaxChars: 正常な結果をインラインで受け取る量を変えたいときはこちらを使います。最大 128,000 文字で、インラインの上限と読み戻し範囲をまとめて決め、設定するとBASH_MAX_OUTPUT_LENGTHは無視されます(Claude Code v2.1.261 以降)。
バックグラウンド実行と時間制限
開発サーバーや watch ビルドのような長時間動くプロセスは、Claude が run_in_background: true を付けてバックグラウンドタスクとして起動し、その間も作業を続けられます。動いているバックグラウンドタスクの一覧表示と停止は /tasks で行います。そこやデスクトップアプリなどの接続中のクライアントから止めると、Claude は待たずに次へ進みます。
バックグラウンドのコマンドがいつ止まるかは、誰が起動したかで決まります。
- フォアグラウンドのサブエージェントが起動したコマンドは、そのサブエージェントの実行が終わった時点(完了・失敗・中断のいずれでも)で止まります。
- メインの会話やバックグラウンドのサブエージェントが起動したコマンドは、最終応答の後も、終了するか、停止されるか、時間制限に達するまで動き続けます。
-pフラグの非対話実行では、メインの会話が起動したコマンドが動いている間、結果を出した後もそのコマンドが終わるか時間制限に達するまで実行が終わりません。バックグラウンドのサブエージェントが起動したコマンドは、実行の終了とともに止まります。
時間制限がかかるのは、-p 実行、Agent SDK アプリケーション、CI ジョブ、クラウドセッションのように無人で動くセッションだけです(v2.1.285 以降。v2.1.288 より前はすべてのセッションに適用)。ターミナル・デスクトップアプリ・VS Code 拡張で自分が操作するローカルセッションには、バックグラウンドコマンドの時間制限はありません。
- Claude が最初からバックグラウンドで起動したコマンド: 30分、または Claude が
run_in_backgroundと一緒に渡したtimeout(最大2時間) - フォアグラウンドで始まり、タイムアウトでバックグラウンドへ移ったコマンド: 移った時点から30分
- プロンプトを
--input-format stream-jsonではなくテキストで渡した-p実行では、上の既定値はどちらも10分
制限に達したコマンドは止められ、Background command "<description>" was stopped after reaching its background time limit という通知とともに理由が Claude に伝わります。作業がまだ必要なら、Claude はより長い timeout を付けて再実行できます。
この制限は、タイムアウトと同じ2つの環境変数で引き上げることができます(短くはできません。既定値より小さい値は無視され、既定値と2時間の上限がそのまま残ります)。
BASH_DEFAULT_TIMEOUT_MSを1800000より大きくすると、30分の既定値がその値に置き換わります(timeoutなしで起動したコマンドと、移動したコマンドの両方)。テキストのプロンプトで動く-p実行では、600000を超える値で10分の既定値が置き換わります。BASH_MAX_TIMEOUT_MSを7200000より大きくすると、2時間の上限がその値まで上がります。BASH_DEFAULT_TIMEOUT_MSを7200000より大きくした場合も同様です。
設定のまとめ
この記事で扱った環境変数と設定を一覧にします。環境変数はシェルで設定するか、settings.json の env ブロックに書けます。
| 名前 | 種類 | 用途 |
|---|---|---|
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR | 環境変数 | 各コマンドの後に元の作業ディレクトリへ戻す(cd を引き継がない) |
CLAUDE_ENV_FILE | 環境変数 | Bash コマンド間で持続させたい環境変数を書いたシェルスクリプトを指定 |
BASH_DEFAULT_TIMEOUT_MS | 環境変数 | 既定のタイムアウト(既定2分)。大きくすると無人セッションのバックグラウンド既定制限も置き換わる |
BASH_MAX_TIMEOUT_MS | 環境変数 | Claude が指定できるタイムアウトの上限(既定10分)。2時間超で背景実行の上限も上がる |
BASH_MAX_OUTPUT_LENGTH | 環境変数 | 結果へ読み戻す文字数(既定 30,000、最大 150,000) |
bashOutputMaxChars | 設定 | 正常な結果のインライン上限と読み戻し範囲(最大 128,000、v2.1.261 以降)。設定時は上の変数を無視 |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | 環境変数 | 1 で run_in_background パラメータを外し、タイムアウト時の自動バックグラウンド移動も止める |
たとえば、ビルドに15分ほどかかるプロジェクトで、Claude が待てる上限を30分に広げたい場合は次のように書きます。
{
"env": {
"BASH_MAX_TIMEOUT_MS": "1800000"
}
}
どのコマンドを確認なしで実行させるかは別の仕組みで、Bash(npm run *) のような権限ルールで決めます。詳しくは権限モードの選び方を参照してください。
本記事は Claude Code 公式ドキュメント「Tools reference」の Bash ツールの節を元に、「Environment variables」で各環境変数の既定値と意味を照合した非公式の日本語解説です(確認日 2026-11-15)。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。