ivygrep

コードとメモを検索し、コーディングタスクのコンテキストを構築します。
ファイルとクエリはマシン上に保持されます。デフォルトのモデルは、初回使用時に固定されたアセットをダウンロードします。

ウェブサイト · アーキテクチャ · ベンチマーク · コントリビュート · ディスカッション

検索してコンテキストを構築

# Find code by intent
ig "where is refresh token rotated?"

# Build context from code and current changes
ig context "fix refresh-token races" --since main --budget 8000

出力の一部：

# ivygrep context
Budget: 7642 / 8000 estimated tokens
Coverage: 7 files | 2 primary | 1 definitions | 1 dependencies | 0 dependents | 2 callers | 0 references | 1 tests | 0 config | 0 docs
Candidates: 31 retrieved | 14 selected
## Evidence
### 1. src/auth/refresh.rs:118-166 [primary, definition]
Why: task anchor; changed implementation.
Signals: lexical, symbol, git change.

検索では、順位付けされたファイルパス、行番号、プレビューが返されます。コンテキストパックには関連するコードが追加され、各項目が選ばれた理由が説明されます。

コンテキストコマンドは、タスク、貼り付けたテキスト内のファイルパス、ステージ済みまたは未コミットの変更を使用します。 --since を指定すると、選択した参照を解決し、HEAD との Git マージベースを特定します。パックには、そのベース以降に現在のブランチでコミットされた変更に加え、ステージ済み、ステージ前、未追跡のファイルが含まれます。選択した参照自体が差分のベースになるわけではありません。 削除された変更は、git_deleted とラベル付けされた Git 履歴をコンテキストパックに含める場合があります。リリース前の削除修正では、見つからないファイルが現在の検索結果から除外されます。 パックには定義、呼び出し元、依存関係、テスト、設定、ドキュメントを含めることができます。 レンダリングされた Markdown は、指定された推定トークン数の上限に合わせて切り詰められます。回答の生成やファイルの変更は行いません。

Git ワークツリー内では、--since main、--since HEAD~3、または --since '@{upstream}' を使用します。 Git 管理されていないディレクトリでは、--since を省略してください。

インストール

# Homebrew on macOS or Linux
brew install bvolpato/tap/ivygrep

# Release installer on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.sh | sh

# WinGet on Windows
winget install --id BrunoVolpato.ivygrep --exact

# Release installer on Windows
irm https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.ps1 | iex

インストーラーは互換性のあるアーカイブを選択し、SHA-256 チェックサムを検証して、ig をインストールします。 シェルインストーラーは、Apple Silicon では Metal ビルドを選択します。Linux x86_64 で、計算能力 8.0 以上の NVIDIA GPU が認識され、CUDA 13 ランタイムが利用可能な場合に限り、CUDA を選択します。それ以外のサポート対象ホストでは、ポータブルビルドが使用されます。Homebrew は、Apple Silicon では Metal ビルドを、Intel 搭載の macOS と Linux ではポータブルビルドをインストールします。CUDA と Metal は、オプションのトランスフォーマープロファイルを高速化します。デフォルトのモデルは、どのビルドでも CPU 上で動作します。 ig hardware を実行すると、互換性を確認し、適合する再インストールコマンドを表示できます。

macOS または Linux でソースからビルドする場合：

git clone https://github.com/bvolpato/ivygrep.git && cd ivygrep
./build.sh
mkdir -p ~/.local/bin
install -m 0755 target/release/ig ~/.local/bin/ig

検索

最初のクエリでは現在のリポジトリにインデックスを作成します。その後、デーモンが変更を監視し、インデックスを増分更新します。

v1.3.1 以降では、安全なファイルリーダーによってファイルが存在しないと確認されると、ウォッチャーによる調整の前でも、そのファイルは検索対象から直ちに除外されます。その後の調整で、そのワークスペースが所有するエントリが削除されます。権限エラー、利用不可、シンボリックリンクのエラーは、削除として扱われません。それ以前のリリースでは、ファイルが存在しない場合にインデックス済みテキストへフォールバックします。

リンクされた Git ワークツリーは、ベースインデックスを共有します。オーバーレイのトゥームストーンは、そのブランチで削除されたベース由来のファイルを非表示にしますが、ほかのワークツリーでの検索には影響しません。ワークツリー内でのみ追加されたファイルを削除すると、そのオーバーレイエントリが削除され、ベースのトゥームストーンは必要ありません。

