一种像 grep 一样工作的自然语言搜索工具。快速、本地化，专为编码智能体打造。

• 语义性： 查找概念（“事务在哪里创建？”），而不仅仅是字符串。
• 调用图追踪： 使用 trace 命令映射依赖关系，查看谁调用了什么。
• 角色检测： 区分 ORCHESTRATION（高层逻辑）和 DEFINITION（类型/类）。
• 本地与私密： 通过 onnxruntime-node 实现 100% 的本地嵌入。
• 自动隔离： 每个仓库都会自动获得自己的索引。
• 适配智能体： 原生输出包含符号、角色和调用图。

快速入门

1. 安装

   npm install -g osgrep
   

2. 设置（推荐）

   osgrep setup
   

   会预先下载嵌入模型（约 150MB）。如果你跳过这一步，模型会在首次使用时自动下载。

3. 搜索

   cd my-repo
   osgrep "我们在哪里处理认证？"
   

   你的第一次搜索会自动为该仓库建立索引。 每个仓库都会自动隔离并拥有独立的索引。在不同仓库之间切换“无缝衔接”——无需手动配置。如果后台服务正在运行（osgrep serve），搜索将通过热守护进程进行；否则会回退到按需索引。

4. 追踪（调用图）

   osgrep trace "function_name"
   

查看哪些代码调用了某个函数（上游依赖），以及该函数又调用了哪些代码（下游依赖）。非常适合影响分析和理解代码流程。

要查找代码库中的符号： bash osgrep symbols

在我们的公开基准测试中，osgrep 可以节省约 20% 的 LLM token，并提升 30% 的速度。

Claude Code 插件

1. 运行 osgrep install-claude-code
2. 打开 Claude Code（claude），并向它询问关于你代码库的问题。
3. 强烈建议在使用插件前先对代码库进行索引。
4. 插件的钩子会自动在后台启动 osgrep serve，并在会话结束时关闭它。Claude 会自动使用 osgrep 进行语义搜索，但也可以被主动引导使用。

Opencode 插件

1. 运行 osgrep install-opencode
2. 打开 OC（opencode），并向它询问关于你代码库的问题。
3. 强烈建议在使用插件前先对代码库进行索引。
4. 插件的钩子会自动在后台启动 osgrep serve，并在会话结束时关闭它。OC 会自动使用 osgrep 进行语义搜索，但也可以被主动引导使用。

命令

osgrep search

默认命令。使用语义含义搜索当前目录。

osgrep "数据库连接是如何池化的？"

选项：

标志	描述	默认值
-m <n>	最多返回的结果总数。	25
--per-file <n>	每个文件最多显示匹配结果数。	1
-c, --content	显示完整内容块而非片段。	false
--scores	显示每个结果的相关性分数（0-1）。	false
--min-score <n>	过滤掉低于此分数阈值的结果。	0
--compact	仅显示文件路径（类似 grep -l）。	false
-s, --sync	强制在搜索前重新索引已更改的文件。	false
-r, --reset	重置索引并从头开始重新索引。	false

示例：

# 通用概念搜索
osgrep "API 速率限制逻辑"

# 深入挖掘（每个文件显示更多匹配）
osgrep "错误处理" --per-file 5

# 只给我文件
osgrep "用户验证" --compact

# 显示相关性分数并过滤低置信度匹配
osgrep "认证" --scores --min-score 0.5

osgrep index

手动为仓库建立索引。当你想预热缓存，或者在编辑器之外进行了大量更改时非常有用。

• 遵循 .gitignore 和 .osgrepignore 文件规则（参见 配置 部分）。
• 智能索引： 只对代码和配置文件进行嵌入。跳过二进制文件、锁文件和压缩资源。
• 有限并发： 使用固定线程池，以保持系统响应能力。
• 语义分块： 对支持的语言使用 TreeSitter 语法解析器（TypeScript、JavaScript、Python、Go、Rust、C/C++、Java、C#、Ruby、PHP、JSON、YAML、Kotlin、Swift、Dart）。

选项：

标志	描述	默认值
-d, --dry-run	查看哪些内容会被索引，而不实际进行更改。	false
-p, --path <dir>	要索引的路径（默认为当前目录）。	.
-r, --reset	删除现有索引并从头开始重新索引。	false
-v, --verbose	显示带有文件名的详细进度。	false
--allow-fallback	也索引没有 TreeSitter 语法支持的文件。	false

示例：

osgrep index                    # 索引当前目录
osgrep index --dry-run          # 查看哪些内容会被索引
osgrep index --verbose          # 观察详细进度（适合调试）
osgrep index --allow-fallback   # 包括没有语法支持的文件
osgrep index --reset            # 完全从头重新索引

