llmgrep

Version: 3.6.0

Pattern-based code search for Magellan databases. Fast, deterministic symbol search with JSON output.

Positioning: Read-only query tool for codebases indexed by Magellan. Use to find symbols, references, call relationships, source documents, and knowledge triples. Emits structured JSON for code analysis.

Purpose

llmgrep queries Magellan databases. Built for:

• Code Analysis — Structured JSON output for programmatic analysis
• Developers — Fast symbol search without IDE overhead
• Tooling — Scriptable code analysis with precise byte spans

Features

• Symbol search — Find functions, structs, traits by name or regex
• Reference lookup — Find all callers/callees of a function
• Call graph traversal — Navigate caller → callee relationships
• Graph navigation — Stepable depth-aware traversal via navigate command
• Source document search — Query wiki pages, specs, messages by tags and wikilinks
• Knowledge triple search — Query candidate facts by subject, predicate, object
• AST filtering — Filter by node kind, nesting depth, complexity
• Geometric backend — Native .geo file support with chunk retrieval
• Path normalization — Consistent path handling across platforms
• Explicit ambiguity handling — Structured results for disambiguation
• Parameterized SQL — All database queries use bound parameters (no string interpolation)

Quick Start

# Install
cargo install llmgrep

# Create Geometric database (recommended)
magellan watch --root ./src --db code.geo

# Search symbols
llmgrep --db code.geo search --query "parse"

# Find references
llmgrep --db code.geo search --query "MyType" --mode references

Installation

# Install with default features
cargo install llmgrep

# Install with geometric backend support
cargo install llmgrep --features geometric-backend

Backends

Backend	File	Features	Status
Geometric	.geo	Full search + chunk retrieval + path normalization	Requires --features geometric-backend
SQLite	.db	Full search	Default (always available)

Geometric (.geo) features:

• Path normalization before queries
• Explicit ambiguity error handling
• Code chunk retrieval (no file I/O)
• No SQLite dependencies

Backend detection is automatic — no flags needed. Detects by file extension (.geo) and header bytes.

Requirements

• Magellan 3.3.3+ — Required for indexing
• sqlitegraph 3.0+ — Included automatically

Documentation

• MANUAL.md — Complete command reference and examples
• CHANGELOG.md — Version history
• API_INTEGRATION.md — Magellan contract details
• INVARIANTS.md — Behavior guarantees

What llmgrep Does NOT Do

• ❌ Index code (use Magellan)
• ❌ Type checking or semantic analysis
• ❌ Background file watching
• ❌ Code editing (use splice)
• ❌ CFG analysis (use Mirage)

License

GPL-3.0-only. See LICENSE.