sqry - Semantic Code Search

sqry

sqry はローカルで動作するセマンティックコード検索ツールです。ソースコードを AST に基づくシンボルと関係のグラフに解析するため、テキスト検索では確実に答えられないコードに関する問い合わせが可能になります。

すべてはお使いのマシン上で実行されます。インデックス作成とクエリはネットワーク呼び出しを行わず、sqry はテレメトリーを送信しません。

ウェブサイト: https://sqry.dev

現在の機能

• 37 個の言語プラグインがあり、28 個が完全な関係サポート、9 個がシンボル抽出とインポートに対応しています。ビルドコスト別では、29 個がデフォルトの高速パス上にあり、json はコンパイルされますがウォールクロックが大きいためデフォルトでは除外され、7 個の特殊プラグインは Cargo フィーチャーの背後にあります。sqry://meta/manifest MCP リソースは、インストールされているバイナリについてこれらの数を報告します。
• シンボルの種類、言語、可視性、名前、戻り値の型、参照、関係に対する構造的クエリ。
• 呼び出し元、呼び出し先、インポート、エクスポート、呼び出しパス、循環、未使用シンボル、重複、影響範囲、セマンティック diff、フォーカスされたサブグラフのグラフ分析。
• サポートされているグラフパスに対する、エッジに基づく returns:<TypeName> と解決を考慮した resolved_via:<kind> 述語。詳しくは 呼び出し解決述語 を参照してください。
• 言語をまたぐ FFI エッジ。C、C++、C#、Elixir、Haskell、Kotlin、Lua、PHP、R、Ruby、Rust の各プラグインは、extern "C"、DllImport / P/Invoke、JNI、Ruby FFI の attach_function、R の .Call / Rcpp といった仕組みから FfiCall エッジを出力します。sqry graph cross-language または cross_language_edges MCP ツールでクエリできます。
• sqry shape-match による構造的形状マッチング。これは識別子とは無関係に、本体の構造が類似した関数を検出します。
• 宣言的なルールレイヤー。sqry rules run は、同梱のルール ID とパック、または独自の TOML ルールパックをグラフに対して実行します。rules_run MCP ツールは同じエンジンを公開します。
• context.Context を破棄する呼び出しサイトに対する Go のコンテキスト伝播分析(sqry context-propagation)。
• Rust のマクロ境界分析: sqry cache expand はマクロ展開キャッシュを構築し、--expand-cache はマクロが生成したシンボルを検索可能なノードとして実体化し、--cfg は #[cfg] でゲートされたシンボルをアクティブまたは非アクティブとしてマークします。両方のインデックスパスオプションは実行を伴わず、インデックスマニフェストに記録され、永続化するすべての再ビルドは、--no-macro-options(または reset_macro_options)がクリアするまでその記録を再利用します。対象は sqry index --force、sqry update、sqry watch、sqry query の自動インデックスと --auto-rebuild、デーモン(sqry daemon rebuild、そのファイルウォッチャーによる再ビルド、およびその MCP rebuild_index)、LSP(sqry.index、その自動インデックスと自己修復)、スタンドアロン MCP(rebuild_index とその自動インデックス)です。既存のインデックスに対しては --force が必要です。相対的な --expand-cache は作業ディレクトリを基準に解決され、MCP の expand_cache フィールドはその path 引数が指すディレクトリ(そのディレクトリ、またはファイルの親ディレクトリ)を基準に解決され、daemon/rebuild は再ビルドするワークスペースを基準に解決されます。ディレクトリは存在している必要があり、正規パスが有効な UTF-8 でないものは拒否されます。マニフェストがそれを JSON テキストとして記録するためです。--cfg は空または空白のみの値、および先頭または末尾に空白がある値を拒否します。
• Mermaid、Graphviz DOT、または D2 としての可視化とエクスポート(sqry visualize、sqry export)。
• 多数のクエリにわたってセッションキャッシュをウォームに保つ対話型シェル(sqry shell)とバッチランナー(sqry batch)。
• sqry update と sqry watch によるインデックス更新。いずれも完全な再ビルドで、インデックスが記録したプラグイン選択とマクロオプションを再利用します(変更されたファイルのみを再インデックスするコマンドはありません)。
• .sqry-workspace レジストリと VS Code の .code-workspace sqry.workspace ブロックによるワークスペース対応のインデックス作成。
• エディタ、MCP、および繰り返し実行されるエージェントのワークフロー向けの、sqryd によるデーモンベースの共有グラフ読み込み。
• sqry overview(およびエージェント向けの対応する generate_overview MCP ツール)によるワンショットのリポジトリ概観: 主要なハブ、パス/パッケージのサブシステム、複雑さのホットスポット、潜在的な問題、すぐに実行できるフォローアップクエリを 1 つのレポートにまとめます。
• AI アシスタント向けの MCP 統合。スタンドアロンの sqry-mcp は現在 39 個のツールを公開しており、デーモンホスト型 MCP は 17 ツールのサブセットを公開しています。権威あるカタログとして tools/list、sqry-mcp --list-tools、または sqry://meta/manifest を使用してください。
• エディタワークフロー向けの LSP および VS Code 拡張機能のサポート。