ig "where is authentication handled?"       # hybrid semantic + lexical
ig --literal "handleAuth"                    # exact indexed lookup
ig --symbol calculate_tax                    # definitions
ig --refs calculate_tax                      # references and calls
ig --callers calculate_tax                   # caller chunks
ig "database migrations" src/api/           # path scope
ig --all "retry policy"                      # all indexed projects
ig --interactive "auth flow"                 # terminal UI
ig --web "auth flow" .                       # local Web UI

便利なオプションには、結果ファイル数を指定する -n、コンテキスト行数を指定する -C、言語を指定する --type、パスの glob を指定する --include／--exclude、--lexical-only、--hash、--json があります。--hash は軽量なローカル埋め込みを使用するため、起動が速く、モデルのダウンロードも不要ですが、セマンティック検索の品質は低くなります。すべてのオプションについては、ig --help を実行してください。

リテラル検索では、一致する行を基準にファイルを順位付けします。上限付きの検索では、ファイルごとに最大 3 件のプレビューを表示し、省略された一致件数を報告します。すべての一致を返すには --no-limit を使用し、プレビューを生成せずにパスだけを返すには --file-name-only を使用します。

単独の大文字の AND、OR、NOT はブール演算子です。 たとえば、ig "settings NOT render" は render を含む結果を除外します。 末尾の OR など、短く不正な式はエラーになります。

無効なブールクエリが複数行にわたる場合、または 13 語以上の場合、ivygrep はプレーンテキストとして検索します。 結果には警告が含まれます。CLI は警告を stderr に書き込みます。MCP と Web UI は警告を warnings に返します。 有効なブール式は、長いプロンプトでもブール演算として扱われます。 演算子の単語をテキストとして検索するには、小文字を使うか、単語をバッククォートまたは引用符で囲みます。

貼り付けられたソースコードのように見える複数行のクエリでは、識別子が一部重複する 1 行の定義シグネチャよりも、そのスニペットを含むコードが上位に表示されます。複数段落のプロンプト、貼り付けられた issue のテキスト、空行を含む質問は散文として扱われ、シグネチャとの一致は本文テキストと同じようにスコア付けされます。トレースバック、Caused by: の連鎖、panicked at の行など、貼り付けられたエラー出力の場合、字句、パス、ハッシュベクトル、再ランキングの各シグナルは、ワークスペース外のパス、ID、タイムスタンプなどの実行時の値を無視し、静的なメッセージテキストを、そのメッセージを発生させるコードと照合します。ニューラルクエリベクトルには、引き続き元のテキストが埋め込まれます。

macOS のノートパソコンでは、バックグラウンドのニューラル拡張はバッテリー駆動時に一時停止します（ig --status に Paused: Battery Power と表示されます）。動作を継続するには IVYGREP_ENHANCE_ON_BATTERY=1 を設定してください。軽量なハッシュ層はバッテリー駆動時も計算を続けるため、セマンティック検索を利用できます。同時に変更されるワークスペースがいくつあっても、ハッシュ拡張ワーカーとニューラル拡張ワーカーはそれぞれ最大 2 つまで実行されます（IVYGREP_ENHANCE_MAX_WORKERS）。残りはデーモン内で待機し、最後に検索または編集されたワークスペースが優先されます。

検索メモと記憶

メモには一度だけインデックスを作成してください。ウォッチャーが最新の状態を維持し、クエリではデフォルトでローカルのセマンティック検索と字句検索が使用されます。

ig --add ~/notes --wait-for-enhancement
ig -n 20 "what did we decide about cache invalidation?" ~/notes

公開されている MemoryQuest の結果（v1.2.7）：87.63 ms の warm p95 で、recall@20 は 74.9% です。ベンチマークの対象は検索のみで、回答の正確性は対象外です。

コーディングエージェントとの接続

Codex と Claude Code のパッケージは、MCP 設定と、タスクに特化したコンテキスト用スキルをインストールします。

codex plugin marketplace add bvolpato/ivygrep
codex plugin add ivygrep@ivygrep

claude plugin marketplace add bvolpato/ivygrep
claude plugin install ivygrep@ivygrep

自動セットアップではクライアントを検出し、既存の設定を保持したまま、ig の絶対パスを書き込み、MCP のハンドシェイクを検証して検索を実行します。

ig agent install claude
ig agent install codex
ig agent install cursor
ig agent doctor

インストール後、起動中のクライアントを再起動してください。MCP の手動設定も利用できます。

claude mcp add -s user ig -- ig --mcp
codex mcp add ig -- ig --mcp
gemini mcp add --scope user --transport stdio ig ig --mcp

Cursor の .cursor/mcp.json：

{"mcpServers":{"ig":{"type": "stdio", "command": "ig", "args": ["--mcp"]}}}

OpenCode の opencode.json：

