CLAUDE_CODE_GLOB_TIMEOUT_SECONDSとは — 大規模リポジトリのGlobタイムアウト調整

CLAUDE_CODE_GLOB_TIMEOUT_SECONDS は、Claude CodeのGlobツールがファイル探索にかけられる時間を秒数で指定する環境変数です。既定値は多くの環境で20秒、WSLだけ60秒です。ただし、この変数が効くのはGlobツールが使われている間だけです。macOS・Linux・WSLではGlobが既定で無効なので、まず「自分の環境でGlobが動いているか」を見るのが先になります。

macOS・Linuxでは、この変数が効かないことがある

Globツールは、ファイル名のパターンでファイルを探す専用ツールです。Windowsでは既定のツールセットに入っています。一方、macOS・Linux・WSLではGlobもGrepも既定のツールセットから外れていて、ClaudeはfindとgrepをBashツール経由で実行して探します。Claude Codeのシェルの中では、この2つのコマンドはbfsとugrepの組み込み版として動きます。

この違いが、タイムアウト調整の前提を変えます。

Bash経由の探索はフックや権限ルールにもBashの呼び出しとして届く点が、Globツールとの実務上の違いです。

Globが復帰する条件

macOS・Linux・WSLでも、次のいずれかに当てはまるとGlobとGrepが使えるようになります。

• --toolsまたは--allowedToolsにGlobかGrepを名指しして起動する(Agent SDKの同等オプションでも同じ)。--toolsでは挙げたものだけが有効になり、--allowedToolsでどちらかを名指しすると両方が復帰する
• 権限の拒否ルール、--disallowedTools、--restrictedのいずれかでBashがセッションから外れる
• サブエージェントのtools欄にGlobかGrepがあり、Bashが含まれない

サブエージェントで復帰させる場合は、定義ファイルのtools欄にBashを入れずにGlobを並べます。

---
name: file-finder
description: ファイル名のパターンだけで該当ファイルを探す
tools: Read, Glob, Grep
---

この定義のサブエージェントでは、Globが復帰します。復帰するのはそのサブエージェントの中だけで、--agentやagent設定でメインのセッションとして動かしたときは、セッション全体でGlobとGrepが使えます。

設定ファイルに許可ルールを書くだけでは復帰しません。v2.1.289のclaude --helpでは、起動時のフラグは次のように説明されています。

