{"id":46351129,"url":"https://github.com/verivus-oss/sqry","last_synced_at":"2026-06-03T03:06:21.214Z","repository":{"id":341789308,"uuid":"1083528058","full_name":"verivus-oss/sqry","owner":"verivus-oss","description":"Semantic code search engine - by Verivus (sqry.dev)","archived":false,"fork":false,"pushed_at":"2026-05-04T04:46:33.000Z","size":104913,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-04T06:38:34.602Z","etag":null,"topics":["call-graph","cli","code-search","developer-tools","developer-tools-ai-agent","lsp","mcp","rust","semantic-search","tree-sitter","verivus"],"latest_commit_sha":null,"homepage":"https://sqry.dev","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verivus-oss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T07:53:10.000Z","updated_at":"2026-05-04T03:10:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/verivus-oss/sqry","commit_stats":null,"previous_names":["verivus-oss/sqry"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/verivus-oss/sqry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verivus-oss%2Fsqry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verivus-oss%2Fsqry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verivus-oss%2Fsqry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verivus-oss%2Fsqry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verivus-oss","download_url":"https://codeload.github.com/verivus-oss/sqry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verivus-oss%2Fsqry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32793488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["call-graph","cli","code-search","developer-tools","developer-tools-ai-agent","lsp","mcp","rust","semantic-search","tree-sitter","verivus"],"created_at":"2026-03-04T23:07:29.261Z","updated_at":"2026-06-03T03:06:21.207Z","avatar_url":"https://github.com/verivus-oss.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sqry\n\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.verivus-oss%2Fsqry/versions/latest)\n[![crates.io](https://img.shields.io/crates/v/sqry-cli.svg)](https://crates.io/crates/sqry-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nsqry is a semantic code search tool. It parses source code into an AST and builds a graph of symbols and relationships, so you can search by what code **means** rather than just what it says.\n\nWebsite: https://sqry.dev\n\n## Example\n\n```bash\n# Index a codebase (creates .sqry/graph/snapshot.sqry)\nsqry index\n\n# Find all public async functions\nsqry query \"kind:function AND async:true AND visibility:public\"\n\n# Who calls this function?\nsqry query \"callers:authenticate\"\n\n# Trace a path between two symbols\nsqry graph trace-path main handle_request\n\n# Find circular dependencies\nsqry cycles\n\n# Ask in plain English (translates to sqry syntax, then searches)\nsqry ask \"find all error handling functions\"\n```\n\n## Why sqry?\n\nIf you just need text search, use [ripgrep](https://github.com/BurntSushi/ripgrep) - it's faster and simpler for that job.\n\nsqry is useful when you need to search by code **structure**: finding all callers of a function, tracing execution paths, detecting cycles, or querying by symbol kind, visibility, or return type. These are things text search can't do reliably.\n\n### What sqry is good at\n\n- **Relation queries**: `callers:X`, `callees:X`, `imports:X`, `returns:Result` - exact answers from the call graph\n- **Graph analysis**: trace paths between symbols, find cycles, detect unused code\n- **Structured queries**: combine predicates with boolean logic (`kind:function AND lang:rust AND async:true`)\n- **Cross-language detection**: FFI linking (Rust\u003c\u003eC/C++), HTTP route matching (JS/TS\u003c\u003ePython/Java/Go)\n- **AI assistant integration**: MCP server with 36 tools, LSP server for editors\n\n### When NOT to use sqry\n\n- **Simple text search**: Use ripgrep. It's faster for grep-style patterns.\n- **Pattern matching on syntax**: Use [ast-grep](https://github.com/ast-grep/ast-grep). It's better for \"find this syntax pattern and replace it.\"\n- **Linting or rule enforcement**: Use language-specific linters (clippy, eslint, semgrep).\n- **Full IDE features**: Use your editor's built-in language server.\n- **Hosted code search**: Use Sourcegraph if you need a web UI and team features.\n\nsqry is focused on one thing: local semantic code search via AST analysis.\n\n## What's New (through 17.0.1)\n\n- **C/C++ indirect-call precision**: indexing now resolves C function-pointer (indirect) calls into the call graph and records how each edge was resolved. The v16.0.x rewrite made large C/C++ indexing dramatically faster (~10x on the Linux `drivers/net` subset). C++ types declared inside other types (nested classes/structs/enums) are now emitted as first-class nodes.\n- **Resolution-aware queries (V12 graph)**: the new `resolved_via:` predicate filters the call graph by *how* each edge was resolved (`direct`, `type_match`, `binding_plane`), so you can isolate calls recovered by the C indirect-call resolver from ordinary direct calls. A companion `framework:` predicate for web-framework route filtering is wired through the same surfaces (route extraction is rolling out). Both work in the planner text grammar (`sqry plan-query`, MCP `sqry_query`) and as filter parameters on the relation/search MCP tools (`relation_query`, `direct_callers`, `direct_callees`, `semantic_search`).\n- **Richer Go analysis**: implicit interface implementations, promoted methods, and function-signature implementations are detected. Struct fields are emitted as `Property` nodes with qualified names (also for C and Haskell).\n- **`returns:\u003cType\u003e` is edge-backed**: the `returns:` predicate resolves against real `TypeOf{Return}` edges for Rust, Java, Python, TypeScript, and Go instead of matching signature text.\n- **Typed ambiguous-symbol errors**: bare names with multiple definitions return a structured `AmbiguousSymbol` error listing every candidate (see \"Ambiguous symbol resolution\" below).\n- **Natural-language hardening**: `sqry ask` runs an on-device ONNX classifier with gated, SHA256-verified model auto-download and strict integrity checking by default; override the model location with `--model-dir`.\n- **Workspace-aware indexing is explicit**: multi-repo analysis is opt-in via a `.sqry-workspace` registry or a VS Code `.code-workspace` `sqry.workspace` block — there is no implicit \"cross-repo by default\" behavior (see \"Workspace-Aware Multi-Repo Indexing\" below).\n- **`find_duplicates` payload caps**: each duplicate group is capped to 10 members by default (`max_members_per_group` to change; `0` disables), with `total_members` / `members_truncated` fields so large repositories stay within MCP payload budgets.\n- **Distribution**: a Homebrew tap auto-publishes on every release, and Windows/macOS artifacts are validated on native-platform smoke gates before public promotion.\n\n\u003e **Upgrade note**: the C indirect-call and Go field-edge work changed in-format graph semantics. After upgrading across these releases, run `sqry index --force` once so the graph is rebuilt with the current shape.\n\n## Install\n\n### Windows (recommended)\n\n```powershell\nInvoke-WebRequest https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1 -OutFile install.ps1\nGet-Content .\\install.ps1\n.\\install.ps1 -Component all -VerifySignatures\n```\n\nThis installs `sqry.exe`, `sqry-mcp.exe`, `sqry-lsp.exe`, and `sqryd.exe` into `%LOCALAPPDATA%\\Programs\\sqry\\bin` and adds that directory to the user `PATH`. `-Component all` (the default) installs all four binaries from the Windows release ZIP.\nBy default the installer resolves the latest GitHub release; use `.\\install.ps1 -Version vX.Y.Z` to pin a specific release tag.\n\n`-VerifySignatures` uses Cosign to verify that the downloaded release zip was produced by the official `release-distribute.yml` GitHub Actions workflow for this repository. Older releases signed by `oss-distribute.yml` remain accepted for legacy compatibility. Install `cosign` and ensure it is on `PATH` before using this mode. SHA256 verification remains enabled by default and protects against download corruption; use `-NoChecksum` only for diagnostics.\n\n\u003e **Note**: Windows Defender and enterprise EDR products commonly flag the `irm ... | iex` pattern heuristically, even when the installer script is benign. If you are on a managed machine, use the download-review-run path above or install from release assets/package-manager manifests instead of piping the script directly into `iex`.\n\u003e\n\u003e If PowerShell execution policy blocks `.\\install.ps1` after download, prefer release assets or package-manager manifests rather than weakening machine-wide policy settings.\n\nConvenience shortcut for personal or non-managed machines (installs all four binaries):\n\n```powershell\n$script = irm https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1\n\u0026 ([scriptblock]::Create($script)) -Component all\n```\n\nPinned-release example:\n\n```powershell\n.\\install.ps1 -Component all -Version v17.0.1 -VerifySignatures\n```\n\nManual fallback:\n- download the Windows ZIP release asset (`sqry-\u003cversion\u003e-windows-x86_64.zip`)\n- extract all contents, including the bundled `.dll` runtime files\n- place them in a directory on `PATH`\n\n### macOS and Linux (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | bash -s -- --component all\n```\n\nInstalls `sqry`, `sqry-mcp`, `sqry-lsp`, and `sqryd` into `~/.local/bin` (override with `--install-dir`).\nDownloads individual binaries directly from GitHub releases with per-asset SHA256 checksum\nverification against `SHA256SUMS.txt`. Add `--verify-signatures` to enforce Cosign bundle\nverification (requires `cosign`). Published binaries are available for Linux `x86_64`/`arm64`,\nWindows `x86_64`, and macOS Apple Silicon/Intel.\n\nOptions: `--component sqry|sqry-mcp|sqry-lsp|sqryd|all`, `--version vX.Y.Z`, `--install-dir DIR`,\n`--repo OWNER/REPO`, `--no-checksum`.\n\n### Build from source\n\n```bash\ngit clone https://github.com/verivus-oss/sqry.git\ncd sqry\ncargo install --path sqry-cli\ncargo install --path sqry-mcp\ncargo install --path sqry-lsp\ncargo install --path sqry-daemon   # installs sqryd\n\nsqry --version\nsqryd --version\n```\n\n**Requirements**: Rust 1.90+ (Edition 2024). About 20 GB disk for a full build (37 tree-sitter grammars are compiled from source).\n\n### Package managers\n\nRelease packaging configs are generated from signed release checksums for:\n- Homebrew (published to the sqry tap and included as a release formula asset)\n- Scoop\n- Winget\n- AUR\n- Nix\n- Snap\n\nLook for these files in release assets (`homebrew-sqry.rb`, `scoop-sqry.json`, `winget-*.yaml`, `aur-PKGBUILD`, `nix-*.nix`, `snap-snapcraft.yaml`).\nPrimary install methods provide `sqry`, `sqry-mcp`, `sqry-lsp`, and `sqryd`. The shell installer and the Windows ZIP both support `sqryd` as a component. Raw binaries and `.bundle` files are advanced/manual verification assets.\n\n## Commands\n\n### Indexing Controls\n\n```bash\n# Default fast-path index\nsqry index\n\n# Include all compiled non-default plugins\nsqry index --include-high-cost\n\n# Force the fast path even if SQRY_INCLUDE_HIGH_COST=1 is set\nsqry index --exclude-high-cost\n\n# Include one non-default plugin explicitly\nsqry index --enable-plugin json\n\n# Exclude a plugin explicitly\nsqry index --disable-plugin json\n```\n\nsqry persists the active plugin set in the unified graph manifest, so later\n`query`, `watch`, `diff`, and graph-loader paths reuse the indexed semantics\ninstead of silently reinterpreting the workspace under current defaults.\n\nCurrently, the default fast path excludes these non-default plugins when they are compiled:\n- `json`\n- optional specialty plugins such as `apex`, `abap`, `servicenow-xanadu-js`, `servicenow-xml`, `terraform`, `puppet`, and `pulumi`\n\nThe specialty plugin crates stay archived in-tree and can be compiled with the `specialty-plugins` feature. For example:\n\n```bash\ncargo build -p sqry-cli --features specialty-plugins\n```\n\nThe same plugin-selection flags also apply to `sqry update` and `sqry watch`.\n`--enable-language` and `--disable-language` remain accepted compatibility\naliases for `--enable-plugin` and `--disable-plugin`.\n\n#### Plugin-tiering environment variables\n\nThe CLI flags above also have environment-variable equivalents, useful for CI\npipelines and shell sessions where you want a stable default without retyping\nflags on every `sqry` invocation. Per-invocation CLI flags always win over\nenvironment defaults.\n\n- `SQRY_INCLUDE_HIGH_COST=1` — include every compiled non-default plugin in\n  the default fast path. Equivalent to passing `--include-high-cost`.\n  Example: `SQRY_INCLUDE_HIGH_COST=1 sqry index`.\n- `SQRY_EXCLUDE_HIGH_COST=1` — force the fast path even when\n  `SQRY_INCLUDE_HIGH_COST=1` is set elsewhere. Equivalent to\n  `--exclude-high-cost` and useful for overriding a CI-wide default in a\n  single job. Example: `SQRY_EXCLUDE_HIGH_COST=1 sqry index`.\n- `SQRY_ENABLE_PLUGINS=json,servicenow-xml` — comma-separated list of plugin\n  IDs to opt back into the fast path one at a time. Equivalent to repeating\n  `--enable-plugin \u003cid\u003e`. Example:\n  `SQRY_ENABLE_PLUGINS=json sqry index`.\n- `SQRY_DISABLE_PLUGINS=json,servicenow-xml` — comma-separated list of plugin\n  IDs to drop from the active set even when they would otherwise be on.\n  Equivalent to repeating `--disable-plugin \u003cid\u003e`. Example:\n  `SQRY_DISABLE_PLUGINS=servicenow-xml sqry index`.\n\n#### Upgrade-rebuild requirement\n\nWhen sqry's in-format graph semantics change between releases (for example\nthe v10.0.x Cluster C field-edge source migration that re-sources Go\nstruct-field `TypeOf{Field}` edges from the new `NodeKind::Property`\nnodes), an existing `.sqry/graph/snapshot.sqry` keeps loading but returns\nthe legacy graph shape until rebuilt. Run `sqry index --force` once after\nupgrading across such releases. The release notes for any version that\nneeds the rebuild call this out explicitly.\n\n### Macro Expansion (Rust)\n\n```bash\n# Index with macro boundary analysis\nsqry index --enable-macro-expansion\n\n# Include cfg-gated items\nsqry index --enable-macro-expansion --cfg 'feature=\"serde\"'\n\n# Search with macro filters\nsqry search \"Handler\" --cfg-filter 'feature=\"serde\"' --include-generated\nsqry search \"process_\" --macro-boundaries\n```\n\n### JVM Classpath Analysis\n\nJVM classpath analysis is an optional build surface. Build sqry with\n`--features sqry-cli/jvm-classpath` before using the classpath flags:\n\n```bash\n# Index with automatic wrapper/tool resolution (Gradle: gradlew -\u003e gradle, Maven: mvnw -\u003e mvn)\nsqry index --classpath\n\n# Shallow resolution (direct dependencies only)\nsqry index --classpath --classpath-depth shallow\n\n# Use a specific classpath file\nsqry index --classpath-file classpath.txt\n\n# Restrict discovery to a specific JVM build system in a larger monorepo\nsqry index --classpath --build-system gradle\n```\n\n- Missing JVM tooling with no cache is treated as an error, not a successful empty external graph.\n- Nested JVM build roots are discovered from the repo root, and workspace import edges are scoped to the nearest containing module/root.\n\n### Search and Query\n\n```bash\n# On-the-fly search (no index needed, slower)\nsqry search \"kind:function\" src/\n\n# Indexed query (fast, requires sqry index first)\nsqry query \"kind:class OR kind:struct\"\nsqry query \"kind:function AND visibility:public AND callers:helper\"\n\n# Fuzzy search (typo-tolerant)\nsqry --fuzzy \"patern\" .\n\n# Hierarchical search (results grouped by file, useful for RAG)\nsqry hier \"kind:function visibility:public\"\n```\n\n### Query Language Reference\n\n`sqry query` (and `sqry plan-query`) accepts a whitespace-separated chain\nof *steps*. Each step narrows the result set; the chain must start with a\ncontext-free step (`kind:` or `name:`) and may continue with any number of\nfilter / relation / traversal steps.\n\n| Step | Example | Meaning |\n|------|---------|---------|\n| `kind:\u003cNodeKind\u003e` | `kind:function` | Restrict to nodes of the given AST kind (`function`, `method`, `class`, `struct`, `enum`, `interface`, `trait`, `module`, `variable`, `constant`, `type`, `property`, …). |\n| `name:\u003cvalue\u003e` | `name:NeedTags` | **Literal value** is an exact byte-for-byte match against the interned simple **or** qualified name of the node (case-sensitive). **Glob meta** in the value (`*`, `?`, `[`) promotes the pattern to a glob match (e.g. `name:parse_*` matches `parse_expr`, `parse_stmt`). Either way, synthetic placeholder nodes are excluded and there is **no** implicit substring or regex form. See \"`name:` contract\" below. |\n| `visibility:\u003cv\u003e` | `visibility:public` | `public` or `private`. |\n| `has:caller` / `has:callee` | `kind:function has:caller` | Existence checks over the call graph. |\n| `unused` | `kind:function unused` | Nodes with no inbound use edges. |\n| `in:\u003cglob\u003e` | `in:src/api/**/*.rs` | Filter by file-path glob. |\n| `scope:\u003ckind\u003e` | `scope:module` | Restrict to a binding-plane scope kind (`module`, `function`, `class`, `namespace`, `trait`, `impl`). |\n| `returns:\u003cTypeName\u003e` | `returns:Result` | Functions whose `TypeOf{Return}` edge targets a node whose interned name **equals** `TypeName` (exact, no glob). |\n| `resolved_via:\u003ckind\u003e` | `resolved_via:binding_plane` | Filter `Calls` edges by how they were resolved: `direct`, `type_match`, or `binding_plane` (the latter two recover indirect/function-pointer calls). |\n| `callers:\u003cvalue\u003e` / `callees:\u003cvalue\u003e` | `callees:visit_*` | Relation predicates; value can be a bare word, a glob, a quoted string, or a sub-query in parentheses. |\n| `imports:\u003cvalue\u003e` / `exports:\u003cvalue\u003e` | `imports:serde` | Module-graph relation predicates. |\n| `implements:\u003cvalue\u003e` (alias `impl:\u003cvalue\u003e`) | `kind:class implements:Visitor` | OO interface/trait conformance. |\n| `references:\u003cvalue\u003e` / `references ~= /regex/` | `references ~= /handle_.*/i` | Literal value or regex form (with `i`/`m`/`s` flags). |\n| `traverse:\u003cdir\u003e(\u003cedge\u003e,\u003cdepth\u003e)` | `kind:function traverse:forward(calls,3)` | Walk `\u003cedge\u003e` for up to `\u003cdepth\u003e` hops in `forward` / `reverse` / `both` direction. |\n\n**Name and qualified-name format.** Node names follow per-language\nconventions:\n\n- **Simple name** (`entry.name`) — typically the local identifier\n  (e.g. `NeedTags`, `parseConfig`).\n- **Qualified name** (`entry.qualified_name`) — language-canonical\n  fully-qualified form. For Go: `\u003cpackage\u003e.\u003cTypeName\u003e.\u003cFieldName\u003e`\n  (e.g. `main.SelectorSource.NeedTags`); for Rust:\n  `\u003ccrate\u003e::\u003cmodule\u003e::\u003csymbol\u003e`; for Java/Kotlin/Scala:\n  `\u003cpackage\u003e.\u003cClass\u003e.\u003cmember\u003e`. `name:\u003cX\u003e` matches both fields in\n  parallel — it returns a node whose simple name **or** qualified name\n  equals `X`.\n\n**`name:` contract (B1_ALIGN, locked).** For **literal** values (no\n`*`, `?`, or `[` in the pattern), the planner's `name:\u003cliteral\u003e` step\nand the top-level CLI shorthand `sqry --exact \u003cliteral\u003e` are\ncontract-bound to return identical sets against any fixture:\n\n```bash\nsqry query 'name:NeedTags' .   # planner exact-name lookup (literal)\nsqry --exact NeedTags .        # CLI exact-name shorthand\n```\n\nBoth:\n\n1. Look up the literal in the snapshot string interner.\n2. Walk the by-name and by-qualified-name indices for that interned id.\n3. Drop synthetic placeholder nodes (Go-plugin `\u003cfield:operand.field\u003e`\n   shadows; `\u003cident\u003e@\u003coffset\u003e` per-binding-site Variables; any future\n   nodes flagged `NodeMetadata::Synthetic`).\n4. Return the deduplicated `NodeId` set.\n\nFor values containing glob meta (`*`, `?`, `[`), the planner's `name:`\nstep promotes to a glob match (still synthetic-filtered); the\ntop-level CLI `--exact` does **not** accept glob meta and treats every\ncharacter as a literal. Use `sqry query 'name:parse_*'` for glob\nmatching against names; the exact-set-equality contract above does\nnot apply when the value contains glob meta.\n\n**Surface precedence and synthetic visibility.**\n\n| Surface | Match mode | Synthetic placeholders |\n|---------|------------|------------------------|\n| `sqry --exact \u003cliteral\u003e` (top-level) | Exact byte-for-byte match (literal only; glob meta is treated as literal characters). | Filtered out. |\n| `sqry search \u003cpat\u003e` (no flag, default) | Regex match against interned simple **and** qualified names. Invalid regex returns an error; there is no implicit substring fallback. | Not filtered — the regex surface is a literal scan over interned strings. |\n| `sqry query 'name:\u003cvalue\u003e'` (planner) | Exact byte-for-byte match for **literal** values; glob match when the value contains `*`/`?`/`[`. | Filtered out (both literal and glob paths). |\n| `sqry query 'name~/\u003cregex\u003e/'` | **Reserved** for a future regex variant (mirrors the existing `references ~= /…/` split). Not yet implemented; users wanting regex name matching today should use `sqry search \u003cregex\u003e` or `references ~= /…/` for incoming references. | n/a |\n\nOnly the structured `name:\u003cliteral\u003e` prefix and the top-level\n`--exact \u003cliteral\u003e` shorthand are bound to the exact-set-equality\ncontract — every other surface in the table has its own match mode and\nsynthetic-visibility policy as listed.\n\n### Relations\n\n```bash\nsqry query \"callers:process_data\"       # Who calls this?\nsqry query \"callees:main\"               # What does this call?\nsqry query \"imports:utils\"              # Who imports this?\nsqry query \"returns:Result\"             # Functions returning Result\n\nsqry graph direct-callers parse_config  # Direct callers\nsqry graph direct-callees main          # Direct callees\nsqry graph call-hierarchy parse_config --depth 3\n```\n\n### Graph Analysis\n\n```bash\nsqry graph trace-path main handle_error    # Execution path between symbols\nsqry graph dependency-tree module           # Transitive dependencies\nsqry graph cross-language                   # Cross-language relationships\nsqry cycles                                 # Circular dependencies\nsqry duplicates                             # Duplicate code\nsqry unused                                 # Dead code detection\nsqry impact parse_config                    # Dependency impact analysis\nsqry graph complexity                       # Complexity metrics\nsqry diff HEAD~1 HEAD                       # Semantic diff between git refs\n```\n\nFor very large C++ codebases, pathological single-file graph builds are now\nbounded so one oversized translation unit does not pin the entire index run\nindefinitely.\n\n### Ambiguous symbol resolution\n\n`sqry impact` and `sqry explain` (and the MCP `dependency_impact` tool)\nresolve a bare symbol name against the graph's by-name index. When a\nbare name matches more than one indexable node — for example `NeedTags`\nmatches both the Go `Property` node `main.SelectorSource.NeedTags` and\na local variable of the same name — the command returns a typed\n`AmbiguousSymbol` envelope under the stable error code\n`sqry::ambiguous_symbol`:\n\n```json\n{\n  \"error\": {\n    \"code\": \"sqry::ambiguous_symbol\",\n    \"message\": \"Symbol 'NeedTags' is ambiguous; specify the qualified name\",\n    \"candidates\": [\n      {\n        \"qualified_name\": \"main.SelectorSource.NeedTags\",\n        \"kind\": \"property\",\n        \"file_path\": \"main.go\",\n        \"start_line\": 12,\n        \"start_column\": 4\n      },\n      {\n        \"qualified_name\": \"main.useSelector.NeedTags\",\n        \"kind\": \"variable\",\n        \"file_path\": \"main.go\",\n        \"start_line\": 30,\n        \"start_column\": 6\n      }\n    ],\n    \"truncated\": false\n  }\n}\n```\n\nPass the qualified name (`sqry impact main.SelectorSource.NeedTags`) to\ndisambiguate. The candidate list is capped at 20 entries with\n`truncated: true` set when the underlying set is larger.\n\n**MCP redaction policy (`minimal` preset, default).** When the same\n`AmbiguousSymbol` envelope is delivered through the MCP transport\n(e.g. via `dependency_impact`), the `sqry-mcp-redaction` layer\nrewrites every per-candidate `file_path` to a workspace-relative form\nunder the default `minimal` preset, so the absolute repository path\n(home directory, machine layout, etc.) is never exposed. The redacted\nMCP envelope still surfaces `qualified_name`, `kind`, `start_line`,\nand `start_column` per candidate so AI-assistant consumers can\ndisambiguate. No source excerpt, snippet, or code-context field is\nintroduced into the envelope. The CLI envelope is unredacted (CLI\nusers have direct filesystem access already); only the MCP boundary\napplies the redaction. For stricter envelopes (filename hashing, no\nposition info), set `SQRY_REDACTION_PRESET=strict`.\n\n### Natural Language\n\n```bash\nsqry ask \"What functions handle error recovery?\"\nsqry ask \"Find all public structs\" --auto-execute\n```\n\n### Export and Visualization\n\n```bash\nsqry export --format dot          # Graphviz DOT\nsqry export --format mermaid      # Mermaid\nsqry export --format d2           # D2 diagrams\nsqry export --format json         # JSON\n\nsqry visualize \"callers:main\" --format mermaid\n```\n\nSee [docs/user-guide/visualization.md](docs/user-guide/visualization.md) for examples.\n\n### Output Formats\n\n```bash\nsqry --preview main                     # Text with context (default 3 lines)\nsqry --json --preview 5 \"pattern\"       # JSON with context\nsqry --csv --headers --columns name,file,line pattern \u003e results.csv\n```\n\nCSV/TSV output escapes per RFC 4180 and prefixes formula-leading characters unless `--raw-csv` is set.\n\n### Cache Management\n\n```bash\nsqry cache stats                    # View cache statistics\nsqry cache prune --days 30          # Remove old entries\nsqry cache prune --size 1GB         # Cap cache size\nsqry cache clear --confirm          # Clear all cached ASTs\nsqry cache expand                   # Generate/refresh macro expansion cache (Rust)\nsqry cache expand --dry-run         # Preview without writing\n```\n\n### Other\n\n```bash\nsqry shell                          # Interactive REPL\nsqry batch commands.txt             # Batch processing\nsqry watch --build                  # Watch mode (auto-update index)\nsqry repair --dry-run               # Check for index corruption\nsqry --list-languages               # List supported languages\nsqry completions bash               # Shell completions\n```\n\n## Choosing the Right Command\n\n| Task | Command | Needs Index? |\n|------|---------|:---:|\n| Quick exploration | `sqry search` | No |\n| Find callers/callees | `sqry query` | Yes |\n| Trace execution paths | `sqry graph trace-path` | Yes |\n| Compare semantic changes across refs | `sqry diff` | Yes |\n| Find cycles | `sqry cycles` | Yes |\n| Export diagrams | `sqry export` | Yes |\n\n`sqry search` parses files on demand - useful for one-off queries. `sqry query` and `sqry graph` use a prebuilt index and are much faster for repeated use.\n\n## Workspace-Aware Multi-Repo Indexing\n\nFor monorepos or saved VS Code workspaces that contain several source roots,\nsqry can treat the folders as one logical workspace while preserving per-root\nindex status.\n\n```bash\nsqry workspace init /projects --name \"My Workspace\"\nsqry workspace scan /projects --mode git-roots\nsqry workspace add /projects /projects/backend --name backend\nsqry workspace query /projects \"kind:function AND repo:backend\"\nsqry workspace stats /projects\nsqry workspace status /projects --json --no-cache\n```\n\nDiscovery modes:\n- `index-files` (default): find existing `.sqry/graph/` indexes under the root.\n- `git-roots`: find repositories by `.git/` directories.\n\nUse `sqry workspace status` to see each source root as `ok`, `building`,\n`missing`, or `error` plus the aggregate workspace verdict. VS Code and the LSP\nuse the same aggregate status surface, so a healthy multi-root workspace should\nshow indexed roots in the sqry pane instead of a false \"not indexed\" state.\n\nSee [docs/cli/workspace.md](docs/cli/workspace.md) for `.sqry-workspace` and\n`.code-workspace` configuration.\n\n## Language Support\n\nsqry supports **37 languages** through tree-sitter-based plugins. 28 of these have full relation extraction (calls, imports, exports); the remaining 9 have symbol extraction with basic import tracking.\n\n**Full relation support (28)**: C, C++, C#, CSS, Dart, Elixir, Go, Groovy, Haskell, HTML, Java, JavaScript, Kotlin, Lua, Perl, PHP, Python, R, Ruby, Rust, Scala, Shell, SQL, Svelte, Swift, TypeScript, Vue, Zig\n\n**Symbol extraction + imports (9)**: JSON, Oracle PL/SQL, Pulumi, Puppet, Salesforce Apex, SAP ABAP, ServiceNow Xanadu, ServiceNow XML, Terraform\n\nEach language plugin lives in its own crate (`sqry-lang-*`) and implements the `GraphBuilder` trait. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a new language.\n\n## MCP Server (AI Assistant Integration)\n\nsqry includes an MCP server with 36 JSON-RPC tools for AI assistants (Claude, Codex, Gemini, Cursor, Windsurf):\n\n```bash\n# Start MCP server (stdio transport)\nsqry-mcp\n\n# Auto-configure for your AI assistant\nsqry mcp setup\n\n# Or add to ~/.claude.json manually:\n# \"mcpServers\": { \"sqry\": { \"command\": \"sqry-mcp\", \"args\": [\"--no-daemon\"] } }\n```\n\nThe MCP server gives AI assistants structured access to the code graph - exact caller/callee lists, path tracing, cycle detection, etc. - rather than relying on text search or embedding similarity.\n\nSee [sqry-mcp/README.md](sqry-mcp/README.md) for setup details and tool documentation.\nFor sensitive repositories, use [sqry-mcp-redaction](sqry-mcp-redaction/README.md) to sanitize MCP responses before sending data to external LLMs.\n\n## LSP Server (Editor Integration)\n\n```bash\nsqry lsp --stdio        # Start LSP server (stdio mode)\n```\n\nSupports hover, definition, references, call hierarchy, document/workspace symbols, code actions, and 29 custom sqry methods. Works with VS Code, Neovim, Helix, and any LSP 3.17 client. Socket mode available for shared instances.\n\nSee `sqry-lsp/` for configuration details.\n\n## VSCode Extension (Preview)\n\nThe VS Code extension provides in-editor semantic queries, a \"Semantic Results\" panel, and CodeLens caller count annotations. \u003c!-- claim:multi-root-supported test:resolve_logical_workspace_short_circuits_in_documented_order --\u003e Multi-root workspaces are supported with per-folder index status and tree data, and cross-repo analysis is opt-in per workspace rather than enabled by default — add a `sqry.workspace` block inside a saved `.code-workspace` file (or commit a `.sqry-workspace` registry under any of your workspace folders) to define `sourceRoots`, `memberFolders`, `exclusions`, and `projectRootMode`. When a `.code-workspace` is open, the extension parses it and forwards a lightweight `{ folders, classification }` hint plus the workspace-file path under `initializationOptions.sqry` to `sqry lsp`. `sqry lsp` then runs its canonical `LogicalWorkspace` resolver in this fixed order (see `sqry-lsp::session::resolve_logical_workspace`): (1) a hand-crafted `LogicalWorkspace` from `initializationOptions.sqry.workspace` (the extension's lightweight hint is detected and skipped), (2) `--index-root \u003cpath\u003e/.sqry-workspace`, (3) `\u003cworkspace_folder\u003e/.sqry-workspace` walked across every workspace folder, (4) the `.code-workspace` JSON loaded via `from_code_workspace` using `initializationOptions.sqry.workspaceFile`, and (5) anonymous multi-root from the workspace folders as a last resort. The extension also contributes four settings — `sqry.indexRoot`, `sqry.projectRootMode`, `sqry.workspaceFolderExcludes`, `sqry.workspaceClassification` — that govern extension-side runtime behaviour: excludes filter every enumeration loop, and `sqry.workspaceClassification` is the user-editable surface for the inline `sqry.workspace` block. \u003c!-- claim:configurable-cross-repo test:resolve_logical_workspace_short_circuits_in_documented_order --\u003e See [docs/cli/workspace.md](docs/cli/workspace.md) for the full configuration surface, including the CLI parity flag (`--workspace \u003cPATH\u003e` / `SQRY_WORKSPACE_FILE`). Source is in `sqry-vscode/`.\n\n```bash\ncd sqry-vscode \u0026\u0026 npm install \u0026\u0026 npm run compile\n# Launch via F5 in VS Code\n```\n\n## Configuration\n\nsqry stores configuration in `.sqry/graph/config/config.json`, created automatically with sensible defaults on first use.\n\n```bash\n# View configuration\nsqry config show\n\n# Common environment variable overrides\nexport SQRY_CACHE_ROOT=/mnt/ssd/.sqry-cache    # Custom cache location\nexport SQRY_CACHE_MAX_BYTES=524288000           # 500 MB cache limit\nexport SQRY_CACHE_DISABLE_PERSIST=1             # Memory-only caching\n```\n\nSee [docs/PERFORMANCE_TUNING.md](docs/PERFORMANCE_TUNING.md) for all tuning options and [CONFIGURATION_TUNING_GUIDE.md](CONFIGURATION_TUNING_GUIDE.md) for the full reference.\n\n### Index Flags\n\n```bash\nsqry index . --no-incremental       # Force full rebuild\nsqry index --validate=fail          # Strict validation (exit 2 on corruption)\nsqry update --validate=fail --auto-rebuild  # Auto-rebuild on corruption\n```\n\n### .sqryignore\n\nExclude files from indexing using gitignore syntax:\n\n```bash\necho \"node_modules/\" \u003e\u003e .sqryignore\necho \"target/\" \u003e\u003e .sqryignore\nsqry index\n```\n\nsqry also skips common dependency, generated, build-output, editor-cache, and\nCI-runner roots by default: `.git`, `.hg`, `.svn`, `.cache`, `.next`, `.nuxt`,\n`.sqry`, `.turbo`, `.venv`, `__pycache__`, `_actions`, `_update`, `_work`,\n`build`, `dist`, `node_modules`, `target`, `vendor`, `venv`, and directories\nwhose names start with `externals.`. This keeps editor-triggered indexing from\nwalking third-party or generated trees when ignore files are absent. If a\nrepository intentionally stores first-party code in those directories, run with\n`SQRY_INCLUDE_DEFAULT_EXCLUDED_DIRS=1`.\n\n## Daemon Mode\n\n`sqryd` is a background daemon that keeps your code graph in memory across multiple CLI, LSP, and MCP invocations. Instead of parsing and indexing from scratch on every `sqry query` or AI assistant request, `sqryd` keeps the graph hot and rebuilds it incrementally when source files change.\n\n```bash\n# Start the daemon (background process, keeps graph in memory)\nsqry daemon start\nsqry daemon load /path/to/project\n\n# Check status — shows version, uptime, memory, workspaces\nsqry daemon status\n\n# Rebuild a loaded workspace in place\nsqry daemon rebuild /path/to/project --timeout 1800\n\n# Stop the daemon\nsqry daemon stop\n\n# Tail the daemon log (requires log_file set via daemon.toml or SQRY_DAEMON_LOG_FILE)\nsqry daemon logs --follow\n```\n\nExample `sqry daemon status` output:\n\n```\nsqryd v17.0.1 -- uptime 2h 14m\n\nMemory: 391 MB / 2048 MB  (peak: 418 MB)\n\nWorkspaces (2 loaded):\n  ~/projects/sqry      304 MB  (peak: 318 MB)  [Loaded]\n  ~/projects/myapp      87 MB  (peak:  91 MB)  [Loaded]\n```\n\nThe `peak` value per workspace shows the high-water mark: the maximum resident memory since that workspace was loaded or last evicted. It persists across incremental rebuilds but resets when the workspace is unloaded or evicted. The aggregate `Memory` peak shows the highest total across all workspaces. A peak close to the memory limit signals you are near the LRU eviction threshold.\n\n### Daemon-backed LSP and MCP\n\nPass `--daemon` to `sqry-mcp` or `sqry lsp` to route all tool calls through the running daemon instead of loading the graph in-process:\n\n```bash\nsqry-mcp --daemon                          # connect to default socket\nsqry-mcp --daemon --daemon-socket /tmp/sqryd.sock  # custom socket path\nsqry lsp --daemon                          # LSP backed by daemon\n```\n\nIf no daemon is running when `--daemon` is specified, `sqry-mcp` and `sqry lsp` will auto-start one. Binary resolution order: `SQRYD_PATH` env var, then a `sqryd` sibling next to the running binary, then `sqryd` on `PATH`.\n\n### Configuration\n\nThe daemon reads `~/.config/sqry/daemon.toml` at startup (XDG; on macOS: `~/Library/Application Support/sqry/daemon.toml`). Key fields:\n\n```toml\nmemory_limit_mb       = 2048   # evict LRU workspaces above this threshold (MB)\nidle_timeout_minutes  = 30     # unload workspace after N minutes of inactivity\nlog_max_size_mb       = 50     # rotate log file at this size (MB)\nlog_keep_rotations    = 5      # number of rotated log files to retain\n\n[socket]\npath      = \"\"    # Unix socket path (default: $XDG_RUNTIME_DIR/sqry/sqryd.sock,\n                  #   fallback: $TMPDIR/sqry-\u003cuid\u003e/sqryd.sock, then /tmp/sqry-\u003cuid\u003e/sqryd.sock)\npipe_name = \"\"    # Windows named pipe name (default: sqry → \\\\.\\pipe\\sqry)\n```\n\nSelected environment-variable overrides:\n- `SQRY_DAEMON_MEMORY_MB` — override `memory_limit_mb`\n- `SQRY_DAEMON_SOCKET` — override `socket.path`\n- `SQRY_DAEMON_LOG_LEVEL` — override log level (`info`, `debug`, `warn`, `error`)\n\nA daemon restart is required for any configuration change to take effect, whether editing `daemon.toml` or changing environment variables.\n\nSee [docs/cli/daemon.md](docs/cli/daemon.md) for the full CLI reference, all flags, exit codes, and tuning guidance.\n\n## How It Works\n\nsqry builds a code graph in 5 passes:\n\n1. **AST parsing** - tree-sitter parses source files into syntax trees\n2. **Symbol extraction** - nodes (functions, classes, etc.) and structural edges (defines, contains)\n3. **Enrichment** - visibility, types, async markers\n4. **Intra-file edges** - calls, references within each file\n5. **Cross-file edges** - import resolution, FFI linking, HTTP route matching\n\nThe resulting graph is persisted to `.sqry/graph/snapshot.sqry` and loaded for queries. Graph queries use precomputed analyses (SCCs, condensation DAGs, 2-hop labels) for fast cycle detection, path finding, and reachability.\n\n### Architecture\n\nsqry uses arena-based storage with CSR (Compressed Sparse Row) adjacency for cache-friendly O(1) traversal, generational indices for safety, MVCC for concurrent reads, and string interning to reduce memory. Parallelism uses [rayon](https://github.com/rayon-rs/rayon); locks use [parking_lot](https://github.com/Amanieu/parking-lot).\n\nThe **binding plane** is a first-class derived layer (Phase 4e, V9 snapshot) that computes scope/alias/shadow tables from the structural edges emitted by language plugins, then exposes witness-bearing resolution via `BindingPlane\u003c'g\u003e`. The `sqry graph resolve \u003csymbol\u003e [--explain]` command is the CLI proof point for this layer.\n\n### Performance Notes\n\nThese numbers are from sqry's own codebase (~384K nodes, ~1.3M edges). Your results will vary depending on codebase size, language mix, and hardware.\n\n- **Indexed queries**: ~4ms with warm cache (vs ~452ms cold)\n- **Cycle check**: \u003c1s (precomputed SCC lookup)\n- **Path finding**: \u003c1s typical (condensation DAG pruning)\n- **Indexing throughput**: varies by language (JavaScript ~760K LOC/s, C++ ~1.1M LOC/s, Python ~500K LOC/s on the test machine)\n\n## Project Structure\n\n```\nsqry/\n├── sqry-core/              # Core library (graph, symbols, search, plugin system)\n├── sqry-cli/               # CLI binary ('sqry')\n├── sqry-lsp/               # LSP server\n├── sqry-mcp/               # MCP server (36 tools for AI assistants)\n├── sqry-daemon/            # Daemon binary + library (sqryd)\n├── sqry-daemon-protocol/   # Wire types and framing (free functions, envelope types)\n├── sqry-daemon-client/     # Client library (shim mode, management API)\n├── sqry-db/                # Derived analysis DB + query planner (Phase 3)\n├── sqry-classpath/         # Optional JVM classpath analysis\n├── sqry-nl/                # Natural language query translation\n├── sqry-plugin-registry/   # Plugin registration\n├── sqry-mcp-redaction/     # MCP response redaction\n├── sqry-lang-*/            # Default and optional language plugins\n├── sqry-openai/            # Archived Python OpenAI integration\n├── benchmarks/             # Archived benchmark harness and evidence\n├── sqry-lang-support/      # Plugin infrastructure\n├── sqry-tree-sitter-support/ # Tree-sitter helpers\n├── sqry-test-support/      # Test infrastructure\n└── crates/tree-sitter-*    # Vendored tree-sitter grammars\n```\n\n## Comparison\n\n| Feature | sqry | ripgrep | ast-grep | Sourcegraph |\n|---------|------|---------|----------|-------------|\n| Text search | Yes (with fallback) | Yes | No | Yes |\n| AST awareness | Yes | No | Yes | Yes |\n| Relation queries | Yes (28 langs) | No | No | Yes |\n| Local/offline | Yes | Yes | Yes | No |\n| MCP server | Yes (36 tools) | No | No | No |\n| LSP server | Yes | No | No | Yes |\n| Cost | Free (MIT) | Free | Free | Paid |\n\nThis is a rough comparison; each tool has different strengths. ripgrep is faster than sqry for plain text search. ast-grep is better for syntax pattern matching. Sourcegraph offers team features sqry doesn't. sqry's strength is local graph-based queries (callers, cycles, paths).\n\n## Contributing\n\nWe welcome contributions of all sizes - from typo fixes to new language plugins. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\ncargo build --workspace                              # Build\ncargo test --workspace                               # Tests\ncargo fmt --all                                      # Format\ncargo clippy --all-targets --workspace -- -D warnings  # Lint\n```\n\n## Documentation\n\n- [Quick Start Guide](QUICKSTART.md) - Get started in 5 minutes\n- [Usage Examples](docs/USAGE_EXAMPLES.md) - Real-world examples\n- [Feature List](docs/FEATURE_LIST.md) - Complete feature reference\n- [Schema Reference](docs/SCHEMA.md) - Query syntax and metadata keys\n- [Performance Tuning](docs/PERFORMANCE_TUNING.md) - Optimization guide\n- [CLI Documentation](sqry-cli/README.md) - Full CLI reference\n- [Daemon CLI Reference](docs/cli/daemon.md) - `sqry daemon` subcommands, flags, exit codes, and memory tuning\n- [MCP Server](sqry-mcp/README.md) - AI assistant integration\n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions\n\n## Acknowledgments\n\nsqry depends on excellent open-source projects:\n\n- [tree-sitter](https://github.com/tree-sitter/tree-sitter) - Incremental parsing (and the many grammar maintainers)\n- [ripgrep](https://github.com/BurntSushi/ripgrep) - Text search engine (used as a library for fallback search)\n- [rayon](https://github.com/rayon-rs/rayon) - Data parallelism\n- [serde](https://github.com/serde-rs/serde) - Serialization\n- [clap](https://github.com/clap-rs/clap) - CLI argument parsing\n- [tokio](https://github.com/tokio-rs/tokio) - Async runtime (LSP/MCP servers)\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n\n---\n\nDeveloped by [Verivus](https://sqry.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverivus-oss%2Fsqry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverivus-oss%2Fsqry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverivus-oss%2Fsqry/lists"}