sqry を使うべき場面

構造的な答えが必要なときは sqry を使用してください。

sqry index .
sqry overview            # orient in an unfamiliar repo, then run the queries it suggests
sqry query "kind:function AND visibility:public AND lang:rust"
sqry query "returns:Result"
sqry graph direct-callers authenticate
sqry graph trace-path main handle_request
sqry visualize "callers:authenticate" --format mermaid

単純なテキスト検索には ripgrep、構文書き換えパターンには ast-grep、ポリシー適用には言語リンター、完全なエディターセマンティクスには IDE のランゲージサーバーを使用してください。sqry はローカルのセマンティックコード検索に焦点を当て続けます。

インストール

Linux および macOS

curl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | bash -s -- --component all

シェルインストーラーはリリースアセットをダウンロードし、デフォルトで SHA256 チェックサムを検証して、以下をインストールします。

• sqry
• sqry-mcp
• sqry-lsp
• sqryd

サポートされているリリースプラットフォームは、Linux x86_64/arm64（glibc および musl ビルド）、macOS x86_64/arm64、Windows x86_64 です。

便利なオプション:

curl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | \
  bash -s -- --component all --version vX.Y.Z --verify-signatures

--verify-signatures には gh または Cosign が必要です。これは release-distribute.yml からの現在の release-artifacts.attestation.json GitHub アーティファクトアテステーションを検証します。古いリリースでは、引き続きレガシーのアセットごとの Cosign バンドルにフォールバックできます。SHA256 検証はデフォルトの整合性チェックのままです。

Windows

Invoke-WebRequest https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1 -OutFile install.ps1
Get-Content .\install.ps1
.\install.ps1 -Component all -VerifySignatures

PowerShell インストーラーは Windows x86_64 リリース ZIP をダウンロードし、デフォルトでチェックサムを検証して、sqry.exe、sqry-mcp.exe、sqry-lsp.exe、sqryd.exe をユーザーインストールディレクトリにインストールします。

再現性が重要な場合は、固定されたリリースを使用してください。

.\install.ps1 -Component all -Version vX.Y.Z -VerifySignatures

Homebrew

Homebrew は、現在公開リリースマニフェストに支えられているパッケージマネージャー向けの窓口です。

brew tap verivus-oss/sqry
brew install sqry

この formula は、Linux x86_64/arm64 および macOS x86_64/arm64 向けに sqry、sqry-mcp、sqry-lsp、sqryd をインストールします。

Scoop、Winget、AUR、Nix、Snap は、それぞれのリリース制御の仕組みが完成して検証されるまで、公開リリースアセットとして宣伝されていません。

ソースからのビルド

git clone https://github.com/verivus-oss/sqry.git
cd sqry
cargo install --path sqry-cli
cargo install --path sqry-mcp
cargo install --path sqry-lsp
cargo install --path sqry-daemon

要件:

• Edition 2024 を備えた Rust 1.94+。
• リポジトリは rust-toolchain.toml でツールチェーン 1.94.1 を固定しています。
• ワークスペース全体のビルドでは、同梱の tree-sitter グラマーと言語プラグインをコンパイルするため、相当なディスク容量を必要とする場合があります。

