sqry

# sqry

[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.verivus-oss%2Fsqry/versions/latest)
[![crates.io](https://img.shields.io/crates/v/sqry-cli.svg)](https://crates.io/crates/sqry-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

sqry is a local semantic code search tool. It parses source code into AST-backed symbol and relationship graphs so you can ask code questions that text search cannot answer reliably.

Everything runs on your machine. Indexing and querying make no network calls, and sqry sends no telemetry.

Website: https://sqry.dev

## Current Capabilities

- 37 language plugins, 28 with full relation support and 9 with symbol extraction plus imports. By build cost, 29 are on the default fast path, `json` is compiled but excluded by default as high-wall-clock, and 7 specialty plugins sit behind Cargo features. The `sqry://meta/manifest` MCP resource reports these counts for the binary you have installed.
- Structural queries over symbol kind, language, visibility, names, return types, references, and relations.
- Graph analysis for callers, callees, imports, exports, call paths, cycles, unused symbols, duplicates, impact, semantic diff, and focused subgraphs.
- Edge-backed `returns:<TypeName>` and resolution-aware `resolved_via:<kind>` predicates for supported graph paths. See [Call resolution predicates](#call-resolution-predicates).
- Cross-language FFI edges. The C, C++, C#, Elixir, Haskell, Kotlin, Lua, PHP, R, Ruby, and Rust plugins emit `FfiCall` edges from mechanisms such as `extern "C"`, `DllImport` / P/Invoke, JNI, Ruby FFI `attach_function`, and R `.Call` / `Rcpp`. Query them with `sqry graph cross-language` or the `cross_language_edges` MCP tool.
- Structural shape matching with `sqry shape-match`, which finds functions with similar body structure independently of their identifiers.
- A declarative rule layer. `sqry rules run` executes shipped rule IDs and packs, or your own TOML rule packs, against the graph; the `rules_run` MCP tool exposes the same engine.
- Go context propagation analysis (`sqry context-propagation`) for call sites that drop `context.Context`.
- Rust macro-boundary analysis: `sqry cache expand` builds a macro expansion cache, `--expand-cache` materializes macro-generated symbols as searchable nodes, and `--cfg` marks `#[cfg]`-gated symbols active or inactive. Both index-path options are execution-free and recorded in the index manifest, and every rebuild that persists reuses the record until `--no-macro-options` (or `reset_macro_options`) clears it: `sqry index --force`, `sqry update`, `sqry watch`, the `sqry query` auto-index and `--auto-rebuild`, the daemon (`sqry daemon rebuild`, its file-watcher rebuilds, and its MCP `rebuild_index`), the LSP (`sqry.index`, its auto-index and self-heal), and the standalone MCP (`rebuild_index` and its auto-index). Over an existing index they need `--force`. A relative `--expand-cache` resolves against your working directory; the MCP `expand_cache` field resolves against the directory its `path` argument names (that directory, or a file's parent directory), and `daemon/rebuild` against the workspace it rebuilds. The directory must exist, and one whose canonical path is not valid UTF-8 is refused, because the manifest records it as JSON text. `--cfg` refuses an empty or blank value, and one with leading or trailing whitespace.
- Visualization and export as Mermaid, Graphviz DOT, or D2 (`sqry visualize`, `sqry export`).
- An interactive shell (`sqry shell`) and batch runner (`sqry batch`) that keep the session cache warm across many queries.
- Index refresh with `sqry update` and `sqry watch`, each a full rebuild that reuses the plugin selection and macro options the index records (no command re-indexes only the changed files).
- Workspace-aware indexing through `.sqry-workspace` registries and VS Code `.code-workspace` `sqry.workspace` blocks. <!-- claim:multi-root-supported test:resolve_logical_workspace_short_circuits_in_documented_order -->
- Daemon-backed shared graph loading through `sqryd` for editor, MCP, and repeated-agent workflows.
- One-shot repository orientation with `sqry overview` (and the matching `generate_overview` MCP tool for agents): a single report of the load-bearing hubs, path/package subsystems, complexity hotspots, potential issues, and ready-to-run follow-up queries.
- MCP integration for AI assistants. Standalone `sqry-mcp` currently exposes 39 tools; daemon-hosted MCP exposes a 17-tool subset. Use `tools/list`, `sqry-mcp --list-tools`, or `sqry://meta/manifest` as the authoritative catalog.
- LSP and VS Code extension support for editor workflows.

## When To Use sqry

Use sqry when you need structural answers:

```bash
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
```

Use ripgrep for simple text search, ast-grep for syntax rewrite patterns, language linters for policy enforcement, and an IDE language server for full editor semantics. sqry stays focused on local semantic code search.

## Install

### Linux And macOS

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

The shell installer downloads release assets, verifies SHA256 checksums by default, and installs:

- `sqry`
- `sqry-mcp`
- `sqry-lsp`
- `sqryd`

Supported release platforms are Linux `x86_64`/`arm64` (glibc and musl builds), macOS `x86_64`/`arm64`, and Windows `x86_64`.

Useful options:

```bash
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` requires `gh` or Cosign. It verifies the current `release-artifacts.attestation.json` GitHub artifact attestation from `release-distribute.yml`; older releases can still fall back to legacy per-asset Cosign bundles. SHA256 verification remains the default integrity check.

### Windows

```powershell
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
```

The PowerShell installer downloads the Windows `x86_64` release ZIP, verifies checksums by default, and installs `sqry.exe`, `sqry-mcp.exe`, `sqry-lsp.exe`, and `sqryd.exe` into the user install directory.

Use a pinned release when reproducibility matters:

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

### Homebrew

Homebrew is the package-manager surface currently backed by the public release manifest.

```bash
brew tap verivus-oss/sqry
brew install sqry
```

The formula installs `sqry`, `sqry-mcp`, `sqry-lsp`, and `sqryd` for Linux `x86_64`/`arm64` and macOS `x86_64`/`arm64`.

Scoop, Winget, AUR, Nix, and Snap are not advertised as public release assets until their release-control surfaces are complete and validated.

### Build From Source

```bash
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
```

Requirements:

- Rust `1.94+` with Edition 2024.
- The repository pins toolchain `1.94.1` in `rust-toolchain.toml`.
- A full workspace build compiles the bundled tree-sitter grammars and language plugins and can require substantial disk space.

## Agent Setup

Two steps connect the installed binaries to a coding agent. Run them in this order: MCP gives the agent the tools, the skills tell it when to reach for them.

### 1. Wire The MCP Server

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

Pass `--scope global` unless you specifically want a per-project entry. See [MCP And Editors](#mcp-and-editors) for what the scopes do and how to preview a change before it is written.

Once an agent is connected, `sqry-mcp` serves its own reference material as MCP resources (`sqry://docs/tool-guide`, `sqry://docs/query-syntax`, `sqry://docs/patterns`, `sqry://docs/architecture`, `sqry://docs/capability-map`, `sqry://meta/manifest`). Those ship inside the binary and version with it, so the tool reference an agent reads cannot drift from the tools it can actually call.

### 2. Add The Agent Skills

The skills are what teach an agent to reach for sqry mid-task instead of falling back to text search. That routing judgement is the part no amount of tool documentation supplies, which is why it is a separate artifact from the MCP resources above.

They live in [verivus-oss/sqry-skills](https://github.com/verivus-oss/sqry-skills), which publishes eight: `sqry-semantic-search`, the core routing skill, plus one each for Claude Code, Codex, Gemini CLI, Grok, OpenCode, Antigravity, and Mistral Vibe.

That repository root is also a Claude-compatible plugin, registering the skills, `sqry-mcp`, and `sqry-lsp` together. Clone it into the plugin directory your agent reads, or point the agent at a checkout:

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

For the skills on their own, without the plugin wiring:

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

Per-agent paths and a `doctor.sh` health check are documented in that repository's README. Neither the shell installer nor the Homebrew formula stages the skills today, so this step is manual.

## First Index

```bash
# Build the default fast-path in