{"mcp":{"ig":{"type": "local", "command": ["ig", "--mcp"], "enabled": true}}}

エージェントは探索に ig_search を呼び出します。タスクに実装のコンテキストが必要な場合は、output=context_pack と budget_tokens=8000 を設定してください。アクティブなリポジトリまたはワークツリーの絶対パスを渡します。ワークツリーはベースインデックスを再利用し、変更されたチャンクと tombstone のみを保存します。

コンテキストパックには、定義、呼び出し元、参照、依存関係、依存先、テスト、設定、ドキュメントを含められます。

セットアップガイド：Codex、Claude Code、Cursor、Gemini CLI、OpenCode、MCP。

推奨するエージェント向け指示：

Use ivygrep before broad filesystem scans. Pass absolute active worktree path.
Use natural-language queries for concepts and literal=true for identifiers.
For implementation, request output=context_pack with budget_tokens=8000.

仕組み

1. Git 対応のウォーカーが変更されたファイル、またはインデックス化できるファイルを検出します。
2. Tree-sitter と制限付きのテキストフォールバックによって、構造化されたチャンクを生成します。
3. SQLite にメタデータと関係性を保存します。Tantivy に語彙の転置リストを保存します。USearch にハッシュベクトルとモデルベクトルを保存します。
4. クエリルーティングでは、統合の前に、範囲を限定した完全一致、語彙、シンボル、ハッシュ、および任意のニューラル検索を実行します。
5. コンテキストは、コードの関係性と最近の変更を通じて主要なヒットを拡張し、その後、レンダリングしたエビデンスを指定されたトークン予算に合わせて切り詰めます。

新規インデックス作成では、ベクトルによる拡張より先に語彙検索の結果を公開します。ワークツリーはベースインデックスを再利用し、差分のあるチャンクと tombstone のみを保存します。ワークスペースの一部で問題が発生した場合は、有効なヒットとともに警告を返し、すべてで失敗した場合はエラーを返します。

ivygrep は45種類の言語とファイル形式をサポートします。このうち24種類では、Tree-sitter AST によるチャンク化を使用します： Rust、Python、Go、JavaScript、TypeScript、Java、C、C++、C#、Kotlin、Scala、PHP、Ruby、Swift、Elixir、Zig、Bash、Haskell、OCaml、Lua、Dart、Objective-C、Perl、Starlark。

ストレージ、コミット順序、検索、ワークツリー、プロトコル、セキュリティ境界、モジュールの所有範囲については、アーキテクチャをお読みください。

システムのパフォーマンス

過去の v1.2.7 ベンチマークでは、100 万チャンクの決定論的な合成コーパスを使用しました。 ハッシュのみを使った 3 回の試行では、ウォーム状態の CLI p95 の中央値は 6.19 ms でした。制御されたインデックス作成では 150,576 チャンク/秒を達成しました。 最終的なインデックスのサイズは 0.42 GiB でした。これらの結果は規模と占有容量を測定したものであり、検索品質やコーディングタスクの精度を測定したものではありません。 また、現在のニューラルモデルの同時負荷時の性能を示すものではありません。

リソースとレイテンシのレポートでは、2 種類の静的モデルプロファイルを使用して、リリース済みバイナリを測定しています。 拡張処理の反復測定、ニューラル処理を強制した場合の p99、8 つの MCP クライアント、RSS、CPU、ディスク書き込みを含みます。 モデルのスクリーニングレポートは、1 回の反復のみを使用したため、別途公開しています。

過去の規模測定（v1.2.7） · 100 万チャンクの測定方法 · ベンチマークの全ダッシュボード

ソース実装では、キャッシュ結果を 64 MiB、キャッシュされたニューラルクエリを 4 MiB に制限しています。 解析済みコンテキスト入力には、共有の 32 MiB キャッシュがあります。コンテンツダイジェストにより、ファイルの変更後にキャッシュが再利用されることを防ぎます。 アイドル状態の検索コンテキストでは、推定 256 MiB の予算を共有します。各インデックス作成の実行には、キューに入れたペイロード用に推定 32 MiB の予算があります。 大きなファイルを単独で処理すると、インデックス作成の目標を超えることがあります。これらの予算は、プロセス全体の RSS を制限するものではありません。 適用範囲と計測コマンドについては、メモリ予算と診断を参照してください。

ローカル環境とプライバシー

実行時のソース、クエリ、埋め込み、結果、インデックスはローカルに保持されます。ニューラル プロファイルでは、キャッシュがすでに存在する場合を除き、初回使用時に固定されたモデルアセットをダウンロードします。モデルのダウンロードを避けるには、--hash、./build.sh --hash-only、または cargo build --locked --no-default-features を使用してください。

