# llmgrep Manual
**v3.8.2** (shipped 2026-06-20)
llmgrep is a read-only query tool for Magellan's code map. Part of the sqlitegraph toolset alongside Magellan (indexing), Mirage (CFG analysis), and Splice (precision editing).
llmgrep only works in conjunction with Magellan — it does not build or modify databases. Magellan owns indexing and freshness.
**Toolset:**
- [Magellan](https://crates.io/crates/magellan) v4.8.0 — Code indexing and algorithm execution
- [llmgrep](https://crates.io/crates/llmgrep) v3.8.2 — This tool (query only)
- [Mirage](https://crates.io/crates/mirage-analyzer) v1.8.x — CFG analysis (Rust)
- [Splice](https://crates.io/crates/splice) — Precision code editing
- [sqlitegraph](https://crates.io/crates/sqlitegraph) v3.3.x — Graph database with 35+ algorithms
## Commands
```bash
llmgrep search --db <FILE> --query <STRING> [OPTIONS]
llmgrep ast --db <FILE> --file <PATH> [OPTIONS]
llmgrep find-ast --db <FILE> --kind <KIND> [OPTIONS]
llmgrep explore --db <FILE> --intent <STRING> [OPTIONS]
llmgrep navigate --db <FILE> --symbol <NAME> [OPTIONS]
llmgrep stats --db <FILE> [OPTIONS]
llmgrep evolve --db <FILE> [OPTIONS]
```
## search command
### Search modes
| `symbols` | Search symbol definitions (default) |
| `references` | Search references to symbols |
| `calls` | Search function calls |
| `implements` | Search type-trait implementations |
| `semantic` | Natural-language semantic search via vector similarity (requires embeddings) |
| `docs` | Search source documents (wiki, specs, messages) |
| `facts` | Search candidate knowledge triples |
| `auto` | Run symbols, references, and calls modes combined |
### Semantic search (`--mode semantic`)
Natural-language code search using HNSW vector similarity. Finds symbols by meaning rather than exact name match.
**Prerequisites:**
- Embeddings must be generated by Magellan: `magellan embed --db <db>`
- Ollama must be running with the same embedding model configured in `~/.config/magellan/config.toml`
**How it works:**
1. llmgrep reads `~/.config/magellan/config.toml` to discover the Ollama endpoint and model
2. The query is embedded via Ollama (query embedding happens at search time)
3. The persisted HNSW index is loaded from the database
4. Returns the nearest symbol vectors sorted by cosine similarity
**Important:** llmgrep only **searches** existing embeddings — it does not create them. Magellan owns embedding generation and freshness.
**Examples:**
```bash
# Find code related to command-line argument parsing
llmgrep search --db code.db --query "parse command line arguments" --mode semantic
# Semantic search with path filter
llmgrep search --db code.db --query "database connection pooling" --mode semantic --path src/db
# JSON output for programmatic use
llmgrep search --db code.db --query "error handling" --mode semantic --output json
```
**Graceful degradation:** If the database has no HNSW index, llmgrep returns a clear error suggesting `magellan embed --db <db>`. All other search modes work normally without embeddings.
### Options
**Required:**
- `--db <FILE>` — Path to Magellan SQLite `.db` database
- `--query <STRING>` — Search query string
**Search mode:**
- `--mode <MODE>` — Search mode: `symbols` (default), `references`, `calls`, `implements`, `semantic`, `docs`, `facts`, `auto`
**Filters:**
- `--path <PATH>` — Filter by file path prefix
- `--kind <KIND>` — Filter by symbol kind (Function, Struct, Method, Class, Interface, Enum, Module, Union, Namespace, TypeAlias)
- `--language <LANGUAGE>` — Filter by programming language (rust, python, javascript, typescript, c, cpp, java, go)
- `--regex` — Treat query as regex pattern
- `--fqn <PATTERN>` — Filter by FQN pattern (LIKE match, use % for wildcards)
- `--exact-fqn <FQN>` — Exact FQN match
- `--symbol-id <SYMBOL_ID>` — Search by 32-char BLAKE3 hash (unambiguous)
**Metrics filtering:**
- `--min-complexity <N>` — Minimum cyclomatic complexity
- `--max-complexity <N>` — Maximum cyclomatic complexity
- `--min-fan-in <N>` — Minimum incoming references
- `--min-fan-out <N>` — Minimum outgoing calls
**AST filtering:**
- `--ast-kind <KIND>` — Filter by AST node kind (supports shorthands and specific kinds)
- `--with-ast-context` — Include enriched AST context (depth, parent_kind, children, decision_points)
**Depth filtering:**
- `--min-depth <N>` — Minimum nesting depth (decision points only)
- `--max-depth <N>` — Maximum nesting depth (decision points only)
**Structural search:**
- `--inside <KIND>` — Find symbols within a parent of specific kind
- `--contains <KIND>` — Find symbols containing specific children
**Algorithm filtering:**
- `--from-symbol-set <FILE>` — Load pre-computed SymbolSet from JSON file
- `--condense` — Filter to symbols in strongly connected components (SCCs)
- `--paths-from <SYMBOL>` — Filter by execution paths from start symbol
- `--paths-to <SYMBOL>` — Optional end symbol for path filtering
- `--reachable-from <SYMBOL>` — Find symbols reachable from specified symbol
- `--dead-code-in <SYMBOL>` — Find dead code (unreachable symbols)
- `--in-cycle <SYMBOL>` — Find symbols in dependency cycles
- `--slice-backward-from <SYMBOL>` — Backward slice (code affecting target)
- `--slice-forward-from <SYMBOL>` — Forward slice (code affected by target)
**Sorting:**
- `--sort-by <MODE>` — Sort mode (default: `relevance`)
- `relevance` — Text relevance scoring with configurable weight factors
- `position` — Fast SQL-only sorting
- `fan-in` — Most referenced symbols first
- `fan-out` — Symbols with most calls first
- `complexity` — Highest complexity first
- `nesting-depth` — Deepest nested first
**Limits:**
- `--limit <N>` — Max results (default: 50)
- `--candidates <N>` — Candidate limit for filtering (default: 500)
- `--auto-limit <MODE>` — Auto mode behavior: `per-mode` (default) or `global`
**Output:**
- `--output <FORMAT>` — Output format: `human` (default), `json`, `pretty`
- `--tokens <N>` — Limit output to ~N tokens (chars/4 heuristic). Preserves symbol names, truncates context first. `0` or absent = no limit. JSON includes `tokens_estimated` and `truncated` metadata fields.
**Content inclusion:**
- `--with-context` — Include context lines in output
- `--with-snippet` — Include code snippets in output
- `--with-fqn` — Include fully-qualified names in output
- `--fields <FIELDS>` — JSON-only field selector (overrides `--with-*` flags)
**Context options:**
- `--context-lines <N>` — Context lines before/after (default: 3)
- `--max-context-lines <N>` — Maximum context lines (default: 20)
**Snippet options:**
- `--max-snippet-bytes <N>` — Max snippet size in bytes (default: 200)
**Docs mode filters** (`--mode docs`):
- `--tags <TAGS>` — Filter by tags (comma-separated, OR match)
- `--wikilinks <LINKS>` — Filter by wikilinks
- `--source-kind <KIND>` — Filter by source kind (wiki, code, message, etc.)
- `--since <TIMESTAMP>` — Filter by timestamp (Unix epoch)
- `--path <PATH>` — Filter by document path prefix
**Facts mode filters** (`--mode facts`):
- `--subject <SUBJECT>` — Filter by subject key (LIKE match)
- `--predicate <PRED>` — Filter by predicate (exact match)
- `--object <OBJECT>` — Filter by object key (LIKE match)
- `--status <STATUS>` — Filter by status (pending, accepted, rejected, ambiguous)
- `--subject-type <TYPE>` — Filter by subject type (Task, Agent, Event, etc.)
### Docs and Facts examples
```bash
# Find wiki documents tagged "rust"
llmgrep search --db code.db --mode docs --tags "rust"
# Find documents about a specific topic via wikilinks
llmgrep search --db code.db --mode docs --wikilinks "memory-system"
# List all candidate facts assigned to an agent
llmgrep search --db code.db --mode facts --predicate assigned_to --subject-type Task
# Find rejected facts for review
llmgrep search --db code.db --mode facts --status rejected --output json
```
## ast command (v2.1)
Query raw AST tree for a file.
```bash
llmgrep ast --db <FILE> --file <PATH> [OPTIONS]
```
**Options:**
- `--db <FILE>` — Path to Magellan SQLite database (required)
- `--file <PATH>` — Path to source file (required)
- `--position <OFFSET>` — Query AST node at specific byte offset
- `--limit <N>` — Limit number of nodes returned (default: 1000)
**Output:** Hierarchical JSON structure preserving parent_id relationships.
## find-ast command (v2.1)
Find AST nodes by kind.
```bash
llmgrep find-ast --db <FILE> --kind <KIND>
```
**Options:**
- `--db <FILE>` — Path to Magellan SQLite database (required)
- `--kind <KIND>` — AST node kind to search (required)
**Output:** JSON list of matching AST nodes.
## explore command (v3.5)
Intent-based code search using graph metadata — no embeddings needed.
```bash
llmgrep explore --db code.db --intent "database connection pooling"
llmgrep explore --db code.db --intent "error handling" --output json
llmgrep explore --db code.db --intent "cfg" --limit 5
```
### How it works
1. Tokenizes the intent string (strips stop words, expands abbreviations like `db`→`database`)
2. Searches symbols via FTS5 prefix match + LIKE fallback
3. Ranks candidates by name match score + fan-in (heavily referenced symbols rank higher)
4. Clusters results by file/module
### Options
| `--intent` | (required) | Natural language description of what you're looking for |
| `--limit` | 10 | Max symbols to return |
| `--output` | human | Output format: `human`, `json`, `pretty` |
### Abbreviation expansion
The tokenizer expands common abbreviations: `db`→`database`, `cfg`→`config`, `impl`→`implement`, `auth`→`authentication`, `fn`→`function`, `util`→`utility`, `conn`→`connection`, `err`→`error`, `svc`→`service`, `mgr`→`manager`, and more.
### Example output
```
Exploring: "database connection pooling"
Module: graph (score: 36)
File: src/graph/db_compat.rs
open_database (Function, fan-in: 12)
database_path (Function, fan-in: 5)
Module: storage (score: 15)
File: src/storage/sqlite.rs
SqliteBackend::new (Function, fan-in: 3)
2 modules, 3 symbols found
```
### When to use
- **Instead of 3-5 separate `search` commands** when you know *what* you want but not the exact symbol name
- **For codebase orientation** in an unfamiliar project
- **For agent integration** — single command replaces multi-query round trips
## navigate command (v3.6)
Stepable graph navigation using magellan's `SymbolNavigator`. Resolve a symbol, then traverse its call graph with configurable depth.
```bash
llmgrep navigate --db code.db --symbol "function_name" --callees --depth 2
llmgrep navigate --db code.db --symbol "function_name" --callers --depth 1 --output json
llmgrep navigate --db code.db --id 42 --edges
```
### How it works
1. Resolves the starting symbol by name (`--symbol`) or entity ID (`--id`)
2. Traverses the call graph in the requested direction(s) up to `--depth` hops
3. Returns depth-tagged node lists, edges, and optional resolve information
### Options
| `--symbol` | — | Symbol name to resolve (mutually exclusive with `--id`) |
| `--id` | — | Entity ID to use directly (mutually exclusive with `--symbol`) |
| `--callers` | false | Traverse callers (incoming calls) |
| `--callees` | false | Traverse callees (outgoing calls) |
| `--edges` | false | Include connected entity edges in output |
| `--depth` | 1 | Maximum traversal depth |
| `--output` | human | Output format: `human`, `json`, `pretty` |
### Examples
```bash
# Show all functions called by parse_config, 2 levels deep
llmgrep navigate --db code.db --symbol "parse_config" --callees --depth 2
# Show who calls parse_config (1 level)
llmgrep navigate --db code.db --symbol "parse_config" --callers --depth 1 --output json
# Show all edges connected to entity 42
llmgrep navigate --db code.db --id 42 --edges
```
## stats command (v3.5)
Code health summary from the database. No arguments required.
```bash
llmgrep stats
llmgrep stats --output json
```
### What it shows
- Symbol counts by kind (function, struct, trait, etc.)
- Dead code detection (symbols with zero fan-in and zero fan-out)
- Top hotspots ranked by composite score (fan-in × complexity)
- Coverage gaps (files in graph but not indexed)
## evolve command (v3.5)
Score symbols by `fan_in × cyclomatic_complexity` and optionally write high-impact candidates to `candidate_facts` table.
```bash
# Dry run — show scores without writing
llmgrep evolve --dry-run --min-score 50
# Write candidates to database
llmgrep evolve --min-score 8 --limit 20
# JSON output for scripting
llmgrep evolve --output json
```
### Options
| `--min-score` | 8 | Minimum composite score to include |
| `--limit` | 50 | Max candidates to return |
| `--dry-run` | false | Show scores without writing to database |
| `--output` | human | Output format: `human`, `json`, `pretty` |
## AST filtering
### `--ast-kind` flag
Filter search results by AST node kind for structural code queries.
**Syntax:**
```bash
**Shorthands expand to multiple node kinds:**
| `loops` | `for_expression,while_expression,loop_expression` | Loop constructs |
| `conditionals` | `if_expression,match_expression,match_arm` | Conditionals |
| `functions` | `function_item,closure_expression,async_function_item` | Functions |
| `declarations` | `struct_item,enum_item,let_declaration,const_item,static_item,type_alias_item` | Declarations |
| `unsafe` | `unsafe_block` | Unsafe blocks |
| `types` | `struct_item,enum_item,type_alias_item,union_item` | Type definitions |
| `macros` | `macro_invocation,macro_definition,macro_rule` | Macros |
| `mods` | `mod_item` | Module declarations |
| `traits` | `trait_item,trait_impl_item` | Trait items and impls |
| `impls` | `impl_item` | Impl blocks |
**Language-aware expansion:**
When used with `--language`, shorthands expand to language-specific node kinds.
| `rust` | `loops` | `for_expression,while_expression,loop_expression` |
| `python` | `loops` | `for_statement,while_statement` |
| `javascript` | `loops` | `for_statement,for_in_statement,for_of_statement,while_statement,do_statement` |
| `typescript` | `loops` | `for_statement,for_in_statement,for_of_statement,while_statement,do_statement` |
| `rust` | `functions` | `function_item,closure_expression,async_function_item` |
| `python` | `functions` | `function_definition,lambda,async_function_definition` |
| `javascript` | `functions` | `function_declaration,function_expression,arrow_function,generator_function_declaration,generator_function_expression` |
| `typescript` | `functions` | `function_declaration,function_expression,arrow_function,generator_function_declaration,generator_function_expression` |
## Depth filtering
### Decision depth
Depth is measured as **decision points only** (branching control flow structures):
- `if_expression`, `match_expression`, `for_expression`, `while_expression`, `loop_expression`
Root-level code has depth 0. Each decision point ancestor adds 1.
**Examples:**
```bash
# Find deeply nested code (complexity hotspots)
llmgrep --db code.db search --query ".*" --min-depth 5
# Find only top-level code
llmgrep --db code.db search --query "process" --max-depth 1
# Find code at specific depth range
llmgrep --db code.db search --query ".*" --min-depth 2 --max-depth 3
```
## Structural search
### `--inside` flag
Find symbols that are children of a parent with a specific AST node kind.
```bash
# Find closures within functions
llmgrep --db code.db search --query ".*" --inside function_item --ast-kind closure_expression
# Find local variables inside functions
llmgrep --db code.db search --query ".*" --inside function_item --ast-kind let_declaration
```
### `--contains` flag
Find symbols that contain children with a specific AST node kind.
```bash
# Find functions containing async calls
llmgrep --db code.db search --query ".*" --contains await_expression --ast-kind function_item
# Find functions with loops
llmgrep --db code.db search --query ".*" --contains for_expression --ast-kind function_item
```
## Magellan Algorithm Integration
### `--condense` flag (v2.1)
Filter search results to symbols in strongly connected components (SCCs). Detects dependency cycles in the call graph.
```bash
# Find all symbols participating in dependency cycles
llmgrep --db code.db search --condense --query ".*"
```
### `--paths-from` / `--paths-to` flags (v2.1)
Filter by execution paths using bounded DFS to prevent exponential explosion.
```bash
# Find symbols on paths from main
llmgrep --db code.db search --paths-from main --query ".*"
# Find symbols on paths between two symbols
llmgrep --db code.db search --paths-from parse --paths-to execute --output json
```
**Default bounds:** max-depth=100, max-paths=1000
### `--from-symbol-set` FILE
Load a pre-computed SymbolSet from a JSON file and filter search results.
**SymbolSet file format:**
```json
{
"symbol_ids": [
"abc123def456789012345678901234ab",
"0123456789abcdef0123456789abcdef"
]
}
```
### `--reachable-from` SYMBOL
Find all symbols reachable from the specified symbol.
### `--dead-code-in` SYMBOL
Find all symbols NOT reachable from the specified symbol (dead code).
### `--in-cycle` SYMBOL
Find all symbols that participate in a dependency cycle with the specified symbol.
### `--slice-backward-from` / `--slice-forward-from` SYMBOL
Backward slice: code affecting target. Forward slice: code affected by target.
## Error Codes
- **SPL-E105**: Magellan CLI not found. Install magellan to use algorithm features.
- **SPL-E106**: Ambiguous symbol name. Multiple symbols match.
- **SPL-E107**: Magellan version mismatch. Required version not available.
- **SPL-E108**: Magellan execution failed. The algorithm command exited with an error.
## Database compatibility
AST features require Magellan databases with `ast_nodes` table. If the table doesn't exist, AST filters are silently ignored (graceful degradation).
Algorithm features require Magellan 2.1.0+ CLI to be installed.
## Output formats
### Human (default)
Human-readable text with color-coded results when output is a terminal.
### JSON
Schema-aligned JSON for programmatic use.
### Pretty
Formatted JSON with indentation for readability.
## Error Codes
| **SPL-E105** | Magellan CLI not found | Install Magellan: `cargo install magellan` |
| **SPL-E106** | Ambiguous symbol name | Add `--path` or `--kind` filter to disambiguate |
| **SPL-E107** | Magellan version mismatch | Update Magellan: `cargo install magellan --force` |
| **SPL-E108** | Magellan execution failed | Check Magellan logs, verify database integrity |
| **SPL-E112** | Database file not found | Verify database path, run `magellan watch` |
| **SPL-E113** | Database table missing | Reindex database with `--scan-initial` |
| **SPL-E114** | Invalid regex pattern | Check regex syntax, escape special characters |
| **SPL-E115** | Invalid FQN format | Use valid FQN format: `crate::module::symbol` |
| **SPL-E116** | Symbol not found | Verify symbol exists, check spelling, use `--ambiguous` flag |
| **SPL-E117** | Timeout executing algorithm | Reduce search scope, use `--limit` |
## Best Practices
### For Programmatic Use
1. **Always use `--output json`** for structured output
2. **Use specific `--mode`** instead of `auto` (3x faster)
3. **Request only needed fields** with `--fields`
4. **Combine filters** to reduce result set early
### For Interactive Use
1. **Use `--output human`** for terminal display
2. **Add `--show-metrics`** when debugging performance
3. **Use `--limit`** to cap large result sets
4. **Use `--sort-by`** for discovery (complexity, fan-in)
### For Scripting
1. **Use `--output json`** with `jq` for processing
2. **Prefer exact match** over regex when possible
3. **Cache algorithm results** (expensive Magelliand subprocess calls)
## Performance Tips
| Use `--mode symbols` instead of `auto` | 3x faster |
| Remove `--with-ast-context` unless needed | 2-3x faster |
| Use `--limit` on wildcard queries | Prevents large outputs |
| Cache algorithm filter results | Avoid subprocess overhead |
## Version history
See `CHANGELOG.md` for detailed version history.
## Further Documentation
- **[README.md](README.md)** — Quick start and overview
- **[CHANGELOG.md](CHANGELOG.md)** — Version history
- **[ARCHITECTURE.md](ARCHITECTURE.md)** — Component design
- **[API_INTEGRATION.md](API_INTEGRATION.md)** — Magellan contract details