Sensegrep

sensegrep

面向 AI 编码 Agent 的语义 grep

sensegrep 能从语义层面理解你的代码。它不匹配文本模式，而是结合 AI 嵌入和 tree-sitter AST 解析，按含义查找代码——因此，你可以搜索“身份验证逻辑”，并找到实际的身份验证函数，即使代码中从未出现“身份验证”这个词。

AI Agent 不应该阅读更多代码，而应该阅读正确的代码。sensegrep 结合语义搜索、精确匹配和感知 AST 结构的检索，提供更精简、更相关的上下文。

对于 Agent 路由，发现内容时默认使用 search：适用于有关行为、概念、结构或某项功能的实现位置和方式的问题。只有在要查找已知的精确字符串或正则表达式、穷举审查所有匹配项，或在语义发现后进行验证或细化时，才使用 literal。意图不明确时，请从 search 开始。

MP4 备用文件：assets/time-to-value.mp4

观看完整产品演示（25 秒）：assets/time-to-value-full.mp4

为什么选择 sensegrep？

传统搜索工具（grep、ripgrep、ast-grep）匹配文本模式。sensegrep 匹配概念：

功能	grep/ripgrep	ast-grep	sensegrep
精确文本匹配	是	是	是（通过 --pattern）
感知 AST 结构	否	是	是（tree-sitter）
语义搜索	否	否	是（AI 嵌入）
符号元数据筛选器	否	部分支持	是（30+ 个筛选器）
重复项检测	否	否	是（逻辑重复项）
Tree-shaking 输出	否	否	是（折叠无关代码）
面向 AI Agent 的 MCP 服务	否	否	是

快速入门

可选的远程评估：Jev 设置、感知证据的重排、分组标签和重复项判定。默认关闭，可与本地 Ollama 嵌入配合使用。

Claude Code 插件（推荐）

将 sensegrep 添加到 Claude Code 的最快方式——无需任何配置：

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

此操作会自动设置 MCP 服务，并指导 Claude 何时以及如何使用 sensegrep 代替 grep。无需手动编辑 JSON。

市场设置（首次安装时必需）：

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

添加一次市场后，也可以使用明确指定市场的形式：

claude plugin install sensegrep@sensegrep

在全新机器上，如果先运行 claude plugin install sensegrep@sensegrep，再运行 claude plugin marketplace add Stahldavid/sensegrep，安装将失败，因为 Claude Code 尚不了解 sensegrep 市场。

CLI

npm i -g @sensegrep/cli

# Smoke-test local CLI/core/config without calling embeddings
sensegrep selftest --root .

# Default local embeddings use Ollama when no API key/provider is configured
ollama pull qwen3-embedding:0.6b
sensegrep index --root .

# Search by meaning
sensegrep search "error handling and retry logic" --type function --exported --exclude "*.md"

# Known exact text, deterministic and exhaustive: no embedding call
sensegrep literal "X-Goog-Message-Number" --include "src/**"

# Compact evidence cards, followed by deterministic expansion
sensegrep search "authentication flow" --purpose understand --json
sensegrep show <result-id> --before 10 --after 20

# Exhaustive within the ripgrep-visible filesystem, independent of the index
sensegrep literal "TODO:" --filesystem --max-output-bytes 50000 --json

# Complete changed-file review coverage in bounded batches
sensegrep audit "security regressions" --base origin/main --require-coverage --continue-uncovered --batch-tokens 4000 --max-total-tokens 8000 --max-output-bytes 32000 --max-batches 8

# Build a reading map for a broad theme
sensegrep survey "authentication login token" --language typescript --limit 4

# Break a broad topic into coherent subthemes
sensegrep cluster "checkout payment order cart" --limit 4

# Find duplicates
sensegrep detect-duplicates --threshold 0.85
sensegrep detect-duplicates --threshold 0.85 --timeout 30s --resume-cursor 0 --json

