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 缩减至请求的估算 token 预算。它不会生成答案或修改文件。

在 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。 Shell 安装程序会在 Apple Silicon 上选择 Metal 构建版本。仅当 Linux x86_64 上可检测到计算能力为 8.0 或更高的 NVIDIA GPU，且 CUDA 13 运行时可用时， 才会选择 CUDA 构建版本。其他受支持的主机使用便携构建版本。Homebrew 会在 Apple Silicon 上安装 Metal 构建版本，在 Intel macOS 和 Linux 上安装便携 构建版本。CUDA 和 Metal 可加速可选的 transformer 配置；所有构建版本中的默认模型都在 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 worktree 共用一个基础索引。覆盖层墓碑会隐藏该分支上已删除的基础索引文件，但不会影响其他 worktree 的搜索结果。删除仅在 worktree 中添加的文件时，会移除其覆盖层条目，无需设置基础索引墓碑。

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 指定语言，--include/--exclude 指定路径 glob，--lexical-only、--hash 和 --json。--hash 使用轻量级本地嵌入来加快启动速度，且无需下载模型，但语义质量较低。运行 ig --help 查看完整参考。

字面搜索会根据匹配行对文件进行排序。有数量限制的搜索每个文件最多显示三个预览，并报告省略的匹配项。使用 --no-limit 返回所有匹配项，或使用 --file-name-only 仅返回路径，不生成预览。

独立的大写 AND、OR 和 NOT 是布尔运算符。 例如，ig "settings NOT render" 会排除包含 render 的结果。 格式错误的短表达式（例如以 OR 结尾）会返回错误。

如果无效的布尔查询跨越多行，或至少包含 13 个单词，ivygrep 会将其作为纯文本搜索。 结果中会包含警告。CLI 会将警告写入 stderr。MCP 和 Web UI 会在 warnings 中返回警告。 有效的布尔表达式仍会保留其布尔含义，包括在较长的提示词中。 若要将运算符词作为文本搜索，请使用小写字母，或用反引号或引号括起这些词。

对于看起来像粘贴源码的多行查询，包含该片段的代码会排在仅共享部分标识符的单行定义签名之前。多段提示词、粘贴的问题文本以及包含空行的问题会按散文处理，签名匹配会像正文文本一样评分。对于粘贴的错误输出，例如回溯、Caused by: 链或 panicked at 行，词法、路径、哈希向量和重排信号会忽略工作区外路径、ID 和时间戳等运行时值，并将静态消息文本与引发该错误的代码进行匹配。神经查询向量仍会嵌入原始文本。

在 macOS 笔记本电脑上，后台神经增强会在使用电池时暂停（ig --status 会显示 Paused: Battery Power）；设置 IVYGREP_ENHANCE_ON_BATTERY=1 可让它继续运行。 轻量级哈希层会在使用电池时继续计算，以保持语义结果可用。 无论同时有多少工作区发生更改，最多只会有两个哈希增强工作线程和两个神经增强工作线程同时运行（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）：Recall@20 为 74.9%，预热 p95 为 87.63 ms。基准测试仅衡量检索能力；答案准确性不在评估范围内。

连接编码 Agent

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}}}

Agent 使用 ig_search 进行探索。当任务需要实现上下文时，设置 output=context_pack 和 budget_tokens=8000。传入当前仓库或工作树的绝对路径。工作树会复用基础索引，只存储变更的代码块和墓碑记录。

上下文包可以包含定义、调用方、引用、依赖项、依赖者、测试、配置和文档。

设置指南：Codex、Claude Code、Cursor、Gemini CLI、OpenCode 和 MCP。

推荐的 Agent 指令：

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. 上下文会通过代码关系和近期变更扩展主要命中结果， 然后将渲染后的证据裁剪至所需的令牌预算。

新索引会先发布词法结果，再增强向量。工作树会复用基础索引，只存储差异代码块和墓碑记录。部分工作区失败时会在返回有效命中结果的同时发出警告；完全失败则会报错。

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 基准测试使用了包含一百万个块的确定性合成语料库。 在三次仅使用哈希的试验中，CLI 预热后的 p95 中位数为 6.19 ms。受控索引速度达到 150,576 个块/秒。 最终索引占用 0.42 GiB。这些结果衡量的是规模和占用空间，而非检索质量或编码任务准确率。 它们不能反映当前神经模型在并发负载下的表现。

资源与延迟报告使用两个静态模型配置文件测试发布版二进制文件。 报告包含多次增强测量、强制神经模式下的 p99、八个 MCP 客户端、RSS、CPU 和磁盘写入。 模型筛选报告单独列出，因为它只进行了一次测试。

历史规模测量（v1.2.7） · 百万块测试方法 · 完整基准测试仪表板

源代码实现将缓存结果限制为 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 和来源证明。

数据与配置

所有操作系统上的索引和守护进程状态均存放在 ~/.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 可能会添加被忽略的文件， 因此这两种情况也会提示确认。

守护进程还会删除已连续缺失七天的目录索引（IVYGREP_INDEX_GC_GRACE_SECS），并在通过 git worktree remove 删除工作树十分钟后移除其覆盖层。

故障排查、升级和卸载

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：直接访问 http://127.0.0.1:4747/ 会返回 401，直到浏览器获得该 URL 设置的会话 Cookie。 如果 ig --web 打开的页面无法加载重定向文件（Ubuntu 上以 snap 打包的浏览器无法访问隐藏目录中的文件），请打开它输出的 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

请从 适合新手的议题 开始，阅读 CONTRIBUTING.md 和架构文档， 或在 Discussions 中讨论想法。

采用 MIT 许可证。由 Bruno Volpato 维护。