CLAUDE_CODE_GLOB_TIMEOUT_SECONDSとは — 大規模リポジトリのGlobタイムアウト調整
CLAUDE_CODE_GLOB_TIMEOUT_SECONDSはGlobツールのファイル探索タイムアウトを変更する環境変数です。既定値、WSLとの違い、上げる目安と確認手順をまとめます。
CLAUDE_CODE_GLOB_TIMEOUT_SECONDS は、Claude CodeのGlobツールがファイル名パターンでの探索に使える時間を秒数で指定する環境変数です。既定値は多くの環境で20秒、WSLだけ60秒です。大規模リポジトリやネットワークドライブ上のプロジェクトでGlobがタイムアウトを理由に結果を返せないとき、この値を引き上げることで探索を完走させます。
Globツールが何をしているか
Globツールは、ファイル名のパターンマッチだけでファイルを探すツールです。**/*.js のように ** を使った再帰的なディレクトリ横断や、src/**/*.ts、*.{json,yaml} のような拡張子指定に対応します。中身の文字列を検索するGrepとは役割が分かれていて、Globは「名前」、Grepは「中身の行」を探します。
結果は更新日時順に並び、上限100件で打ち切られます。上限に達すると、Claude側にはその旨を示す打ち切りフラグが渡り、パターンを絞り込んで再検索する判断材料になります。100件の上限自体はこの環境変数では変わりません。
Globは既定では .gitignore を見ません。追跡外のファイルも含めて全部を対象にするため、大きなビルド成果物ディレクトリや node_modules を丸ごと抱えたリポジトリでは、それだけ探索対象が膨らみます。.gitignore を尊重させたい場合は別の環境変数 CLAUDE_CODE_GLOB_NO_IGNORE を false に設定します。この設定は探索対象そのものを絞り込むため、タイムアウト対策としても効きます。
既定値とタイムアウトが起きる条件
| 項目 | 内容 |
|---|---|
| 既定タイムアウト(通常) | 内容20秒 |
| 既定タイムアウト(WSL) | 内容60秒 |
| 変更対象 | 内容Globツールのファイル探索のみ |
| 影響しないもの | 内容@ファイル自動補完、ls、Grep、Read |
WSLだけ既定値が3倍長いのは、WSLの/mnt/c配下でWindows側のファイルシステムをマウントして扱う構成が、ネイティブなLinuxファイルシステムより探索に時間がかかりやすいためです。同じ理由で、WSL上でもさらに大きなリポジトリを扱うなら、既定の60秒でも足りないことがあります。
タイムアウトが起きやすいのは、数十万ファイル規模のモノレポ、ネットワークドライブやマウントされた共有ストレージ上のプロジェクト、.gitignore 対象外のビルド成果物や依存パッケージが大量に残ったディレクトリでの探索です。1つのパターンで再帰的に深い階層まで辿る **/*.ext のような形の指定は、浅い階層に絞った指定より探索コストが高くなります。
設定のしかた
シェルの環境変数として渡すのが最も手早い方法です。値は秒数を表す整数で指定します。
export CLAUDE_CODE_GLOB_TIMEOUT_SECONDS=60
claude端末やチームをまたいで固定したい場合は、設定ファイルの env キーに書きます。この形式なら、その設定ファイルが読み込まれる全セッションと子プロセスに同じ値が渡ります。
{
"env": {
"CLAUDE_CODE_GLOB_TIMEOUT_SECONDS": "60"
}
}プロジェクト単位で必要なら .claude/settings.json、ユーザー全体で固定したいなら ~/.claude/settings.json、組織で一律に強制したいなら管理設定に書きます。設定ファイルの階層と優先順位はClaude Code設定ガイドにまとめています。
Bashのタイムアウト系変数との違い
Claude Codeには用途別のタイムアウト変数がいくつかあり、名前が似ていて混同しやすいところです。それぞれが効く対象は完全に別です。
| 環境変数 | 効く対象 | 既定値 |
|---|---|---|
CLAUDE_CODE_GLOB_TIMEOUT_SECONDS | 効く対象Globツールのファイル探索 | 既定値20秒(WSLは60秒) |
BASH_DEFAULT_TIMEOUT_MS | 効く対象長時間実行するbashコマンドの既定タイムアウト | 既定値120,000ミリ秒(2分) |
BASH_MAX_TIMEOUT_MS | 効く対象モデルがbashコマンドに設定できる上限 | 既定値600,000ミリ秒(10分) |
MCP_TIMEOUT | 効く対象MCPサーバーの起動 | 既定値30,000ミリ秒(30秒) |
MCP_TOOL_TIMEOUT | 効く対象MCPツールの実行 | 既定値約28時間相当 |
BASH_DEFAULT_TIMEOUT_MS と BASH_MAX_TIMEOUT_MS はミリ秒単位で、実効の上限はこの2つのうち大きい方が使われます。Globのタイムアウトだけが秒単位で指定する変数という点も、他と混同しやすいポイントです。Bashコマンド実行のタイムアウト全般はClaude Code環境変数リファレンスで扱っています。
タイムアウトを疑ったときの切り分け手順
Globが結果を返さない、または途中で止まったように見えるとき、次の順で切り分けます。
- 対象ディレクトリの規模を確認する。
find . -type f | wc -lのようなコマンドで、探索対象がどれくらいの件数になるか把握します - パターンを狭める。
**/*.tsのような広いパターンより、src/api/**/*.tsのように階層を絞ったパターンの方が速く終わります .gitignore対象のファイルが探索に含まれていないか確認する。CLAUDE_CODE_GLOB_NO_IGNORE=falseを試して、ノイズになっている生成物ディレクトリを除外できないか見ます- それでも間に合わない場合に
CLAUDE_CODE_GLOB_TIMEOUT_SECONDSを引き上げる
この順番が重要なのは、タイムアウトを先に引き上げてしまうと、本来は探索対象を絞ることで速くなるはずの遅さを、待ち時間で覆い隠してしまうからです。ネットワークドライブやマウント越しのストレージが原因なら、値を上げても毎回同じだけ待たされる状態が続きます。
起動場所を変えるという回避策
環境変数を上げる以外に、そもそもGlobの探索対象を小さくする方法もあります。Claude Codeをリポジトリのルートではなく、実際に作業する下位ディレクトリから起動すると、Globが辿るディレクトリツリーそのものが縮みます。数十のパッケージを抱えるモノレポで、いま触っているのがその中の1パッケージだけなら、ルートから毎回全体を探索させる必要はありません。
この考え方は環境変数の設定より根本的な対処です。タイムアウトを引き上げる対応は「遅い探索を待つ」ための調整であるのに対し、起動場所を絞る対応は「探索そのものを速くする」ための調整だからです。モノレポでの起動場所の決め方やパッケージ単位の絞り込みはClaude Codeモノレポ設計、起動場所と除外設定の組み合わせ方はClaude Codeのコンテキスト管理で扱っています。
見落としやすい注意点
- タイムアウトを上げても上限100件は変わらない。Globは結果を最大100件で打ち切る仕様があり、この環境変数はあくまで探索にかけられる時間を延ばすだけです。100件を超える大量のファイルがヒットする状況では、パターンを絞り込む方が根本的な対処になります
- CI環境ではWSLの既定値が適用されない。60秒という長めの既定値はWSL固有の挙動で、Linux上のCIランナーやDockerコンテナでは通常の20秒が既定になります。CI側でリポジトリが大きい場合は、明示的に設定しておかないと同じタイムアウトを踏みます
- 値を上げすぎると本来の不具合を隠す。パターンの書き方が悪くて実質的に無限に近い階層を辿ってしまっているケースでも、タイムアウトを極端に長くすると「遅いが終わる」状態になり、原因の特定が先送りになります
よくある質問
CLAUDE_CODE_GLOB_TIMEOUT_SECONDSを設定するとGrepも速くなりますか
なりません。この変数が効くのはGlobツールのファイル名探索だけです。Grepはripgrepを使ったファイル内容の検索で、別の実装であり、この変数の対象外です。@によるファイル自動補完、ls、Readにも影響しません。
値に小数や0を入れるとどうなりますか
公式ドキュメントには整数の秒数として説明されています。極端に小さい値や0のような境界値の扱いは明記がないため、動作を保証したい場合は素直に整数秒で指定するのが安全です。
WSLで既定の60秒でも足りない場合はどうすればいいですか
そのままこの環境変数で値を引き上げます。WSLの60秒という既定値は、Windows側ファイルシステムのマウント越し探索を見込んだ値であり、それでも足りないほど大きなリポジトリでは、さらに大きな値を明示的に設定します。
プロジェクト設定とユーザー設定の両方に書いたらどちらが優先されますか
Claude Codeの設定ファイルは階層ごとに読み込み順が決まっていて、より狭い範囲の設定が広い範囲の設定を上書きします。同じ変数をプロジェクト単位の.claude/settings.jsonとユーザー全体の~/.claude/settings.jsonの両方に書いた場合、通常はプロジェクト側の値が使われます。設定ファイルの優先順位の全体像はClaude Code設定ガイドで確認できます。
この環境変数を設定してもタイムアウトが変わらないときは何を疑いますか
まずclaudeを起動したシェルに値が渡っているかをecho $CLAUDE_CODE_GLOB_TIMEOUT_SECONDSで確認します。空なら、設定ファイルのenvキーに書いたつもりで別の階層のファイルを編集していないか、exportした端末とClaude Codeを起動した端末が別になっていないかを見直します。値が正しく渡っているのにタイムアウトが変わらないように見える場合は、そもそも探索がタイムアウトではなく別の理由(パターンの記述ミスなど)で終わっていないかを切り分けます。
まとめ
CLAUDE_CODE_GLOB_TIMEOUT_SECONDS は、Globツールのファイル探索だけに効くタイムアウト設定です。既定は20秒、WSLは60秒で、大規模リポジトリやネットワーク越しのストレージで探索が完走しないときに引き上げます。ただし値を上げる前に、パターンを絞り込む・.gitignore対象を除外するという探索対象そのものを減らす対処を先に試す方が、根本原因に近い解決になります。Bashコマンドやその他ツールのタイムアウトは別の環境変数が担当するので、Claude Code環境変数リファレンスで全体像を確認してください。大規模コードベースでの起動場所や除外設定はClaude Codeのコンテキスト管理にまとめています。