エージェントのセットアップ

インストール済みのバイナリをコーディングエージェントに接続するには 2 つのステップがあります。この順序で実行してください。MCP はエージェントにツールを提供し、スキルはいつそれらを使うべきかをエージェントに伝えます。

1. MCP サーバーを接続する

sqry mcp setup --tool claude --scope global
sqry mcp setup --tool codex --scope global
sqry mcp setup --tool gemini --scope global
sqry mcp status

プロジェクトごとのエントリを特に希望しない限り、--scope global を渡してください。スコープの動作と、変更が書き込まれる前にプレビューする方法については MCP とエディター を参照してください。

エージェントが接続されると、sqry-mcp は自身の参照資料を MCP リソースとして提供します（sqry://docs/tool-guide、sqry://docs/query-syntax、sqry://docs/patterns、sqry://docs/architecture、sqry://docs/capability-map、sqry://meta/manifest）。これらはバイナリ内に同梱され、バイナリとともにバージョン管理されるため、エージェントが読むツールリファレンスが、実際に呼び出せるツールから乖離することはありません。

2. エージェントスキルを追加する

スキルは、エージェントがテキスト検索にフォールバックするのではなく、タスクの途中で sqry を使うように教えるものです。このルーティングの判断こそが、どれだけツールのドキュメントを揃えても補えない部分であり、それが上記の MCP リソースとは別の成果物になっている理由です。

これらは verivus-oss/sqry-skills にあり、8 つを公開しています。中核となるルーティングスキルである sqry-semantic-search に加え、Claude Code、Codex、Gemini CLI、Grok、OpenCode、Antigravity、Mistral Vibe 用にそれぞれ 1 つずつです。

そのリポジトリのルートは Claude 互換のプラグインでもあり、スキル、sqry-mcp、sqry-lsp をまとめて登録します。エージェントが読み込むプラグインディレクトリにクローンするか、エージェントをチェックアウト先に向けてください。

git clone --depth 1 https://github.com/verivus-oss/sqry-skills ~/.grok/plugins/sqry
# or, without installing:  claude --plugin-dir /path/to/sqry-skills

プラグインの配線なしでスキルだけを使う場合:

npx skills add https://github.com/verivus-oss/sqry-skills

エージェントごとのパスと doctor.sh ヘルスチェックは、そのリポジトリの README に記載されています。現在、シェルインストーラーも Homebrew の formula もスキルを配置しないため、このステップは手動です。

最初のインデックス

# Build the default fast-path index.
sqry index .

# Check status without rebuilding.
sqry index --status --json .

# Force a rebuild after upgrading across graph-format or semantics changes.
sqry index --force .

インデックスの成果物は .sqry/ の下に置かれます。意図的に共有する場合を除き、.sqry/ およびレガシーの .sqry-index 成果物をプロジェクトの無視ルールに追加してください。

インデックス検証

sqry search main . --validate fail --auto-rebuild
sqry index --status --metrics-format prometheus .

--validate は off、warn（デフォルト）、fail のいずれかを取ります。fail では、古いインデックスはそこから計算された結果を返す代わりに終了コード 2 で中断され、これにより CI ゲートとして使用できるようになります。--auto-rebuild は、fail の場合に古いインデックスを一度再構築してからそれを使って実行します。warn と off では何も行いません。コマンド自身の引数（パターン、あらゆる形式のクエリ、--var、ファジーアルゴリズム）はその再構築の前にチェックされるため、コマンドが拒否した引数はインデックスをそのままの状態に保ちます。唯一のしきい値は --threshold-orphaned-files RATIO（0.0 から 1.0、デフォルト 0.20）です。インデックス化されたファイルのうち、ディスク上にもはや存在しないものの割合がこれを超えると検証が作動します。したがって --threshold-orphaned-files 0.5 はファイルの半数が失われることを許容し、0 は一切許容しません。

制限に注意してください。これらはグローバルフラグですが、検証は sqry search および sqry query サブコマンドに対してのみ実行されます（sqry <pattern> 短縮形や、デーモンが保持するリビジョンを読むリビジョンクエリでは実行されません）。インデックスがすでに存在するときにこれらを sqry index に渡しても、検証パスはトリガーされません。

