blz

BLZ ※

blaze /bleɪz/ (verb, noun)

1. verb – Move or proceed at high speed; achieve something rapidly
2. noun – A trail marker, typically painted on trees with specific colors and patterns; a mark to guide explorers on their journey
3. abbr. – BLZ – A local-first search tool that indexes llms.txt documentation for instant, line-accurate retrieval

---

What is BLZ?

A Rust + Tantivy-based CLI tool that downloads, parses, and indexes llms.txt files locally to enable fast documentation search with line-accurate retrieval.

Quick Start

# Install (one line)
curl -fsSL https://blz.run/install.sh | sh

# Add Bun's docs
blz add bun https://bun.sh/llms.txt

# Search (results in 6ms)
blz find "test runner"
# Or just: blz "test runner"

# Browse documentation structure
blz toc bun --tree -H 1-2

# Pull exact lines (citations auto-detected)
blz find bun:304-324 --json
# Or: blz bun:304-324 --json

MCP Server Setup

Enable BLZ in your AI coding assistant with one command:

# Claude Code
claude mcp add blz blz mcp-server --scope user

# Cursor, Windsurf, and others
# See detailed setup: docs/mcp/SETUP.md

What you'll see:

✓ Added bun (1,926 headings, 43,150 lines) in 890ms

Search results for 'test runner' (6ms):

1. bun:304-324 (score: 92%)
   📍 Bun Documentation > Guides > Test runner

   ### Test runner
   Bun includes a fast built-in test runner...

Docs

• Documentation index – Overview of every guide, reference, and technical deep dive.
• Quickstart guide – Install BLZ and run your first searches in minutes.
• Agent playbook – Best practices for using BLZ inside AI workflows.
• Architecture overview – Core components, storage layout, and performance notes.

What's llms.txt?

llms.txt is a simple Markdown standard for making documentation accessible to AI agents. llms-full.txt is an expanded version that includes all documentation for a project.

Why they're great:

• Comprehensive documentation that's kept up to date
• Single file in a standardized format makes for easy retrieval and indexing

The challenge:

• They're huge (12K+ lines, 200K+ tokens)
• Too context-heavy for agents to use directly
• Keeping them up to date is manual work

Why BLZ?

BLZ indexes llms.txt documentation files locally:

• 6ms search across locally saved docs (vs. seconds for web requests)
• Exact line citations (e.g., bun:304-324) for copy-paste accuracy
• Works offline after initial download
• Smart updates with HTTP caching (only fetches when changed)

The Problem

Projects publish complete docs as llms-full.txt files, but:

• They're massive (12K+ lines, 200K+ tokens)
• Too context-heavy for agents to use directly

But what about MCP servers for searching docs?

• They're great, and we use them too! but...
• Results can take up a lot of an agent's context window
• May require multiple searches to find critical info

BLZ's Solution

Cache & index llms.txt locally → search in ms → retrieve only needed lines

With BLZ, agents can get the docs they need in a fraction of the time, and context.

See docs/architecture/PERFORMANCE.md for detailed benchmarks and methodology.

Features

• Unified find command: Smart pattern detection automatically routes queries to search or retrieval
• Heading level filtering: Search within specific heading depths with -H flag (e.g., -H <=2 for top-level sections)
• One-line installation: Install script with SHA-256 verification and platform detection
• Fast search: 6ms typical search latency with exact line citations
• Offline-first: Works offline after initial download, smart updates with HTTP caching
• Clipboard support: Copy search results directly with --copy flag
• Source insights: Commands for visibility (blz stats, blz info, blz history)
• Enhanced TOC Navigation
  • Heading level filtering (-H 1, -H 2-3, -H <=2, -H >3)
  • Tree view visualization with box-drawing characters (--tree)
  • Multi-source TOC browsing (--source bun,react or --all)
  • Backward compatible with --max-depth
• Direct CLI integration: IDE agents run commands directly for instant JSON results
• MCP server: stdio-based integration via official Rust SDK for deep AI assistant integration

Language Filtering

BLZ automatically filters non-English content from multilingual documentation sources:

• Enabled by default: Reduces storage by 60-90% for multilingual sources
• Opt-out available: Use --no-language-filter to keep all languages
• Retroactive: Use blz refresh <source> --reindex --filter on existing sources

# Add source with filtering (default)
blz add anthropic https://docs.anthropic.com/llms-full.txt