phuongddx/jarvis

jarvis

CI
Platforms
License: MIT
MCP

你的编码代理不应该把上下文窗口浪费在 grep 上。

当你的代理问“AuthService 在哪里被使用？”时，grep 会把注释、
markdown、测试夹具以及名称相似的符号一股脑儿地返回，杂乱无章。代理为了
从噪声中过滤出信号而重新读取文件，白白消耗上下文——而且仍然会
漏掉调用点。

jarvis 预先计算出一个本地代码智能层，让你的代理可以调用
findReferences 获取精确出现位置，调用 goToDefinition 获取定义
范围，调用 callHierarchy 获取调用路径，调用 searchCode 进行精确的词法
搜索——十个 MCP 工具，适用于 Claude Code、Cursor 或任何 MCP 客户端。
你的代码和索引永远不会离开你的机器。

| | |
|---|---|
| 没有 jarvis | Grep → 注释、测试、导入与真实命中混杂在一起 → 打开文件进行过滤 → 猜测调用点 → 把上下文浪费在搜索上而不是推理上 |
| 使用 jarvis | findReferences("AuthService") → 精确的文件与范围出现位置 → 用 callHierarchy 获取调用图 → searchCode("token refresh") → 无需打开每个匹配项即可作答 |

快速开始 · MCP 工具 · 仪表盘 · 限制 · 详情 · 文档

快速开始

1. 安装独立二进制文件：

brew install jarvis-intelligence/jarvis/jarvis

Linux 用户需要先安装 Homebrew/Linuxbrew。
该 formula 支持 macOS arm64/x86_64 和 Linux
arm64/x86_64，会同时安装 jarvis 和 jarvis-server，并内嵌 Python
3.12、仪表盘资源、tree-sitter 库、watch、scip、
zoekt-git-index 和 zoekt-webserver。Homebrew 提供
universal-ctags。无需安装 Python、uv、pip 或 PyPI。

使用 brew upgrade jarvis 升级；使用
brew reinstall jarvis 修复损坏的安装。

2. 索引一个仓库（slug 默认为目录名）：

jarvis index /path/to/your/repo

3. 注册 MCP 服务器：

claude mcp add jarvis --scope user -- jarvis-server

让你的代理“查找对 AuthService 的所有引用”——它会调用
findReferences 而不是 grep。

其他 MCP 客户端（Cursor、Claude Desktop、任何 stdio 客户端）

{
"mcpServers": {
"jarvis": {
"command": "jarvis-server"
}
}
}
如果你的客户端在 PATH 上找不到 jarvis-server（GUI 应用通常不会继承你 shell 的环境变量），请使用 which jarvis-server 得到的绝对路径。

Claude Code 插件（注册 MCP 并附带 agent skills）

先安装 Homebrew 二进制文件。该插件会添加 jarvis skills，并可以注册已安装的 jarvis-server。

/plugin marketplace add jarvis-intelligence/jarvis-index
/plugin install jarvis@jarvis

可选的语言索引器

独立包包含 SCIP 转换器和两个 Zoekt 二进制文件。
Homebrew formula 不会安装 setup.sh；请从 jarvis 源码
检出目录中，为你的仓库安装可选的按语言索引器：

| 语言 | 安装器 | 工具链 |
|---|---|---|
| TypeScript/TSX | sh setup.sh --only scip-typescript | Node.js/npm |
| Python | sh setup.sh --only scip-python | Node.js/npm |
| Java/Kotlin | sh setup.sh --only scip-java | JDK；Kotlin 仓库要求 Kotlin 必须为 2.2.0 |
| Swift | sh setup.sh --only scip-swift | macOS arm64 上的 Xcode |

对于 macOS 上使用 Maven 构建的 Java 仓库，还需使用
brew install bash 安装现代 Bash，然后从同一源码检出目录运行
sh setup.sh --only bash-shim。添加索引器后请重新索引。如果没有匹配的
索引器，在 Tree-sitter 覆盖存在的场景下，documentSymbols 和 goToDefinition 仍可工作；
findReferences、callHierarchy 和 typeHierarchy 会返回恢复
指引。

不包含的内容

semanticSearch 为兼容 MCP 而注册，但不包含在
独立发行版中。它会返回一个 Homebrew 特有的不可用错误，
并指向下方的源码构建步骤；词法搜索和符号搜索
仍然可用。

源码构建的语义搜索

独立 Homebrew 包不包含语义依赖。在源码
检出目录中，使用以下命令安装它们：

uv run jarvis install-semantic

然后显式索引：