osgrep serve

运行一个轻量级的 HTTP 服务器，并实时监控文件变化，使搜索结果始终驻留在内存中。

• 保持 LanceDB 和嵌入式工作进程常驻，以实现小于 50 毫秒的响应时间。
• 使用 chokidar 监控仓库，并在文件发生变化时增量地重新索引。
• 健康检查端点：GET /health
• 搜索端点：POST /search，请求体包含 { query, limit, path, rerank }
• 写锁文件：.osgrep/server.json，记录 port 和 pid。

选项：

标志	描述
-p, --port <port>	监听的端口（未指定时自动递增）
-b, --background	在后台运行服务器并立即退出

端口选择优先级：

1. 显式指定的 -p <port> 标志
2. OSGREP_PORT 环境变量
3. 自动从注册表中递增（上次使用的端口 + 1，如果没有服务器则使用 4444）

使用示例：

osgrep serve                    # 前台运行，端口 4444（或下一个可用端口）
osgrep serve --background       # 后台模式，自动分配端口
osgrep serve -b -p 5000         # 在指定端口上后台运行

子命令：

osgrep serve status             # 显示当前目录下的服务器状态
osgrep serve stop               # 停止当前目录下的服务器
osgrep serve stop --all         # 停止所有正在运行的 osgrep 服务器

示例工作流：

# 在多个项目中启动服务器
cd ~/project-a && osgrep serve -b    # 在端口 4444 上启动
cd ~/project-b && osgrep serve -b    # 在端口 4445 上启动（自动递增）

# 检查状态
osgrep serve status

# 完成后停止所有服务器
osgrep serve stop --all

Claude Code 会自动启动和停止此服务；通常情况下，您无需手动运行它。

osgrep list

列出所有已索引的仓库（存储）及其元数据。

osgrep list

显示存储名称、大小和最后修改时间。有助于查看哪些内容已被索引，并清理旧的存储。

osgrep skeleton

生成文件的压缩“骨架”，仅显示签名、类型和类结构，而省略函数体。

osgrep skeleton src/lib/auth.ts

输出：

class AuthService {
  validate(token: string): boolean {
    // → jwt.verify, checkScope, .. | C:5 | ORCH
  }
}

模式：

• osgrep skeleton <file>：对特定文件进行骨架化。
• osgrep skeleton <Symbol>：在索引中查找符号并对其所在文件进行骨架化。
• osgrep skeleton "query"：搜索查询并对前几条匹配结果进行骨架化。

支持的语言： TypeScript、JavaScript、Python、Go、Rust、Java、C#、C++、C、Ruby、PHP。

osgrep doctor

检查安装健康状况、模型路径和数据库完整性。

osgrep doctor

性能与架构

osgrep 被设计为一台“好公民”式的机器：

1. 有限并发： 分块和嵌入操作限制在小型线程池内（1–4 个线程），并通过限制批处理大小来确保笔记本电脑的响应能力。
2. 智能分块： 使用 tree-sitter 按照函数或类的边界分割代码，确保嵌入能够捕捉完整的逻辑块。
3. 去重： 相同的代码块（如样板代码、许可证头）只会被嵌入一次并缓存，从而节省空间和时间。
4. 语义拆分搜索： 分别查询“代码”和“文档”，以确保文档不会掩盖实现细节，然后使用 ColBERT 进行重新排序。
5. 全局批处理： 生产者/消费者管道将分块与嵌入分离。文件可以并行分块，放入队列，以较大的批次进行嵌入，并批量写入 LanceDB。
6. 仅锚点扫描与批量删除： 文件发现和过期清理只影响锚点行，过期或更改的路径通过单次 IN 删除操作移除，以最小化 I/O 开销。
7. 结构增强： 函数和类的分块会获得轻微的分数提升；测试和规范路径的权重则稍低，以便优先显示主要定义。
8. 角色分类： 检测“编排”函数（复杂度高、调用多）与“定义”（类型或类）之间的区别，帮助代理程序确定阅读的重点。

配置

自动仓库隔离

osgrep 会根据以下规则自动为每个仓库创建唯一的索引：

1. Git 远程 URL（例如 github.com/facebook/react → facebook-react）
2. 无远程的 Git 仓库 → 目录名加哈希值（例如 utils-7f8a2b3c）
3. 非 Git 目录 → 目录名加哈希值，以避免冲突

示例：

cd ~/work/myproject        # 自动检测：owner-myproject
osgrep "API handlers"