面向 Agent 的 JSON 默认采用压缩格式和 minimal 模式。只有在需要额外负载时，才选择 --json-detail content、--diagnostic、--json-detail full 或 --pretty。 Schema v2 在不同传输方式中使用统一的卡片字段：id、file、lines、symbol、 kind、rank 和 relevance。最小输出保留足以支持检索的内容、精简的索引状态 和结构化警告；只有在受到约束时才会显示预算。物理输出预算适用于最终序列化的 JSON， 并尽可能保留部分证据卡片。重复项 JSON 不包含源代码，除非指定了 --show-code。 Survey 和 cluster JSON 默认采用可执行摘要模式，并提供代表性 ID。

Cursor 插件

从 Cursor marketplace 或通过 CLI 安装：

cursor plugin install sensegrep

包含 MCP 服务、一个始终启用且优先使用 sensegrep 而非 grep 的规则，以及一项包含完整筛选器参考的技能。 Cursor 插件状态：等待 marketplace 审核。

Cursor 一键式 MCP 安装链接：

备用深层链接（如有需要，可复制/粘贴）：

cursor://anysphere.cursor-deeplink/mcp/install?name=sensegrep&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzZW5zZWdyZXAvbWNwQGxhdGVzdCJdfQ%3D%3D

Codex 插件

从公开 marketplace 安装——无需手动配置：

codex plugin marketplace add Stahldavid/sensegrep
codex plugin install sensegrep

手动设置 ~/.codex/config.toml，请参阅 Codex 配方。

MCP 服务（用于 Codex 或手动设置）

npx -y @sensegrep/mcp

添加到 MCP 配置中：

{
  "servers": {
    "sensegrep": {
      "command": "npx",
      "args": ["-y", "@sensegrep/mcp"]
    }
  }
}

或者先通过 npm 全局安装：

npm install -g @sensegrep/mcp

{
  "servers": {
    "sensegrep": {
      "command": "sensegrep-mcp"
    }
  }
}

MCP 服务提供规范的 sensegrep_search、sensegrep_show、sensegrep_literal、sensegrep_context、sensegrep_survey、sensegrep_cluster、sensegrep_graph、sensegrep_index 和 sensegrep_detect_duplicates 工具。在受支持的情况下，sensegrep.search 等旧版点分名称仍可作为兼容性别名使用。

Agent 技能 — CLI（无需 MCP 服务）

对于终端优先的 Agent 或 CI，无需 MCP 服务。安装 CLI 和 sensegrep-cli Agent 技能，该技能会教 Agent 直接运行 sensegrep 命令：

npm i -g @sensegrep/cli
npx skills add Stahldavid/sensegrep --skill sensegrep-cli -g

关于何时使用 MCP 工具而非 CLI 技能，请参阅 docs/agent-skills.md。

VS Code 扩展

在 VS Code marketplace 中搜索 "Sensegrep"，或从扩展页面安装。

功能：语义搜索侧边栏、重复检测、代码镜头、语义折叠，以及多根目录自动索引/监视模式。

配方

可复制粘贴的设置说明和实用工作流：

• Claude Code 配方
• Cursor 配方
• Codex 配方
• 使用 GitHub Actions 的 CI
• 通用 CI 配方

完整索引：docs/recipes/README.md

工作原理

Source Code
    │
    ▼
┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│  Tree-Sitter │───▶│   Chunker    │───▶│  Embeddings  │
│  AST Parser  │    │  (symbols +  │    │ (Ollama,     │
│              │    │   metadata)  │    │ Gemini, etc.)│
└─────────────┘    └──────────────┘    └──────────────┘
                                              │
                                              ▼
                                       ┌──────────────┐
                          Query ──────▶│   LanceDB    │
                                       │ Vector Search│
                                       └──────┬───────┘
                                              │
                                              ▼
                                       ┌──────────────┐
                                       │ Tree-Shaker  │──▶ Results
                                       │ (collapse    │
                                       │  irrelevant) │
                                       └──────────────┘

1. 解析：Tree-sitter 提取带有完整元数据的 AST 节点（符号类型、导出、复杂度、文档、装饰器）
2. 分块：将代码拆分为与符号边界对齐的语义块
3. 嵌入：使用 Ollama、Gemini、兼容 OpenAI 的嵌入 API 或 Amazon Bedrock 为每个代码块生成嵌入。
4. 存储：将嵌入和元数据存储在 LanceDB 中，以实现快速向量搜索
5. 搜索：融合向量和词法候选结果，进行结构化筛选，并可选择重新排序
6. 树摇：折叠结果，仅显示相关代码，隐藏无关符号