ig --web は、デフォルトでループバックにバインドします。Web API では、ループバック上でもセッショントークンが必要です。 表示された URL にはそのトークンが含まれています。トークンを記録したターミナル出力やログは非公開にしてください。 ブラウザーは、アプリのホームディレクトリにある所有者のみがアクセスできるリダイレクトファイルを介して開きます。これにより、トークンがプロセスの引数に含まれないようにしています。 ブラウザーを開かない場合は、IVYGREP_NO_BROWSER=1 を設定してください。

ループバック以外のリスナーは、平文の HTTP を使用します。信頼できるネットワーク、Tailscale、または暗号化されたトンネルを使用してください。 リスナーをインターネットに直接公開しないでください。 インデックス化されたファイルの内容がスニペットに表示される場合があります。無視ルールで許可されているドットファイルも含まれます。

脆弱性は、非公開のセキュリティアドバイザリから報告してください。リリースアーカイブには、チェックサム、SBOM、来歴情報が含まれます。

データと設定

インデックスとデーモンの状態は、すべての OS で ~/.local/share/ivygrep（Windows では %USERPROFILE% の下）に保存されます。 IVYGREP_HOME を設定するとパスが上書きされます。設定されていない場合は、空でない XDG_DATA_HOME によって $XDG_DATA_HOME/ivygrep が選択されます。 モデルアセットには Hugging Face キャッシュ（HF_HOME、デフォルトは ~/.cache/huggingface）を使用します。このキャッシュはほかのツールと共有される場合があります。

設定ファイルはありません。CLI フラグと環境変数を使用してください。

ig --status          # tracked workspaces, index health, vector coverage, disk usage
ig --rm ~/notes      # remove a saved index; defaults to current directory
ig --gc              # remove indexes whose directory has been gone past the grace period

v1.3.1 以降、CLI の検索またはコンテキスト要求、ig --interactive、または ig --add では、ホームディレクトリ、そのホームディレクトリを含むディレクトリ、または ファイルシステムのルートに対してインデックスを作成する前に、確認を求めます。y または yes で確定してください。 対話型ターミナルがない場合は、--yes を渡さない限りコマンドは停止します。 すでにインデックス化され、正常な状態にあるディレクトリは、通常の ig --add では確認を求めません。 ig --add --force はインデックスを再作成し、--skip-gitignore は無視対象のファイルを追加する可能性があるため、これらの場合も確認を求めます。

また、デーモンは 7 日間見つからない状態が続いたディレクトリのインデックス（IVYGREP_INDEX_GC_GRACE_SECS）と、git worktree remove で削除されたワークツリーのオーバーレイを 10 分後に削除します。

トラブルシューティング、アップグレード、アンインストール

ig --doctor          # diagnose index, daemon, watcher, and model health
ig --doctor --fix    # repair a broken or stale index
ig --add . --force   # rebuild current workspace index from scratch
ig hardware          # inspect detected hardware and matching build

ig --web が表示する URL を開いてください。ブラウザーにその URL が設定するセッション Cookie がない場合、http://127.0.0.1:4747/ に直接アクセスすると 401 が返されます。 Ubuntu の snap パッケージ版ブラウザーのように、隠しディレクトリ内のファイルを読み込めないブラウザーで ig --web を開いた場合は、表示された URL を開いてください。 WSL では、Windows ブラウザーでリダイレクトファイルを読み込むには、Linux のパスを変換する wslview などのオープナーを使う必要があります。それ以外の場合は、表示された URL を開いてください。

インストールに使用した方法でアップグレードしてください。brew upgrade ivygrep、winget upgrade --id BrunoVolpato.ivygrep --exact を実行するか、インストーラーを再実行してください。次のコマンドで古いビルドのデーモンが再起動します。インデックス形式が変更された場合は、初回使用時に既存のインデックスが一度再構築されます。

アンインストールするには、brew uninstall ivygrep または winget uninstall --id BrunoVolpato.ivygrep --exact を実行するか、インストーラーディレクトリ（IVYGREP_INSTALL_DIR が設定されていない場合は ~/.local/bin または %LOCALAPPDATA%\ivygrep\bin）から ig を削除してください。その後、実行中の ig --daemon プロセスを停止し、データディレクトリを削除してください。

コントリビュート

./test.sh --quick
./test.sh
./bench.sh

good first issue から始めて、CONTRIBUTING.md とアーキテクチャを読み、アイデアについては Discussions で話し合ってください。

MIT ライセンスです。Bruno Volpato がメンテナンスしています。