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

Arch LinuxでClaude Codeを使っていると、Searchツールや@fileメンション、カスタムサブエージェント、カスタムスキルが対象のファイルを見つけてくれないことがあります。原因はClaude Codeに同梱されているripgrepバイナリが、Arch上でそのまま動かないことです。pacmanでシステム側のripgrepを導入し、同梱バイナリの代わりに使うよう設定すれば解決します。

Arch Linuxで検索が効かなくなる原因

Claude CodeはSearchツール、@fileメンション、カスタムエージェントやカスタムスキルの検出にripgrep(rg)を使います。通常はインストーラーに同梱されたバイナリがそのまま動くため、意識する場面はありません。ところが環境によっては、この同梱バイナリが起動できないことがあります。症状はエラーメッセージが出るわけではなく、「検索したファイルが見つからない」「カスタムスキルを認識しない」という形で現れるため、原因がripgrepだと気づきにくいのが厄介な点です。

対処は共通しています。OSのパッケージマネージャーでripgrepを別途インストールし、Claude Codeにそちらを使わせる設定に切り替えます。Arch Linuxでの手順はpacmanだけで完結し、Alpineのようにリポジトリ登録を別途行う手間はありません。

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

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

Archの行に注意点が無いのは省略ではなく、公式ドキュメント自体がArch向けタブに追加の注記を置いていないためです。この後の設定(USE_BUILTIN_RIPGREP)は、インストールコマンドが変わってもすべての環境で共通です。

pacmanでripgrepを導入する

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

pacman -S ripgrep

追加のリポジトリ登録は不要です。同じ公式ドキュメントのAlpine向けタブでは、ripgrepがcommunityリポジトリにしか無くapk addが失敗するケースの回避策まで案内されていますが、Archのタブにはそうした注記がありません。pacman -S ripgrepを実行するだけの手順として案内されている点が、Alpineとの違いです。Alpine側の回避策自体はClaude Code Alpine Linuxセットアップの手順と注意点にまとめています。

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

which rg

パスが表示されれば、pacman経由のripgrepは使える状態です。ただしこの時点ではまだClaude Codeは同梱バイナリを使い続けているので、検索の症状自体は直っていません。

USE_BUILTIN_RIPGREPをオフにする

ripgrepを導入しただけでは、Claude Codeは引き続き同梱バイナリを使おうとします。システム側のripgrepに切り替えるには、環境変数USE_BUILTIN_RIPGREPを0に設定します。公式ドキュメントの定義は「0に設定すると、Claude Code同梱のrgの代わりにシステムにインストールされたrgを使う」というものです。

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

export USE_BUILTIN_RIPGREP=0

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

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

USE_BUILTIN_RIPGREPという環境変数名自体の仕組みや、musl libc環境での同梱バイナリの制約については、前段で紹介したAlpine Linux向けの記事で詳しく扱っています。Arch Linuxはglibc環境なので、Alpine側で問題になるmusl libcの制約は当てはまりません。

claude doctorで切り替えを確認する

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

claude doctor

Search行の表示がOK (bundled)のままなら、Claude Codeはまだ同梱バイナリを使っています。切り替えが効いていれば、Search行にシステム側ripgrepのパスが表示されます。pacman -S ripgrepを実行したのに検索が直らない場合、USE_BUILTIN_RIPGREPの設定を入れ忘れているケースが大半なので、まずこの表示を見てください。設定ファイルの構文が壊れている場合もclaude doctorが検出して知らせます。claude doctorはセッションを開始せず、読み取り専用のインストール診断だけを表示するコマンドです。Claude Codeのセッション内で打つ/doctorとは別物で、両者の違いはClaude Codeの/doctorが自動修正までするチェックアップになった仕組みにまとめています。

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

claude doctorのSearch行が変わったら、Claude Codeを起動して実際に検索を試します。適当なキーワードで@メンションを打ち、対象のファイルが候補に出てくるかを確認するのが手早い方法です。カスタムスキルやカスタムサブエージェントを使っている場合は、/skillsや該当のサブエージェント名を打って一覧に出てくるかも合わせて確認してください。ここで見つからなければ、ripgrep以外の原因(ファイルパスの権限やプロジェクトディレクトリの指定ミスなど)を疑う段階に進みます。claude doctorのSearch行だけを見て安心せず、実際の検索動作まで確かめておくと、後から原因の切り分けに迷いません。