uv run jarvis index /path/to/repo --semantic
install-semantic 还会预下载嵌入模型（BAAI/bge-m3，
约 4.3 GB，一次性）到共享的 Hugging Face 缓存
（~/.cache/huggingface/）；每个被索引的仓库都会复用它。如果下载
中断，下一次 jarvis index 会自动重试。

MCP 工具

| 工具 | 功能 |
|------|-------------|
| goToDefinition | 将符号解析到其定义文件和范围 |
| findReferences | 符号在已索引仓库中的每一次出现 |
| callHierarchy | 符号的传入/传出调用 |
| typeHierarchy | 超类型/子类型 |
| documentSymbols | 一个文件中定义的所有符号的大纲 |
| searchCode | Zoekt 词法/正则搜索，可选过滤到单个仓库 |
| semanticSearch | 返回 Homebrew 发行版的语义不可用错误 |
| blastRadius | 哪些其他已索引仓库依赖某个包，最多 2 跳 |
| getIndexStatus | 已发布的提交、新鲜度、相对于工作树的陈旧程度 |
| indexRepo | 为位于 path 的 git 仓库构建索引 |

仪表盘

jarvis dashboard          # 在 http://127.0.0.1:6080 提供服务并打开浏览器

一个 localhost Web 控制台，基于 CLI 和 MCP 服务器所读取的同一份 ~/.jarvis 数据：

 

要求和限制

- 仅支持 macOS arm64/x86_64 和 Linux arm64/x86_64。 不支持 Windows。
- Homebrew 发行版中不提供语义搜索。
- 每个仓库仅支持一种语言 —— 通过 git 跟踪文件的扩展名占比来检测；可使用 --language 覆盖。
- jarvis 从不编辑代码。 它是检索的那一半 —— Serena 在重命名/重构方面与之互补。
- 索引是显式的 —— 在查询之前运行 jarvis index（或 jarvis watch）。

详情

工作原理

一个索引 CLI 将预计算的索引写入 ~/.jarvis；一个 stdio
运行时将它们读取下来。两者之间没有其他约定。

- 发布是原子的 —— 重新索引会写入一个新快照，然后通过 os.replace 翻转 current 指针。读取旧快照的查询会继续正常工作；没有停机窗口。
- 运行时路径从不写入 —— 每次查询都以只读方式打开已发布的快照（mode=ro&immutable=1）。
- 包图是重建的，而不是累积的 —— 每次重新索引都会先清除该仓库的出边，然后再重新计算。

完整细节：docs/system-architecture.md

索引 CLI 参考

jarvis index /path/to/your/repo            # slug 默认为目录名
jarvis index /path/to/your/repo --slug foo # 或显式选择一个
jarvis index /path/to/your/repo --scheme MyScheme # 具有不明确 Xcode scheme 的 Swift 仓库
jarvis index /path/to/your/repo --language python # 强制指定语言，而不是自动检测
jarvis index /path/to/your/repo --no-scip   # 跳过可选的 SCIP 增强；语法基线 + Zoekt 仍会发布
jarvis index /path/to/your/repo --scip      # 重新启用 SCIP 增强（两个标志按仓库持久化）
jarvis list
jarvis status foo
jarvis reindex foo
jarvis forget foo
jarvis watch /path/to/your/repo [--debounce 5.0]  # 在文件更改时进行防抖自动重新索引（前台）

已知的上游限制
- scip-java 无法索引 Android/Gradle 仓库 — 其 Gradle 插件依赖于标准源集，而 AGP 会替换这些源集（scip-java#177）。自动检测；降级为仅搜索模式。
- Kotlin 索引要求 Kotlin 版本完全匹配 — scip-kotlinc 是针对一个固定版本（当前为 2.2.0）编译的。自动检测。
- Maven 构建的 Java 仓库在 macOS 上需要 bash ≥ 4.4 — brew install bash 可解决此问题。
- Swift 索引需要 scip >= v0.9.0 — 较旧的转换器会静默丢弃出现范围。jarvis index 会拒绝较旧的 scip，而不是发布损坏的索引。

配置

| 变量 | 用途 |
|----------|---------|
| JARVIS_DATA_DIR | 覆盖所有索引和注册表的默认 ~/.jarvis |

源码开发的语义路径有额外的模型前缀覆盖；
它们在独立发行版中不起作用。

文档

- docs/project-overview-pdr.md — 范围、价值主张、超出范围的事项
- docs/system-architecture.md — 架构保证、存储布局、查询路径
- docs/codebase-summary.md — 模块映射、测试覆盖率
- docs/code-standards.md — 代码模式和约定
- docs/dashboard.md — 仪表板视图、操作、安全模型

许可证

MIT