shire (Justinjdev)

郡

.,:lccc:,. .,codxkkOOOOkkxdoc,. .;ldkkOOOOOOOOOOOOOOOkkdl;. .:oxOOkxdollccccccccllodxkOOkxo:. ,lkOOxl;.. ..,lxOOkl, .ckOOd:. .:dOOkc. ;xOOo, .,clllc,. ,oOOx; lOOk; .:dkOOOOOOkd:. ;kOOl oOOx, .ckOOOOOOOOOOOOkc. ,xOOo lOOk, ;xOOOkdl:;;:ldkOOOx; ,kOOl ;OOO; lOOOd;. .;dOOOl ;OOO; dOOd :OOOl lOOO: dOOd kOOl oOOx .;;. xOOo lOOk kOOl oOOx .xOOx. xOOo lOOk dOOd :OOOl .oOOo. lOOO: dOOd ;OOO; lOOOd;. .,,. .;dOOOl ;OOO; lOOk, ;xOOOkdl:,:ldkOOOx; ,kOOl oOOx, .ckOOOOOOOOOOOOkc. ,xOOo lOOk; .:dkOOOOOOkd:. ;kOOl ;xOOo, .,clllc,. ,oOOx; .ckOOd:. .:dOOkc. ,lkOOxl;.. ..,lxOOkl, .:oxOOkxdollccccccccllodxkOOkxo:. .;ldkkOOOOOOOOOOOOOOOkkdl;. .,codxkkOOOOkkxdoc,. .,:lccc:,.

*一个指标来统治他们所有人。*

S搜索， H层次结构， 一、指数， R欧洲专利局 Eexplorer——一个单仓库包索引器，在SQLite中构建依赖图并为其提供服务 模型上下文协议.

把它指向一个monorepo。它发现每个包，映射它们的依赖关系，并为您的AI工具提供对结果的结构化访问。

它做什么

shire build 遍历存储库，解析清单文件，并使用全文搜索将包和依赖项存储在本地SQLite数据库中。它还使用树形图从源文件中提取公共符号（函数、类、类型、方法），并具有完整的签名、参数和返回类型。对于8种一级语言（Go、Python、Java、TypeScript、JavaScript、Perl、Ruby、Scala），shire还提取存储在 symbol_refs 调用图和影响查询表。仓库中的每个文件都用其路径、扩展名、大小和所属包进行索引，以便即时查找文件。 shire serve 通过stdio将该索引作为MCP服务器公开。

支持的生态系统：

安装

家酿 （macOS、Linux）：

brew tap justinjdev/shire
brew install shire

来自预构建的二进制文件 （macOS、Linux）：

从下载最新版本 并添加到您的PATH中。

来源：

cargo install --path .

# With RAG vector search support (~30-50MB larger binary due to ONNX Runtime):
cargo install --path . --features rag

用法

# Index a monorepo
shire build --root /path/to/repo

# Rebuild from scratch (ignore cached hashes)
shire build --root /path/to/repo --force

# Write the index to a custom location
shire build --root /path/to/repo --db /tmp/my-index.db

# Start the MCP server
shire serve

# Auto-rebuild: start watch daemon, then stop it
shire watch --root /path/to/repo
shire watch --root /path/to/repo --stop

# Signal a rebuild (from a hook or manually)
shire rebuild --root /path/to/repo

# Initialize config
shire init              # project-level shire.toml
shire init --global     # global ~/.claude/ config for all projects

# Register with all detected AI tools (Claude Code, Cursor, VS Code, etc.)
shire install
shire install --force   # overwrite existing registrations
shire uninstall         # remove from all tools

CLI参考

该索引被写入 .shire/index.db 默认情况下位于repo根目录内。你可以用以下命令覆盖它 --db 在build命令上或 db_path 在 shire.toml （参见 配置).后续版本为 渐进的 --只有内容已更改（通过SHA-256哈希）的清单才会被重新解析。源文件也会被跟踪：如果源文件在没有清单更改的情况下发生更改，则会自动重新提取符号。一 mtime预检 对于自上次构建以来源文件未被修改的包，完全跳过SHA-256计算。文件索引也是增量的——文件树哈希检测结构变化，当没有添加、删除或调整大小的文件时，完全跳过第9阶段。符号提取和源哈希是 并行化 使用人造丝实现多核吞吐量。所有数据库写入使用 分批多排插入式 在显式事务中实现最大SQLite吞吐量。A每相 定时故障 每次构建后都会打印到stderr。服务器以只读模式读取此数据库。

