Sensegrep

sensegrep

AI コーディングエージェント向けのセマンティック grep

sensegrep は、コードの意味を理解します。テキストパターンを照合する代わりに、AI 埋め込みと tree-sitter による AST 解析を使って、意味からコードを検索します。そのため、「認証ロジック」を検索すると、コード内に「認証」という単語が含まれていなくても、認証関数を見つけられます。

AI エージェントに必要なのは、より多くのコードを読むことではなく、適切なコードを読むことです。sensegrep はセマンティック検索、完全一致、AST を考慮した構造的な検索を組み合わせ、より小さく関連性の高いコンテキストを提供します。

エージェントによるルーティングでは、動作、概念、構造、または実装場所や実装方法について調べる場合、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 種類以上のフィルター）
重複検出	いいえ	いいえ	はい（論理的な重複）
ツリーシェイキング出力	いいえ	いいえ	はい（関連性のないコードを折りたたみ）
AI エージェント向け MCP サーバー	いいえ	いいえ	はい

クイックスタート

任意のリモート評価：Jev のセットアップ、根拠を考慮した再ランキング、グループラベル、重複判定。デフォルトでは無効で、ローカルの Ollama 埋め込みと併用できます。

Claude Code プラグイン（推奨）

Claude Code で sensegrep を使い始める最速の方法です。設定は不要です。

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

これにより MCP サーバーが自動的にセットアップされ、grep の代わりに sensegrep をいつ、どのように使うかを Claude に伝えます。JSON を手動で編集する必要はありません。

マーケットプレイスのセットアップ（初回インストール時に必要）：

claude plugin marketplace add Stahldavid/sensegrep
claude plugin install sensegrep

マーケットプレイスを一度追加すれば、明示的なマーケットプレイス指定を使った次の方法も利用できます。

claude plugin install sensegrep@sensegrep

新しいマシンで claude plugin marketplace add Stahldavid/sensegrep を実行する前に claude plugin install sensegrep@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

エージェント向けの JSON は、デフォルトで最小化され、minimal 形式です。追加のペイロードが必要な場合に限り、--json-detail content、 --diagnostic、--json-detail full、または --pretty を指定してください。 スキーマ v2 では、すべての転送方式で統一されたカード用語を使用します。id、file、lines、symbol、 kind、rank、relevance です。最小出力には、検索に必要な情報、簡潔なインデックス状態、構造化された警告が含まれます。予算は制限がある場合にのみ表示されます。物理出力の予算は、最終的にシリアライズされた JSON に適用され、可能な場合は部分的な根拠カードを保持します。重複 JSON には、--show-code を指定しない限りソースコードは含まれません。Survey と cluster の JSON は、代表 ID を含む、アクションにつながる要約モードをデフォルトで使用します。

Cursor プラグイン

Cursor マーケットプレイスまたは CLI からインストールします。

cursor plugin install sensegrep

MCP サーバー、grep よりも sensegrep を優先する常時有効ルール、フィルターのリファレンスをすべて含むスキルが含まれています。 Cursor プラグインのステータス：マーケットプレイスでの承認待ちです。

Cursor 用ワンクリック MCP インストールリンク：

フォールバック用ディープリンク（必要に応じてコピーして貼り付けてください）：

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

Codex プラグイン

公開マーケットプレイスからインストールできます。手動設定は不要です。

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 などの従来のドット区切り名も、対応している場合は互換性エイリアスとして引き続き利用できます。

エージェントスキル — CLI（MCP サーバー不要）

ターミナルを中心に使うエージェントや CI では、MCP サーバーは必要ありません。CLI と sensegrep-cli エージェントスキルをインストールすると、エージェントが 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 マーケットプレイスで 「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（データクラス、プロトコル、デコレーター、非同期ジェネレーター、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 をスキップします。大規模なインデックスでは、チャンク数が 10,000 に達すると LanceDB の ANN インデックスとスカラーインデックスが自動的に作成されます。無効にするには SENSEGREP_ANN_MIN_CHUNKS=0 を設定するか、別のしきい値を指定してください。

言語プラグイン

コアを変更せずに言語サポートを拡張できます。プラグインは、拡張子と任意の chunk(content, filePath) 実装を含む LanguageSupport オブジェクト（default、language、または languages[]）をエクスポートします。プロジェクト相対パスの 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 を、使用する Ollama モデルの正確な次元を SENSEGREP_EMBED_DIM に指定してください。

~/.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 のベアラー 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 埋め込みでは、デフォルトで一度に 1 件のプロバイダーリクエストを送信します。レイテンシの高いエンドポイントでのベンチマークでは、同時リクエストを増やすとスループットが低下することがよくあります。デフォルトを上書きする前に、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 エージェント向け MCP サーバー
sensegrep	VS Code 拡張機能	マーケットプレイス
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

ケーススタディ

公開リポジトリを用いた、再現可能な定性的な事例：

• ケーススタディ
• ユースケース
• 並列エージェントのワークフロー

ロードマップ

• ROADMAP.md
• ripgrep／ast-grep とのベンチマーク手法は、2 か月目に予定されています。

コントリビューション

実行時と永続化の設計についてはアーキテクチャガイドを、開発環境のセットアップとコントリビューションのガイドラインについてはCONTRIBUTING.mdを参照してください。VS Code 拡張機能はプロバイダーの API キーを VS Code の SecretStorage に保存します。ワークスペース設定に含まれるのは、秘密情報ではない設定のみです。

コミュニティ

• 行動規範
• セキュリティポリシー
• サポート

ライセンス

Apache-2.0

設定可能なチャンク予算

8K の実行時ウィンドウ、設定可能なシンボル／目標／最大予算、ローカルでのトークナイザーによるカウント、トークン数上限付き HTTP バッチ、安全なインデックス移行については、トークンを考慮したチャンク分割とローカル Ollamaを参照してください。context --max-tokens は出力を個別に制御します。