CLAUDE_CODE_USE_NATIVE_FILE_SEARCHと混同しない

環境変数を検索していると、似た名前のCLAUDE_CODE_USE_NATIVE_FILE_SEARCHに行き当たることがあります。これは別の設定です。1に設定すると、カスタムコマンド・サブエージェント・出力スタイルの検出方法を、ripgrepベースからNode.jsのファイルAPIベースに切り替えます。公式ドキュメントは「Grepツールやファイル検索そのものには影響しない」と明記しており、Searchツールや@fileメンションの検索結果には作用しません。ripgrepが動かないことによる検索の失敗を直そうとしてCLAUDE_CODE_USE_NATIVE_FILE_SEARCHを設定しても、症状は変わりません。直す対象はUSE_BUILTIN_RIPGREPです。名前が似ているだけの別の環境変数だと理解しておけば、切り分けの手間を省けます。

サンドボックス機能を使っている場合の設定

Bashツールのサンドボックス化を有効にしている場合、サンドボックス内で使うripgrepはsettings.jsonのsandbox.ripgrepキーで個別に指定できます。既定は未設定で、その場合サンドボックスもClaude Code本体と同じripgrepバイナリを使います。つまりUSE_BUILTIN_RIPGREPを0にしていなければ同梱バイナリ、0にしていればpacmanで導入したバイナリが、サンドボックス内でもそのまま使われます。sandbox.ripgrepを明示的に指定する必要があるのは、サンドボックス側だけ別のripgrepバイナリを使わせたい場合に限られます。pacmanで導入したripgrepは通常/usr/bin/rgに配置されるため、大半の環境ではUSE_BUILTIN_RIPGREPの設定だけで足り、sandbox.ripgrepまで触る必要はありません。ソースからビルドしたripgrepを/usr/bin以外の場所に置いている場合など、パスが標準と異なるときに使う設定だと考えてください。

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

Arch Linuxはシステム要件の一覧に含まれていない

公式ドキュメントのシステム要件ページに挙げられているOSは、macOS 13.0以降・Windows 10 1809以降またはWindows Server 2019以降・Ubuntu 20.04以降・Debian 10以降・Alpine Linux 3.19以降の5つです。Arch Linuxはこの一覧に含まれていません。一方で、同じ公式ドキュメントのtroubleshootingページには、ripgrepインストール手順としてArch向けのpacmanタブが用意されています。システム要件の動作確認対象としては明記されていない一方、遭遇しうる不具合への対処は個別に用意されている、という状態です。

ハードウェアの要件(4GB以上のRAM、x64またはARM64プロセッサ)とシェルの要件(Bash・Zsh・PowerShell・CMD)、ネットワーク接続の要件は、OSを問わず共通の項目として挙げられています。バージョン番号のように「Arch Linuxではいくつ以上」という形で個別に定義された下限は存在せず、システム要件ページ自体がArch Linuxを対象に含めていません。動作しないと断定する根拠にはなりませんが、トラブルの原因切り分けに時間をかける前に、この非対称な扱いを念頭に置いておくと状況を理解しやすくなります。

よくあるつまずき

pacmanでripgrepを入れたのに検索が直らない

ripgrepの導入自体は成功していても、USE_BUILTIN_RIPGREPを0に設定していないと、Claude Codeは同梱バイナリを使おうとして同じ症状が続きます。settings.jsonのenvキーか、シェルの環境変数を見直してください。

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

WSL上でファイルシステムをまたいだ読み取り性能が理由で、検索結果が期待より少なくなる現象は、Arch Linuxでのripgrep起動失敗とは別の問題です。claude doctorのSearch行はこのケースでもOKと表示されます。WSL固有の対処はClaude Code WSL2セットアップ — パスとNode.js、sandboxの落とし穴を参照してください。

まとめ

Arch LinuxでClaude Codeの検索が効かない場合、まずpacman -S ripgrepでシステム側のripgrepを導入し、次にUSE_BUILTIN_RIPGREPを0に設定します。シェルの環境変数でもsettings.jsonのenvキーでも構いません。設定後はclaude doctorを実行し、Search行がシステム側ripgrepのパスを示しているかを確認します。OK (bundled)のままなら、USE_BUILTIN_RIPGREPの設定漏れを疑ってください。