claude --help | grep -A4 -E "^  --(tools|allowedTools)"

  --allowedTools, --allowed-tools <tools...>
      Comma or space-separated list of tool names to allow (e.g. "Bash(git *)
      Edit")
--
  --tools <tools...>                    Specify the list of available tools from
                                        the built-in set. Use "" to disable all
                                        tools, "default" to use all tools, or
                                        specify tool names (e.g.
                                        "Bash,Edit,Read").

Globを使う構成にするなら、たとえばclaude --tools "Bash,Read,Edit,Glob,Grep"のように名指しします。起動オプションの一覧は、claude --helpが実際のバージョンに対する正本です。

Globツールの挙動と既定値

Globは標準的なグロブ構文に対応します。**/*.jsは深さを問わずすべての.jsファイルに、src/**/*.tsはsrc/以下のすべての.tsファイルに一致します。*.{json,yaml}は、カレントディレクトリの.jsonと.yamlファイルに一致します。中身を探すGrepとは別のツールで、Globは「名前」、Grepは「中身の行」を探します。

100件の上限に達すると、Claude側に打ち切りを示すフラグが渡り、パターンを絞って再検索できます。上限は時間の問題ではないので、タイムアウトを延ばしても件数は増えません。

.gitignoreを尊重させたいときは、CLAUDE_CODE_GLOB_NO_IGNOREをfalseにして起動します。ビルド成果物や依存パッケージを抱えたリポジトリでは、探索対象そのものが小さくなります。ドットファイルを結果から外したいときはCLAUDE_CODE_GLOB_HIDDEN=falseです。CLAUDE_CODE_GLOB_HIDDENが影響するのはGlobツールの結果だけで、@によるファイル補完、ls、Grep、Readには効きません。

Grepは.gitignore対象を飛ばすため、同じリポジトリでもGlobだけがnode_modules配下のファイルを返し、探索量に差が出ます。@によるファイル補完の側はrespectGitignoreという別の設定を持っていて、CLAUDE_CODE_GLOB_NO_IGNOREとは連動しません。補完が重いときは、こちらの設定を確かめます。

設定のしかた

シェルの環境変数として渡すのが最も手早い方法です。値は秒数の整数です。

export CLAUDE_CODE_GLOB_TIMEOUT_SECONDS=60
claude --tools "Bash,Read,Edit,Glob,Grep"

端末やチームをまたいで固定したい場合は、設定ファイルのenvキーに書きます。その設定ファイルを読み込む全セッションと子プロセスに同じ値が渡ります。

{
  "env": {
    "CLAUDE_CODE_GLOB_TIMEOUT_SECONDS": "60"
  }
}

プロジェクト単位なら.claude/settings.json、ユーザー全体なら~/.claude/settings.json、組織で一律に固定するなら管理設定に書きます。同じキーを複数の階層に書いたときは、管理設定、コマンドライン、プロジェクトのローカル設定、共有のプロジェクト設定、ユーザー設定の順に優先されます。階層と優先順位の全体像はClaude Code設定ガイドにあります。

タイムアウト系の環境変数は対象が別々

Claude Codeには用途別のタイムアウト変数があり、名前が似ていて混同しやすいところです。

Globだけが秒単位で、残りの4つはどれもミリ秒単位です。変数名の末尾が_SECONDSか_MSかを見れば、単位は判別できます。2分のつもりでBashの感覚のままCLAUDE_CODE_GLOB_TIMEOUT_SECONDS=120000と入れると、2000分という桁違いの値になります。

BASH_MAX_TIMEOUT_MSの実効上限は、この値とBASH_DEFAULT_TIMEOUT_MSのうち大きい方です。macOS・LinuxでfindがBash経由になるなら、探索が長引いたときに効くのはGlobの変数ではなくBash側の既定値になります。

MCP_TOOL_TIMEOUTは、HTTP・SSE・claude.aiコネクタのサーバーに限り、1回のリクエストにも既定で60秒の制限があります。MCP_TOOL_TIMEOUTかサーバー別のtimeoutを60000より大きくすると、この制限が上がります。stdioとWebSocketのサーバーにはリクエスト単位のタイマーがありません。環境変数全般はClaude Code環境変数リファレンスにまとまっています。

Globの権限と、結果に出るもの・出ないもの

Globは手動モードでも、作業ディレクトリ内のパスなら許可の確認を求めません。作業ディレクトリと追加ディレクトリの外のパスでは、Read・Grepと同じく確認が出ます。確認が出たからといって、そのパスが実在するとは限りません。Claude Codeは、ディレクトリが存在するかを調べる前に権限を判定するためです。

権限ルールとの関係では、次の点が絞り込みの手がかりになります。

• Read(...)の拒否ルールは、Globの検索結果にも効きます。シンボリックリンク経由で届くファイルも対象で、拒否したファイルは結果に出ません
• Glob(path)という形の権限ルールは、起動時に警告が出ます。パスを絞るルールはRead(path)かEdit(path)で書きます
• patternやpathにヌルバイトが含まれると、Claudeに取り除くよう促すエラーが返ります

結果が空のとき、タイムアウトを疑う前にこの3点を見ると原因が早く分かることがあります。拒否ルールで隠れたファイルは、探索が間に合っていても結果に現れません。

探索が遅いときの切り分け

秒数を最初に上げると、探索対象を絞れば速くなるはずの遅さを待ち時間で覆い隠します。

起動場所を変える方法もあります。リポジトリのルートでなく作業中のパッケージのディレクトリでclaudeを起動すると、探索の範囲が絞れることがあります。モノレポでの起動場所の決め方はClaude Codeモノレポ設計、除外設定との組み合わせはClaude Codeのコンテキスト管理で扱っています。

Glob・Grepの近年の修正

探索まわりは更新が続いている領域です。タイムアウトに見えた症状が、すでに直った別の不具合だった例もあります。

Grepの修正も同じ型です。v2.1.208より前は、入力を拒否された検索が「ファイルなし」に見えました。v2.1.277より前は、資源不足で検索が始まらなくても「一致なし」に見えました。古いバージョンで「Globが何も返さない」ときは、タイムアウトの値より先にバージョンを確かめる価値があります。

まとめ

Windowsでは、この変数がGlobの探索時間に直接効きます。macOS・Linux・WSLで起動フラグを付けていなければ、探索はBash経由のfindなので、見るのはBASH_DEFAULT_TIMEOUT_MSです。CIなどで--toolsや--allowedToolsによりGlobを戻したときは、この変数だけが秒単位である点に注意が必要です。