sqry

sqry 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.

Website: https://sqry.dev

Example

# Index a codebase (creates .sqry/graph/snapshot.sqry)
sqry index

# Find all public async functions
sqry query "kind:function AND async:true AND visibility:public"

# Who calls this function?
sqry query "callers:authenticate"

# Trace a path between two symbols
sqry graph trace-path main handle_request

# Find circular dependencies
sqry cycles

# Ask in plain English (translates to sqry syntax, then searches)
sqry ask "find all error handling functions"

Why sqry?

If you just need text search, use ripgrep - it's faster and simpler for that job.

sqry 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.

What sqry is good at

• Relation queries: callers:X, callees:X, imports:X, returns:Result - exact answers from the call graph
• Graph analysis: trace paths between symbols, find cycles, detect unused code
• Structured queries: combine predicates with boolean logic (kind:function AND lang:rust AND async:true)
• Cross-language detection: FFI linking (Rust<>C/C++), HTTP route matching (JS/TS<>Python/Java/Go)
• AI assistant integration: MCP server with 34 tools, LSP server for editors

When NOT to use sqry

• Simple text search: Use ripgrep. It's faster for grep-style patterns.
• Pattern matching on syntax: Use ast-grep. It's better for "find this syntax pattern and replace it."
• Linting or rule enforcement: Use language-specific linters (clippy, eslint, semgrep).
• Full IDE features: Use your editor's built-in language server.
• Hosted code search: Use Sourcegraph if you need a web UI and team features.

sqry is focused on one thing: local semantic code search via AST analysis.

What's New In 7.2.0

• Graph analysis commands now share one traversal engine across CLI, LSP, and MCP, which makes trace-path, show_dependencies, dependency_impact, subgraph, and graph export behave more consistently.
• Path traversal results now preserve deterministic discovery order, enforce node/edge limits atomically, and enumerate leaf paths when no explicit target is supplied.
• MCP gained expand_cache_status, a Rust macro-expansion cache introspection tool, and its tool/reference docs now reflect the live tool catalog instead of stale hard-coded counts.
• LSP workspace path resolution was hardened to reject directory-traversal escapes outside the configured workspace root.

Install

Windows (recommended)

irm https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1 | iex

This installs sqry.exe, sqry-mcp.exe, and sqry-lsp.exe into %LOCALAPPDATA%\Programs\sqry\bin and adds that directory to the user PATH. By default the installer resolves the latest GitHub release; use .\install.ps1 -Version vX.Y.Z to pin a specific release tag. Review-first/signed variant:

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

Pinned-release example:

.\install.ps1 -Version v4.8.16 -VerifySignatures

Manual fallback:

• download sqry-windows-x86_64.zip
• extract sqry.exe, sqry-mcp.exe, sqry-lsp.exe
• place them in a directory on PATH

macOS and Linux (recommended)

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

Installs sqry, sqry-mcp, and sqry-lsp into ~/.local/bin (override with --install-dir). Downloads individual binaries directly from GitHub releases with per-asset SHA256 checksum verification against SHA256SUMS.txt. Add --verify-signatures to enforce Cosign bundle verification (requires cosign). Current published macOS binaries target Apple Silicon (arm64) only.

Options: --component sqry|sqry-mcp|sqry-lsp|all, --version vX.Y.Z, --install-dir DIR, --repo OWNER/REPO, --no-checksum.

Build from source

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

sqry --version

Requirements: Rust 1.94+ (Edition 2024). About 20 GB disk for a full build (37 tree-sitter grammars are compiled from source).

Package managers

Release packaging configs are generated from signed release checksums for:

• Homebrew (tap formula)
• Scoop
• Winget
• AUR
• Nix
• Snap

Look for these files in release assets (homebrew-sqry.rb, scoop-sqry.json, winget-*.yaml, aur-PKGBUILD, nix-*.nix, snap-snapcraft.yaml). Primary install methods should provide sqry, sqry-mcp, and sqry-lsp; raw binaries and .bundle files are advanced/manual verification assets.

Commands

Indexing Controls

# Default fast-path index
sqry index

# Include all high-cost plugins
sqry index --include-high-cost

# Force the fast path even if SQRY_INCLUDE_HIGH_COST=1 is set
sqry index --exclude-high-cost

# Include one high-cost plugin explicitly
sqry index --enable-plugin json

# Exclude a plugin explicitly
sqry index --disable-plugin json

sqry persists the active plugin set in the unified graph manifest, so later query, watch, diff, and graph-loader paths reuse the indexed semantics instead of silently reinterpreting the workspace under current defaults.

Currently, the default fast path excludes these high-cost plugins:

• json
• servicenow-xml