支持的语言

• TypeScript / JavaScript（包含 TSX/JSX）
• Python（dataclass、协议、装饰器、异步生成器、TypedDict 等）
• Java（类、接口、记录、注解、方法，以及经树摇处理的结果）
• Vue（支持 <script> / <script setup> 语义分析的单文件组件）
• 更多语言即将推出：C#、HTML（请参阅功能分支）

搜索筛选器

sensegrep 支持 30 多种可与语义搜索组合使用的结构化筛选器：

# Find exported async functions with high complexity
sensegrep search "data processing" --type function --exported --async --min-complexity 5

# Find Python dataclasses
sensegrep search "user model" --type class --variant dataclass --language python

# Find undocumented complex code (refactoring candidates)
sensegrep search "business logic" --min-complexity 10 --has-docs false

# Filter by decorator
sensegrep search "route handler" --type function --decorator route

# Keep docs and markdown out of results
sensegrep search "authentication flow" --include "src/**/*.ts" --exclude "*.md"

# Build a reading map for onboarding a domain
sensegrep survey "authentication login token" --language typescript --limit 4

# Split a broad backend topic into subthemes
sensegrep cluster "price list commission ncm uf packaging" --language java --include "backend-api/**/*.java"

# Build an agent context pack with a hard estimated-token budget
sensegrep context "authentication request flow" --max-tokens 8000

# Review only code changed against a Git base
sensegrep audit "security and regression risks" --base origin/main

# Navigate the local symbol graph
sensegrep references loadUser
sensegrep impact loadUser --depth 3
sensegrep trace handleRequest loadUser

图节点使用规范的文件/范围标识。对于名称相同且存在歧义的调用目标，不会展开推测性影响边，而是直接省略。

索引操作

# Inspect local work before any embedding request
sensegrep index --dry-run --no-watch

# Interrupted full builds resume their fingerprint-matched staging table
sensegrep index --full --no-watch

# Compare safe concurrency candidates without changing saved config
sensegrep benchmark --concurrency 1,2,4 --samples 16

# Keep independent indexes for different models/settings
sensegrep index --profile fast --no-watch
sensegrep profiles

# Keep LanceDB, graph, tools, and watcher warm behind a local HTTP endpoint
sensegrep daemon start
sensegrep daemon endpoint
sensegrep daemon call --tool search --arguments '{"query":"request routing","limit":5}'

# Agent-native planning and task-level quality evaluation
sensegrep investigate "where does payment gate room access?" --dry-run
sensegrep eval sensegrep-eval.yaml

诊断命令严格只读。不兼容的索引会报告 migrationRequired: true；使用 sensegrep index migrate --no-watch 重建。完整构建会暂存并验证新的 Lance 表，然后切换元数据；同时保留先前的版本，以供并发读取和回滚诊断使用。

对于内容相同的分块，即使相邻分块或元数据发生变化，已更改文件也会复用向量。完整索引会检查点化暂存表，并在重启后跳过已持久化的 ID。对于大型索引，LanceDB ANN 和标量索引会在分块数达到 10,000 时自动创建；设置 SENSEGREP_ANN_MIN_CHUNKS=0 可禁用此功能，也可以指定其他阈值。

语言插件

无需修改核心代码即可扩展语言支持。插件会导出一个 LanguageSupport 对象（default、language 或 languages[]），其中包含其扩展名以及可选的 chunk(content, filePath) 实现。将相对于项目的 ESM 模块或软件包名称添加到 sensegrep.config.json 中的 languagePlugins，或者将 SENSEGREP_LANGUAGE_PLUGINS 设置为以逗号分隔的列表。

{
  "languagePlugins": ["./tools/sensegrep-ruby.mjs"]
}

嵌入配置