--metrics-format prometheus は、インデックスステータスをスクレイピングするための OpenMetrics 互換テキストを出力します。

プラグインの選択

sqry は、インデックスを構築したプラグインセットを記録するため、後続のグラフ読み込みコマンドが同じセマンティクスを再利用できます。

sqry index .                         # default fast path
sqry index --include-high-cost .     # all compiled non-default plugins
sqry index --exclude-high-cost .     # force the fast path
sqry index --enable-plugin json .    # opt into one plugin
sqry index --disable-plugin json .   # opt out of one plugin

レジストリには、高速なプラグイン、ウォールクロックの長いプラグイン、およびオプションの特殊プラグインがあります。json はウォールクロックの長いプラグインです。オプションの特殊プラグインには、対応する Cargo フィーチャーまたは specialty-plugins を指定してコンパイルした場合の apex、abap、servicenow-xanadu-js、servicenow-xml、terraform、puppet、pulumi が含まれます。

アーティファクトのクリーンアップ、プラグインの階層、高コストな動作については、インデックス作成 を参照してください。

クエリの例

# Symbol and attribute predicates.
sqry query "kind:function AND name:parse_*"
sqry query "kind:struct AND lang:rust"
sqry query "kind:function AND returns:Result"

# Relation predicates.
sqry query "callers:authenticate"
sqry query "callees:handle_request"
sqry query "imports:serde"

# Planner-backed query.
sqry plan-query "kind:function callers:main"

# Resolution-aware call filtering where populated by graph metadata.
sqry plan-query "kind:function callers:my_read resolved_via:binding_plane"

returns:<TypeName> はグラフの TypeOf{Return} エッジを使用します。

呼び出し解決の述語

resolved_via:<kind> は、エッジを生成したバインディングの種類によって呼び出しエッジをフィルタリングします。これは、リゾルバーがどれだけ確信しているかとは別の問いです。duck_typed エッジは確信度の低い direct エッジではなく、その呼び出しが構文参照ではなく Python のダックタイピングによって束縛されたという記録です。メカニズムを知ることで、コンパイラがチェックできたはずの呼び出しと、実行時にのみ解決される呼び出しを区別できます。

パーサーは 8 つの値を受け付けます。

値	バインディングのメカニズム
direct	言語プラグインによって解決された構文上の呼び出し
type_match	型によって互換性のあるシグネチャにマッチした間接呼び出し
binding_plane	バインディングプレーンにおける指定イニシャライザーの証拠
virtual_dispatch	JVM の仮想メソッドまたは抽象メソッドのディスパッチ
interface_dispatch	Go のインターフェースディスパッチ
duck_typed	Python のダックタイピングディスパッチ
structural	TypeScript の構造的ディスパッチ
promiscuous_elided	ファンアウトの上限を超えたため、リゾルバーが N 個のターゲットではなく診断用の自己エッジを記録した

# Callers of my_read that only bind through the binding plane,
# not through a plain syntactic call.
sqry plan-query "kind:function callers:my_read resolved_via:binding_plane"

framework フィルタリングは型付き MCP パラメータとして公開されています。プランナーは framework:<id> も解析しますが、フレームワークルートのメタデータは抽出器が実行された場所でのみ設定されます。マッチしなかった場合は、フレームワークが未使用である証拠ではなく、メタデータが存在しないものとして扱ってください。

グラフ述語、スナップショットの表現、影響分析、セマンティック diff、可視化については、高度な分析 を参照してください。

ワークスペース

1 つの論理的なプロジェクトが複数のリポジトリやフォルダにまたがる場合は、ワークスペースを使用してください。

sqry workspace init .
sqry workspace scan .
sqry workspace status . --json
sqry workspace clean .

ワークスペースの構成は、.sqry-workspace レジストリ、または sqry.workspace ブロックを含む VS Code の .code-workspace ファイルから取得できます。詳しくは ワークスペース を参照してください。

デーモン

sqryd は、繰り返し行われる CLI、LSP、MCP、およびエディターのワークフローのためにグラフの状態をウォームに保ちます。

