llmgrep 1.0.0

Smart grep over Magellan code maps with schema-aligned JSON output
Documentation

llmgrep

v1.0 Production-Ready CLI (shipped 2026-01-25)

A command-line search tool for code indexed by Magellan. Queries SQLite graph databases to find symbols, references, and call relationships. Outputs human-readable or structured JSON for programmatic use.

Crates:

  • magellan - Code indexing and database creation
  • llmgrep - This tool (query only)

Note: llmgrep requires a Magellan database. It does not build or modify databases — Magellan handles indexing and freshness.

What it does

  • Searches symbols, references, and calls from Magellan's code database
  • Emits deterministic, schema-aligned JSON output for LLM consumption
  • Supports regex, intelligent relevance ranking, and optional context/snippets
  • --sort-by {relevance|position} flag for LLM-optimized or performance modes

Features

LLM-Optimized Search

  • Relevance mode (default): Intelligent scoring using regex matching (exact > prefix > contains)
  • Position mode: Fast SQL-only sorting, skips in-memory scoring

Security

  • ReDoS prevention via 10KB regex size limit
  • Resource bounds validation on all parameters
  • Path traversal blocking with canonicalize()

Developer Experience

  • LLM-E### error codes with remediation hints
  • Database validation (checks existence before connection)
  • Distinguishes "database not found" from "database corrupted" errors
  • File read error logging with context

Quality

  • 118 unit tests with 87.72% coverage
  • Clippy-clean codebase with zero warnings
  • Comprehensive CLI examples in help text

Install

cargo build --release
cp target/release/llmgrep ~/.local/bin/llmgrep

Or install from crates.io:

cargo install llmgrep

Quick start

llmgrep requires a Magellan database. First, build one:

# Install Magellan (if not already available)
cargo install magellan

# Build a database from your code
magellan watch --root /path/to/repo --db /tmp/repo.db

Then query it with llmgrep:

# Basic symbol search (relevance-ranked, LLM-friendly)
llmgrep search --db /tmp/repo.db --query "parse"

# Position-only sorting (faster, no scoring)
llmgrep search --db /tmp/repo.db --query "parse" --sort-by position

# Regex search with JSON output
llmgrep search --db /tmp/repo.db --query "^Token" --regex --output json

# Reference search
llmgrep search --db /tmp/repo.db --query "MyType" --mode references

Documentation

  • llmgrep search --help — Built-in usage examples
  • MANUAL.md — Full manual with all options
  • CHANGELOG.md — Version history

Compatibility

  • Magellen schema: 1.0.0 (JsonResponse wrapper)
  • Magellen export: 2.0.0
  • Minimum Magellen: 1.7.0

License

GPL-3.0-only. See LICENSE.md.