The same plugin-selection flags also apply to sqry update and sqry watch. --enable-language and --disable-language remain accepted compatibility aliases for --enable-plugin and --disable-plugin.

Macro Expansion (Rust)

# Index with macro boundary analysis
sqry index --enable-macro-expansion

# Include cfg-gated items
sqry index --enable-macro-expansion --cfg 'feature="serde"'

# Search with macro filters
sqry query "kind:function" --cfg-filter 'feature="serde"' --include-generated
sqry query "kind:function" --macro-boundaries

JVM Classpath Analysis

# Index with automatic wrapper/tool resolution (Gradle: gradlew -> gradle, Maven: mvnw -> mvn)
sqry index --classpath

# Shallow resolution (direct dependencies only)
sqry index --classpath --classpath-depth shallow

# Use a specific classpath file
sqry index --classpath-file classpath.txt

# Restrict discovery to a specific JVM build system in a larger monorepo
sqry index --classpath --build-system gradle

• Missing JVM tooling with no cache is treated as an error, not a successful empty external graph.
• Nested JVM build roots are discovered from the repo root, and workspace import edges are scoped to the nearest containing module/root.

Search and Query

# On-the-fly search (no index needed, slower)
sqry search "kind:function" src/

# Indexed query (fast, requires sqry index first)
sqry query "kind:class OR kind:struct"
sqry query "kind:function AND visibility:public AND callers:helper"

# Fuzzy search (typo-tolerant)
sqry --fuzzy "patern" .

# Hierarchical search (results grouped by file, useful for RAG)
sqry hier "kind:function visibility:public"

Relations

sqry query "callers:process_data"       # Who calls this?
sqry query "callees:main"               # What does this call?
sqry query "imports:utils"              # Who imports this?
sqry query "returns:Result"             # Functions returning Result

sqry graph direct-callers parse_config  # Direct callers
sqry graph direct-callees main          # Direct callees
sqry graph call-hierarchy parse_config --depth 3

Graph Analysis

sqry graph trace-path main handle_error    # Execution path between symbols
sqry graph dependency-tree module           # Transitive dependencies
sqry graph cross-language                   # Cross-language relationships
sqry cycles                                 # Circular dependencies
sqry duplicates                             # Duplicate code
sqry unused                                 # Dead code detection
sqry impact parse_config                    # Dependency impact analysis
sqry graph complexity                       # Complexity metrics
sqry diff HEAD~1 HEAD                       # Semantic diff between git refs

For very large C++ codebases, pathological single-file graph builds are now bounded so one oversized translation unit does not pin the entire index run indefinitely.

Natural Language

sqry ask "What functions handle error recovery?"
sqry ask "Find all public structs" --auto-execute

Export and Visualization

sqry export --format dot          # Graphviz DOT
sqry export --format mermaid      # Mermaid
sqry export --format d2           # D2 diagrams
sqry export --format json         # JSON

sqry visualize "callers:main" --format mermaid

See docs/user-guide/visualization.md for examples.

Output Formats

sqry --preview main                     # Text with context (default 3 lines)
sqry --json --preview 5 "pattern"       # JSON with context
sqry --csv --headers --columns name,file,line pattern > results.csv

CSV/TSV output escapes per RFC 4180 and prefixes formula-leading characters unless --raw-csv is set.

Cache Management

sqry cache stats                    # View cache statistics
sqry cache prune --days 30          # Remove old entries
sqry cache prune --size 1GB         # Cap cache size
sqry cache clear --confirm          # Clear all cached ASTs
sqry cache expand                   # Generate/refresh macro expansion cache (Rust)
sqry cache expand --dry-run         # Preview without writing

Other

sqry shell                          # Interactive REPL
sqry batch commands.txt             # Batch processing
sqry watch --build                  # Watch mode (auto-update index)
sqry repair --dry-run               # Check for index corruption
sqry --list-languages               # List supported languages
sqry completions bash               # Shell completions

Choosing the Right Command

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.

Language Support

sqry 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.

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

Symbol extraction + imports (9): JSON, Oracle PL/SQL, Pulumi, Puppet, Salesforce Apex, SAP ABAP, ServiceNow Xanadu, ServiceNow XML, Terraform

Each language plugin lives in its own crate (sqry-lang-*) and implements the GraphBuilder trait. See CONTRIBUTING.md for how to add a new language.

MCP Server (AI Assistant Integration)

sqry includes an MCP server with 34 JSON-RPC tools for AI assistants (Claude, Codex, Gemini, Cursor, Windsurf):

# Start MCP server (stdio transport)
sqry-mcp

# Auto-configure for your AI assistant
sqry mcp setup

# Or add to ~/.claude.json manually:
# "mcpServers": { "sqry": { "command": "sqry-mcp", "args": [] } }