MCP工具

MCP提示

提示是用于语义代码库探索的预构建模板。它们将多个查询组合到结构化上下文中，为您的AI提供概念在代码库中的位置图。

克劳德代码

快速设置 --一个命令为所有项目全局配置shire：

shire init --global

这将创建：

• ~/.claude/shire.toml 和 db_path = "~/.claude/shire/{repo}/index.db" （每个回购自动命名）
• mcpServers.shire 报关进口 ~/.claude/settings.json
• PostToolUse 文件编辑后自动重建索引的钩子

按需模式 --跳过钩子，让MCP服务器自动重建：

shire init --global --no-hook

随着 --no-hook，MCP服务器以 --root . 并在每次查询之前通过比较来检查索引是否过时 .git/index mtime与上次构建时间戳的比较。如果过时，它会自动重建。未安装PostToolUse挂钩。这更简单，但可能会在更改后增加第一个查询的延迟。

按回购设置 --用于项目级配置（创建 shire.toml 和 .claude/settings.local.json):

cd /path/to/repo
shire init          # with PostToolUse hook (default)
shire init --no-hook  # or with on-demand reindexing
shire build

配置已通过回退链解决： ./shire.toml → ~/.claude/shire.toml → 默认值。这意味着 shire build, shire serve，以及 shire watch 当不存在本地配置时，自动获取全局配置。相对的 db_path 值（例如。， tmp/index.db)针对回购根进行解析。

Manual setup

添加 ~/.claude/settings.json （全球）或 .claude/settings.local.json （每次回购）：

{
  "mcpServers": {
    "shire": {
      "command": "shire",
      "args": ["serve"]
    }
  }
}

要在会话期间保持索引新鲜，请添加 PostToolUse 挂钩：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit|Bash",
        "hooks": [{ "type": "command", "command": "shire rebuild --stdin" }]
      }
    ]
  }
}

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "shire": {
      "command": "shire",
      "args": ["serve", "--db", "/path/to/repo/.shire/index.db"]
    }
  }
}

监视守护进程

shire watch 启动一个后台守护进程，在文件更改时自动重建索引。它使用Unix域套接字IPC，具有可配置的去抖动（默认为2s）。

# Start the daemon (idempotent — safe to call multiple times)
shire watch --root /path/to/repo

# Signal a rebuild manually
shire rebuild --root /path/to/repo

# Signal a rebuild from a Claude Code hook (reads JSON from stdin, uses cwd as repo root)
shire rebuild --stdin

# Stop the daemon
shire watch --root /path/to/repo --stop

智能过滤避免了不必要的重建：编辑/写入工具检查文件扩展名相关性和仓库边界；Bash命令根据已知只读命令的列表进行过滤(ls, git status, cargo test等）——未知命令默认重建。

配置

放下一个 shire.toml 在repo根目录中自定义行为。如果没有本地配置，夏尔将退回 ~/.claude/shire.toml （由创建 shire init --global).您还可以使用以下命令指向特定的配置 --config.

# Custom database location (default: .shire/index.db)
# Supports ~ expansion, $ENV_VARs, and {repo} (replaced with repo dir name)
db_path = "~/.claude/shire/{repo}/index.db"