cd ~/personal/utils        # 自动检测：utils-abc12345
osgrep "helper functions"

存储会自动隔离——无需手动指定 --store 参数！

忽略文件

osgrep 在索引时会同时尊重 .gitignore 和 .osgrepignore 文件。您可以在仓库根目录下创建 .osgrepignore 文件，以排除额外的文件或模式。

.osgrepignore 语法：

• 使用与 .gitignore 相同的模式语法
• 模式相对于仓库根目录
• 支持 glob 模式、否定（!）和目录模式（/）

手动管理存储

• 查看所有存储： osgrep list
• 覆盖自动检测： osgrep --store custom-name "query"
• 清理旧存储： rm -rf ~/.osgrep/data/store-name
• 数据位置： ~/.osgrep/data

开发

pnpm install
pnpm build        # 或 pnpm dev
pnpm format       # biome 检查

故障排除

• 索引感觉过时？ 运行 osgrep index 来刷新索引。
• 结果奇怪？ 运行 osgrep doctor 来验证模型。
• 索引卡住？ 运行 osgrep index --verbose 查看正在处理的文件。
• 希望加快索引速度？ 保持备用方案关闭（默认设置），以跳过不支持 TreeSitter 的文件。
• 需要全新开始？ 删除 ~/.osgrep/data 和 ~/.osgrep/meta.json，然后运行 osgrep index。

归属声明

osgrep 是基于 MixedBread 公司的 mgrep 构建的。我们承认并感谢原始架构理念和设计决策对本项目的启发。

详细归属信息请参阅 NOTICE 文件。

许可证

根据 Apache License, Version 2.0 许可。详细信息请参阅 LICENSE 和 Apache-2.0。

osgrep 快速上手指南

osgrep 是一款专为编程助手（Coding Agent）设计的本地语义搜索工具。它像 grep 一样快速，但能理解代码概念而非仅仅匹配字符串，支持调用链追踪和角色检测，且所有数据均在本地处理，保障隐私。

环境准备

• 操作系统：支持 macOS、Linux 和 Windows。
• 前置依赖：
  • Node.js：需安装 Node.js 环境（推荐 LTS 版本），因为工具基于 onnxruntime-node 运行。
  • Git（可选）：用于自动识别仓库来源以实现索引隔离，非 Git 目录也可使用。
• 网络要求：首次运行或执行 setup 时需要下载嵌入模型（约 150MB）。国内用户若遇到下载缓慢，可尝试配置全局代理或使用网络加速工具。

安装步骤

1. 全局安装工具 使用 npm 进行全局安装：

   npm install -g osgrep
   

2. 预下载模型（推荐） 执行设置命令以提前下载所需的嵌入模型，避免首次搜索时等待：

   osgrep setup
   

   注：若跳过此步，模型将在第一次执行搜索命令时自动下载。

基本使用

osgrep 采用“按需索引”机制，每个仓库会自动生成独立的索引，切换项目无需手动配置。

1. 语义搜索

进入你的代码仓库目录，直接使用自然语言提问。首次在该目录搜索时会自动建立索引。

cd my-repo
osgrep "where do we handle authentication?"

常用搜索示例：

# 搜索概念（如：数据库连接池是如何实现的？）
osgrep "how is the database connection pooled?"

# 仅显示匹配的文件路径（类似 grep -l）
osgrep "user validation" --compact

# 显示相关性评分并过滤低置信度结果
osgrep "authentication" --scores --min-score 0.5

2. 调用链追踪 (Trace)

分析函数的上下游依赖关系，查看谁调用了该函数，以及该函数调用了谁。

osgrep trace "function_name"

3. 查看代码骨架 (Skeleton)

快速查看文件的结构、类型和类定义，隐藏具体实现细节，适合快速浏览大文件。

osgrep skeleton src/lib/auth.ts

4. 集成编程助手 (可选)

如果你使用 Claude Code 或 Opencode，可以安装插件让助手自动调用 osgrep 进行语义搜索。

安装 Claude Code 插件：

osgrep install-claude-code

安装 Opencode 插件：

osgrep install-opencode

安装后，在对应的助手会话中提问代码库相关问题时，它将自动利用 osgrep 进行检索。

5. 后台服务模式 (可选)

为了获得毫秒级的响应速度，可以在后台启动服务进程（热守护进程），它会监听文件变化并增量更新索引。

# 后台启动服务
osgrep serve --background

# 查看服务状态
osgrep serve status

# 停止所有服务
osgrep serve stop --all

注：使用上述插件时，服务通常会自动启停，无需手动操作。