sensegrep 默认支持本地 Ollama，也支持 Gemini、兼容 OpenAI 的 API 和 Amazon Bedrock。如果未配置 API 密钥或提供方，默认使用 http://127.0.0.1:11434 上的 Ollama，以及 qwen3-embedding:0.6b（1024 维，32K 上下文）。在建立索引前运行 sensegrep selftest --root .，即可确认所选提供方、模型、维度以及凭据和端点配置说明，而不会调用嵌入服务。

# Default local Ollama embeddings (no API key)
ollama pull qwen3-embedding:0.6b
sensegrep search "auth flow"

# Recommended: Gemini embeddings (best quality)
export SENSEGREP_PROVIDER=gemini
export GEMINI_API_KEY="your_ai_studio_key"
sensegrep search "auth flow" --provider gemini --embed-model gemini-embedding-001

# OpenAI-compatible provider
export SENSEGREP_PROVIDER=openai
export SENSEGREP_OPENAI_API_KEY="your_api_key"
export SENSEGREP_OPENAI_BASE_URL="https://api.fireworks.ai/inference/v1"
sensegrep search "auth flow" --provider openai --embed-model fireworks/qwen3-embedding-8b

# OpenRouter + Qwen3 Embedding 8B with smaller Matryoshka vectors
export SENSEGREP_PROVIDER=openai
export SENSEGREP_OPENAI_API_KEY="your_openrouter_key"
export SENSEGREP_OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export SENSEGREP_EMBED_MODEL="qwen/qwen3-embedding-8b"
export SENSEGREP_EMBED_DIM=1024
export SENSEGREP_OPENAI_BATCH_SIZE=96

# Amazon Bedrock + Cohere Embed v4
export AWS_REGION="us-east-1"
export SENSEGREP_BEDROCK_API_KEY="your_bedrock_api_key"
sensegrep search "auth flow" --provider bedrock --embed-model cohere.embed-v4:0 --embed-dim 1536

如果本地兼容 OpenAI 的嵌入服务实现了 /v1/embeddings，也可以使用；请设置 SENSEGREP_PROVIDER=openai，将 SENSEGREP_OPENAI_BASE_URL 设为该服务的 /v1 基础 URL，并将 SENSEGREP_EMBED_DIM 设为返回向量的确切维度。对于原生 Ollama，请使用 SENSEGREP_PROVIDER=ollama；如果不使用默认地址，则设置 SENSEGREP_OLLAMA_BASE_URL，并将 SENSEGREP_EMBED_DIM 设为 Ollama 模型的确切维度。

通过 ~/.config/sensegrep/config.json 设置全局默认值：

{
  "provider": "ollama",
  "embedModel": "qwen3-embedding:0.6b",
  "embedDim": 1024
}

常见环境变量：

• SENSEGREP_PROVIDER（ollama、gemini、openai、bedrock）
• SENSEGREP_EMBED_MODEL
• SENSEGREP_EMBED_DIM
• SENSEGREP_OLLAMA_BASE_URL（Ollama，默认 http://127.0.0.1:11434）
• GEMINI_API_KEY / GOOGLE_API_KEY（Gemini）
• SENSEGREP_OPENAI_API_KEY / FIREWORKS_API_KEY / OPENAI_API_KEY（兼容 OpenAI）
• SENSEGREP_OPENAI_BASE_URL（兼容 OpenAI，默认 https://api.fireworks.ai/inference/v1）
• SENSEGREP_OPENAI_BATCH_SIZE（兼容 OpenAI 的请求批次大小）
• SENSEGREP_OPENAI_CONCURRENCY / SENSEGREP_EMBED_CONCURRENCY（提供方请求并发数）
• SENSEGREP_INDEX_EMBED_CONCURRENCY（并发执行的索引嵌入批次）
• SENSEGREP_QUERY_CACHE（默认值为 true；在受控基准测试或敏感环境中设置为 false）
• SENSEGREP_QUERY_CACHE_TTL_MS / SENSEGREP_QUERY_CACHE_MAX_ENTRIES（持久化查询向量缓存的限制）
• SENSEGREP_ADAPTIVE_HYBRID_DELAY_MS / SENSEGREP_ADAPTIVE_HYBRID_MIN_SCORE（自适应混合搜索调优）
• SENSEGREP_ANN_MIN_CHUNKS（自动 ANN 阈值；0 表示禁用）
• SENSEGREP_PROFILE（用于并列比较的具名索引配置）
• SENSEGREP_LANGUAGE_PLUGINS（以逗号分隔的 ESM 语言插件）
• SENSEGREP_OPENROUTER_REFERER / SENSEGREP_OPENROUTER_TITLE（可选的 OpenRouter 归属标头）
• SENSEGREP_BEDROCK_API_KEY（Amazon Bedrock bearer API 密钥；使用 AWS SDK 凭据链时省略）
• SENSEGREP_BEDROCK_REGION / AWS_REGION / AWS_DEFAULT_REGION（Amazon Bedrock）
• SENSEGREP_ROOT（MCP 根目录）
• SENSEGREP_WATCH（MCP 监视器开关）