[discovery]
manifests = ["package.json", "go.mod", "go.work", "Cargo.toml", "pyproject.toml", "pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "cpanfile", "Gemfile"]
exclude = ["node_modules", "vendor", "dist", ".build", "target", "third_party", ".shire", ".gradle", "build"]

# Skip symbol extraction for specific file types
[symbols]
exclude_extensions = [".proto", ".pl"]

# Override package descriptions
[[packages]]
name = "legacy-auth"
description = "Deprecated auth service — do not add new dependencies"

所有字段都是可选的。默认值如上所示。这 --db CLI标志优先于 db_path 在配置中。

RAG矢量搜索

RAG增加了语义向量搜索 search_symbols。它需要使用 rag 功能标志并在配置中启用它。

在RAG支持下构建：

cargo install --path . --features rag

启用 shire.toml:

[rag]
enabled = true
# model = "BAAI/bge-small-en-v1.5"   # default, only supported model currently
# cache_dir = "~/.cache/shire-rag"    # optional, for model file storage

当启用时， shire build 在提取后嵌入所有符号。第一个构建会自动下载模型（约33MB）。后续构建是增量的——只有更改的包才会被重新嵌入。

RAG是非致命的：如果模型加载失败或嵌入失败，shire会退回到仅使用FTS的搜索并发出警告。如果 rag 功能未在中编译 [rag] config部分被默认忽略。

自定义包发现

对于那些包不是由标准清单文件定义的代码库——使用单模块monorepos，使用 ownership.yml +构建文件或任何非标准约定——您可以定义自定义发现规则：

# Discover Go apps: directories containing both main.go and ownership.yml
[[discovery.custom]]
name = "go-apps"
kind = "go"
requires = ["main.go", "ownership.yml"]
paths = ["services/", "cmd/"]
exclude = ["testdata", "examples"]
max_depth = 3
name_prefix = "go:"

# Discover proto packages: directories containing *.proto and buf.yaml
[[discovery.custom]]
name = "proto-packages"
kind = "proto"
requires = ["*.proto", "buf.yaml"]
paths = ["proto/", "services/"]
max_depth = 4

自定义发现与基于清单的发现并行运行。清单解析器已找到的目录将被跳过。匹配目录的子目录也会被跳过，以防止嵌套匹配。

演出

在真实世界的monorepos上进行基准测试（完全重建，无增量缓存）：

所有查询都返回 2ms以下，大多数在0.3ms以下。看 演出 详细的基准测试和复制说明。

建筑

src/
├── main.rs          # CLI (clap): build, serve, watch, rebuild subcommands
├── config.rs        # shire.toml parsing
├── db/
│   ├── mod.rs       # SQLite schema, open/create
│   └── queries.rs   # FTS search, dependency graph BFS, listing
├── index/
│   ├── mod.rs       # Walk + incremental index orchestrator
│   ├── custom_discovery.rs # Config-driven custom package discovery
│   ├── manifest.rs  # ManifestParser trait
│   ├── hash.rs      # SHA-256 content hashing for incremental builds
│   ├── npm.rs       # package.json parser (workspace: protocol)
│   ├── go.rs        # go.mod parser
│   ├── go_work.rs   # go.work parser (workspace use directives)
│   ├── cargo.rs     # Cargo.toml parser (workspace dep resolution)
│   ├── python.rs    # pyproject.toml parser
│   ├── maven.rs     # pom.xml parser (parent POM inheritance)
│   ├── gradle.rs    # build.gradle / build.gradle.kts parser
│   ├── gradle_settings.rs # settings.gradle parser (project inclusion)
│   ├── perl.rs      # cpanfile parser (requires, on 'test')
│   └── ruby.rs      # Gemfile parser (gem, group blocks)
├── symbols/
│   ├── mod.rs       # Symbol types, kind-agnostic extraction orchestrator
│   ├── walker.rs    # Source file discovery (extension filtering, excludes)
│   ├── typescript.rs # TS/JS extractor (tree-sitter)
│   ├── go.rs        # Go extractor (tree-sitter)
│   ├── rust_lang.rs # Rust extractor (tree-sitter)
│   ├── python.rs    # Python extractor (tree-sitter)
│   ├── proto.rs     # Protobuf extractor (tree-sitter)
│   ├── java.rs      # Java extractor (tree-sitter)
│   ├── kotlin.rs    # Kotlin extractor (tree-sitter)
│   ├── perl.rs      # Perl extractor (regex-based)
│   └── ruby.rs      # Ruby extractor (tree-sitter)
├── rag/             # Optional RAG vector search (behind `rag` feature flag)
│   ├── mod.rs       # Feature-gated module root
│   ├── embedder.rs  # fastembed wrapper, symbol text formatting, batch embedding
│   └── storage.rs   # sqlite-vec extension, vec0 table, vector CRUD, KNN search
├── mcp/
│   ├── mod.rs       # MCP server setup (rmcp, stdio transport)
│   ├── tools.rs     # 14 tool handlers (+ hybrid search when RAG enabled)
│   └── prompts.rs   # 2 prompt templates (explore, reference_audit)
└── watch/
    ├── mod.rs       # Daemon event loop (UDS listener, debounce, rebuild)
    ├── daemon.rs    # Process management (start/stop/is_running via PID)
    └── protocol.rs  # Hook input parsing, Bash read-only denylist

许可证

阿帕奇-2.0