The 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.

See sqry-mcp/README.md for setup details and tool documentation. For sensitive repositories, use sqry-mcp-redaction to sanitize MCP responses before sending data to external LLMs.

LSP Server (Editor Integration)

sqry lsp --stdio        # Start LSP server (stdio mode)

Supports hover, definition, references, call hierarchy, document/workspace symbols, code actions, and 27 custom sqry methods. Works with VS Code, Neovim, Helix, and any LSP 3.17 client. Socket mode available for shared instances.

See sqry-lsp/ for configuration details.

VSCode Extension (Preview)

The VS Code extension provides in-editor semantic queries, a "Semantic Results" panel, and CodeLens caller count annotations. Multi-root workspaces are supported with per-folder index status and tree data. Source is in sqry-vscode/.

cd sqry-vscode && npm install && npm run compile
# Launch via F5 in VS Code

Configuration

sqry stores configuration in .sqry/graph/config/config.json, created automatically with sensible defaults on first use.

# View configuration
sqry config show

# Common environment variable overrides
export SQRY_CACHE_ROOT=/mnt/ssd/.sqry-cache    # Custom cache location
export SQRY_CACHE_MAX_BYTES=524288000           # 500 MB cache limit
export SQRY_CACHE_DISABLE_PERSIST=1             # Memory-only caching

See docs/PERFORMANCE_TUNING.md for all tuning options and CONFIGURATION_TUNING_GUIDE.md for the full reference.

Index Flags

sqry index . --no-incremental       # Force full rebuild
sqry index --validate=fail          # Strict validation (exit 2 on corruption)
sqry update --validate=fail --auto-rebuild  # Auto-rebuild on corruption

.sqryignore

Exclude files from indexing using gitignore syntax:

echo "node_modules/" >> .sqryignore
echo "target/" >> .sqryignore
sqry index

How It Works

sqry builds a code graph in 5 passes:

1. AST parsing - tree-sitter parses source files into syntax trees
2. Symbol extraction - nodes (functions, classes, etc.) and structural edges (defines, contains)
3. Enrichment - visibility, types, async markers
4. Intra-file edges - calls, references within each file
5. Cross-file edges - import resolution, FFI linking, HTTP route matching

The 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.

Architecture

sqry 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; locks use parking_lot.

Performance Notes

These numbers are from sqry's own codebase (~384K nodes, ~1.3M edges). Your results will vary depending on codebase size, language mix, and hardware.

• Indexed queries: ~4ms with warm cache (vs ~452ms cold)
• Cycle check: <1s (precomputed SCC lookup)
• Path finding: <1s typical (condensation DAG pruning)
• Indexing throughput: varies by language (JavaScript ~760K LOC/s, C++ ~1.1M LOC/s, Python ~500K LOC/s on the test machine)

Project Structure

sqry/
├── sqry-core/              # Core library (graph, symbols, search, plugin system)
├── sqry-cli/               # CLI binary
├── sqry-lsp/               # LSP server
├── sqry-mcp/               # MCP server (34 tools for AI assistants)
├── sqry-classpath/         # JVM classpath analysis (bytecode, Gradle/Maven/Bazel/sbt)
├── sqry-nl/                # Natural language query translation
├── sqry-plugin-registry/   # Plugin registration
├── sqry-lang-*/            # 37 language plugins
├── sqry-lang-support/      # Plugin infrastructure
├── sqry-tree-sitter-support/ # Tree-sitter helpers
├── sqry-test-support/      # Test infrastructure
└── crates/tree-sitter-*    # Vendored tree-sitter grammars

Comparison

This 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).

Contributing

We welcome contributions of all sizes - from typo fixes to new language plugins. See CONTRIBUTING.md for guidelines.

cargo build --workspace                              # Build
cargo test --workspace                               # Tests
cargo fmt --all                                      # Format
cargo clippy --all-targets --workspace -- -D warnings  # Lint

Documentation

• Quick Start Guide - Get started in 5 minutes
• Usage Examples - Real-world examples
• Feature List - Complete feature reference
• Schema Reference - Query syntax and metadata keys
• Performance Tuning - Optimization guide
• CLI Documentation - Full CLI reference
• MCP Server - AI assistant integration
• Troubleshooting - Common issues and solutions

Acknowledgments

sqry depends on excellent open-source projects:

• tree-sitter - Incremental parsing (and the many grammar maintainers)
• ripgrep - Text search engine (used as a library for fallback search)
• rayon - Data parallelism
• serde - Serialization
• clap - CLI argument parsing
• tokio - Async runtime (LSP/MCP servers)

License

MIT - see LICENSE

Developed by Verivus