Claude CodeでArch Linuxの検索が効かない原因と直し方

Arch LinuxでClaude Codeを使っていると、Searchツールや@fileメンション、カスタムサブエージェント、カスタムスキルが対象のファイルを見つけてくれないことがあります。公式のトラブルシューティングが挙げる原因は、Claude Codeに同梱されているripgrepバイナリがその環境で動かないことです。pacmanでシステム側のripgrepを入れ、同梱版の代わりに使わせれば直ります。

検索が効かないとき、どの順で切り分けるか

Claude CodeはSearchツール、@fileメンション、カスタムエージェントやカスタムスキルの検出にripgrep(rg)を使います。通常はインストーラーに同梱されたバイナリが動くので意識する場面はありません。同梱版が動かない環境では、検索が失敗する形で症状が現れます。

OSごとのripgrepインストールコマンド

公式ドキュメントのtroubleshootingページには、主要な環境ごとにripgrepのインストールコマンドがタブで並んでいます。

Archのタブには追加の注記がなく、pacman -S ripgrepの1行だけが載っています。この後のUSE_BUILTIN_RIPGREPの設定は、インストールコマンドが変わってもすべての環境で共通です。

pacmanでripgrepを導入する

Arch Linuxではpacmanでripgrepを導入します。

pacman -S ripgrep

Alpineのタブには「apkがパッケージが無いと言ったらcommunityリポジトリを足す」という案内がありますが、Archのタブには同種の案内がありません。Alpine側の事情はClaude Code Alpine Linuxセットアップの手順と注意点にまとめています。

導入できたかどうかはwhich rgで確認できます。

which rg

パスが表示されれば、システム側のripgrepは使える状態です。

USE_BUILTIN_RIPGREPで同梱版からシステム版に切り替える

環境変数USE_BUILTIN_RIPGREPを0にすると、Claude Code同梱のrgの代わりにシステムにインストールされたrgが使われます。env-varsページの定義は「Set to 0 to use system-installed rg instead of rg included with Claude Code」の1行です。

設定方法は2つあります。1つはシェルの環境変数です。

export USE_BUILTIN_RIPGREP=0

もう1つはsettings.jsonのenvキーです。チームで設定を共有したい場合や、シェルの起動ファイルを触りたくない場合に向いています。

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Alpineのようなmusl系ディストリビューションでも、setupページは同じUSE_BUILTIN_RIPGREP=0を指示しています。そちらではlibgcc・libstdc++・ripgrepが実行時に必要な依存として挙がっており、Alpineではripgrepの導入が前提条件です。Archのtroubleshootingタブにこうした前提の記載はなく、検索が失敗したときの対処としてripgrepが案内されています。

claude doctorのSearch行は何を示すか

設定が反映されたかどうかは、ターミナルからclaude doctorを実行して確認します。

claude doctor

claude doctorはセッションを開かず、--helpによればカレントディレクトリの設定ファイルを信頼確認なしで読む診断コマンドです。セッション内の/doctorが自動修正まで行う点は、Claude Codeの/doctorが自動修正までするチェックアップになった仕組みで扱っています。

v2.1.289(macOS)で、空の作業ディレクトリと空の設定ディレクトリを使って実行すると、冒頭は次のように出ます。Search行が、同梱版かシステム版かを示します。

Claude Code doctor
 
Running: native (2.1.289)
Platform: darwin-arm64
Path: ~/.local/share/claude/versions/2.1.289
Search: OK (bundled)
Auto-updates: enabled

pacman -S ripgrepを実行したのに表示が変わらないときは、まず環境変数が実行時のシェルまで届いているかを疑います。settings.jsonのenvに書いた場合は、そのファイルが読まれる場所(ユーザー設定かプロジェクト設定か)も確認してください。

検索が直ったかを実際に試す

claude doctorのSearch行が変わったら、Claude Codeを起動して実際に検索を試します。適当なキーワードで@メンションを打ち、対象のファイルが候補に出るかを見るのが手早い方法です。カスタムスキルやカスタムサブエージェントを使っているなら、/skillsや該当のサブエージェント名が一覧に出るかも合わせて確認します。

CLAUDE_CODE_USE_NATIVE_FILE_SEARCHとの違い

環境変数を探していると、似た名前のCLAUDE_CODE_USE_NATIVE_FILE_SEARCHに行き当たります。これは対象が違う別の設定です。

env-varsページは後者を「同梱のripgrepが使えない、またはブロックされている環境向け」と位置付けています。カスタムコマンドやサブエージェントが見つからないだけなら試す余地がありますが、@fileやSearchまで直すにはUSE_BUILTIN_RIPGREP側が必要です。

サンドボックスを使っている場合のsandbox.ripgrep

Bashツールのサンドボックスを有効にしている場合、サンドボックスが使うripgrepはsettings.jsonのsandbox.ripgrepで別に指定できます。settings-referenceでは、このキーは既定で未設定です。その場合、サンドボックスはClaude Codeと同じバイナリを使います。同梱版か、USE_BUILTIN_RIPGREP=0のときのシステム版かは、環境変数で決まります。

sandbox.ripgrepが要るのは、サンドボックスにだけ別ビルドのrgを使わせたいときです。commandにrgのパスを書き、必要ならargsで先頭に付ける引数を足します。

{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}

上の/usr/local/bin/rgはsettings-referenceの例の値です。自分の環境のパスはwhich rgの出力に合わせます。このキーのスコープは、settings-referenceにユーザー設定または管理設定と記されています。

Arch Linuxはシステム要件の一覧にない

setupページのシステム要件に並ぶOSは、macOS 13.0以降、Windows 10 1809以降またはWindows Server 2019以降、Ubuntu 20.04以降、Debian 10以降、Alpine Linux 3.19以降の5系統です。Arch Linuxは入っていません。一方、同じ公式ドキュメントのtroubleshootingには、Arch向けのpacmanタブが用意されています。サポートOSの一覧と不具合の対処手順で、扱いが非対称です。

ハードウェア(4GB以上のRAM、x64またはARM64プロセッサ)、シェル(Bash・Zsh・PowerShell・CMD)、ネットワーク接続は、OSを問わない共通の要件です。setupページの追加依存の欄は、ripgrepを「通常はClaude Codeに含まれる」と書き、検索が失敗するときはトラブルシューティングへ誘導しています。Arch向けの個別の下限バージョンは定義されていません。

よくあるつまずき

WSLで検索結果が少ないのはripgrepの問題ではない

WSLでファイルシステムをまたぐと、ディスク読み取り性能の影響で、期待より少ない件数しか返らないことがあります。公式によれば検索自体は動き、claude doctorのSearch行もOKと表示されます。対処はプロジェクトをLinux側のファイルシステム(/home/)に置くことと、ディレクトリやファイル種別を絞った検索を依頼することです。WSL固有の設定はClaude Code WSL2セットアップ — パスとNode.js、sandboxの落とし穴を参照してください。

まとめ

Arch Linuxで検索が効かないときは、pacman -S ripgrepとUSE_BUILTIN_RIPGREP=0をセットで入れ、claude doctorのSearch行がrgのパスに変わったかで成否を判断します。