完整且官方的运行时变量列表，请参阅 docs/mcp-setup.md。

OpenRouter Qwen 嵌入默认每次只发送一个提供方请求。在 高延迟端点上进行的基准测试通常表明，增加并发请求会降低吞吐量； 覆盖默认值前，请使用 sensegrep benchmark --concurrency 1,2,4 --samples 256 --json。

基准测试仅针对兼容 OpenAI 的适配器调整并发数，且只有当样本跨越多个 HTTP 批次时才会调整。原生 Ollama、Gemini 和 Bedrock 会报告顺序执行的基线，recommendedConcurrency: null，且不提供环境变量建议。这不会调整索引工作线程或 Ollama 服务端槽位。 索引计划会分别报告内部的 estimatedBatches 和 estimatedRequests； 对于 Ollama，HTTP 请求使用 httpBatchSize（默认值为 16），包括每个索引批次内部的拆分。请求估算不包括重试；试运行不会扣除将被复用的向量。其他提供方仍使用近似请求估算。

搜索证据和上下文

搜索会保留多样的文件锚点，同时纳入互补符号并有限扩展本地辅助函数。context 默认值为 12,000 个估算输出令牌；紧凑包可使用 4,000，更广泛的调查可使用 8,000。显式文件数和令牌数限制仍会得到遵守。证据不足警告仅供参考，并不能证明代码不存在。有关行为、局限性和可复现的对比脚本，请参阅搜索质量和预算。

索引兼容性

每个索引都会记录嵌入提供商、模型、维度、距离度量，以及非机密的端点／配置指纹。如果更改提供商、模型、基础 URL、维度、本地服务的池化行为或任务前缀策略，请使用 sensegrep index --root . --full --no-watch 重建索引。维度相同并不意味着嵌入可以互换；两个 768 维模型仍会生成不同的向量空间。

未来可能会添加更多嵌入提供商和 API 集成。

软件包

软件包	描述	npm
@sensegrep/core	搜索引擎库
@sensegrep/cli	命令行界面
@sensegrep/mcp	面向 AI Agent 的 MCP 服务
sensegrep	VS Code 扩展	Marketplace
sensegrep-plugin	Claude Code 插件	claude plugin marketplace add Stahldavid/sensegrep && claude plugin install sensegrep
sensegrep-cursor	Cursor 插件	cursor plugin install sensegrep
sensegrep (Codex)	Codex 插件	codex plugin marketplace add Stahldavid/sensegrep && codex plugin install sensegrep

案例研究

来自公开代码库、可复现的定性示例：

• 案例研究
• 用例
• 并行 Agent 工作流

路线图

• ROADMAP.md
• 与 ripgrep / ast-grep 的基准测试方法计划在第 2 个月制定。

贡献

运行时和持久化设计请参阅架构指南，开发环境设置和贡献指南请参阅 CONTRIBUTING.md。VS Code 扩展会将提供商 API 密钥存储在 VS Code SecretStorage 中；工作区设置仅包含非机密配置。

社区

• 行为准则
• 安全策略
• 支持

许可证

Apache-2.0

可配置的分块预算

有关 8K 运行时窗口、可配置的符号／目标／最大预算、本地分词器计数、受令牌数限制的 HTTP 批次，以及安全的索引迁移，请参阅令牌感知分块和本地 Ollama。context --max-tokens 独立控制输出。