sqry daemon start
sqry daemon load .
sqry daemon status --json
sqry daemon rebuild . --force
sqry daemon logs --follow

詳しくは デーモンモード を参照してください。

MCP とエディター

MCP クライアントを次のように設定します。

sqry mcp setup --tool claude --scope global
sqry mcp setup --tool codex --scope global
sqry mcp setup --tool gemini --scope global

--scope のデフォルトは auto で、作業ディレクトリがリポジトリ内にある場合はプロジェクト単位の Claude Code エントリに解決され、そうでない場合はエラーになります。マシン全体のエントリには --scope global を、固定したいリポジトリ内からは --scope project を渡します。Codex と Gemini CLI はグローバル設定のみをサポートしているため、この 2 つでは 2 つのスコープは同じように動作し、ワークスペースの解決はツールを起動したディレクトリに従います。sqry mcp setup --dry-run は変更を書き込まずに出力し、sqry mcp status は現在設定されている内容を報告します。

単体の sqry-mcp はローカルツールの全機能を提供します。sqry-mcp --daemon は sqryd に接続し、デーモンがホストするサブセットを公開します。workspace_status.source_root_id は不透明な表示・関連付け用トークンであり、パスではありません。MCP Guide と sqry-mcp/README.md のコンポーネントドキュメントを参照してください。

MCP 検索ツールは、文字列述語と構造化 JSON パラメータを分離して扱います。

{
  "name": "semantic_search",
  "arguments": {
    "query": "kind:function items:true",
    "filters": {
      "language": ["rust"],
      "visibility": "public"
    }
  }
}

定義のみのクエリ述語には、query で items:true または is_definition:true を使用します。list_symbols を呼び出すときは、構造化された items_only パラメータを使用します。

{
  "name": "list_symbols",
  "arguments": {
    "kind": "function",
    "language": "rust",
    "items_only": true
  }
}

グラフが V16 定義シグナルスナップショット形式より前に構築された場合、定義のみのクエリ述語と list_symbols.items_only は、古いマーカーデータを信頼するのではなく、reindexRequired / 再インデックスが必要である旨の警告を返します。

VS Code 拡張機能については、sqry-vscode/README.md と sqry-vscode/USER_GUIDE.md を参照してください。

ユーザーガイド

• クイックスタート
• ユーザーガイドの索引
• インデックス作成
• ワークスペース
• デーモンモード
• MCP ガイド
• クエリ言語
• リポジトリの概要
• ルール
• コンテキストの伝播
• Doctor
• リビジョン対応ワークスペース
• 高度な分析
• 構造的形状マッチング
• 可視化

セキュリティとサプライチェーン

• リリース成果物には GitHub OIDC のキーレス証明が付与され、release-artifacts.attestation.json アセットとして公開され、gh attestation verify または Cosign で検証できます。SHA256SUMS.txt も同梱され、両方のインストーラーはデフォルトでチェックサムを検証します。
• 各リリースは、リリースマニフェストと、ビルドが通過した段階を記録するリリース台帳アセットも公開します。
• 依存関係は CI で cargo-vet (Mozilla、Google、Bytecode Alliance、ISRG の監査セットをインポート)、cargo-deny、cargo-audit によってゲートされています。Clippy は -D warnings として実行されます。
• クエリプランナーのテキストパーサーは cargo-fuzz で毎晩ファズテストされます。cargo-mutants は PR ごとに変更行に対して、master ではカナリアクレートのベースラインに対して実行されます。現在はブロックせずに報告するだけです。
• SBOM (CycloneDX と SPDX) および OpenVEX ドキュメントは、別のワークフローによって生成されます。

インストールするリリースのアセットリストに記載されていない限り、成果物が存在すると想定しないでください。脆弱性を報告するには、SECURITY.md を参照してください。

プロジェクトの範囲

sqry は MIT ライセンスのオープンソースプロジェクトであり、1 つの製品目標に焦点を当てています。それはローカルなセマンティックコード検索です。ホスト型の検索プラットフォーム、リンター、IDE の代替、または汎用メトリクスプラットフォームではありません。