indxr

Fast codebase indexer for AI agents. Tree-sitter AST parsing + regex extraction across 27 languages. Built in Rust.

Install

cargo install --path .

Usage

indxr                                        # index cwd → stdout
indxr ./my-project -o INDEX.md               # index project → file
indxr -f json -l rust,python -o index.json   # JSON, filter by language
indxr serve ./my-project                     # start MCP server

Output

Default format is Markdown at signatures detail level:

# Codebase Index: my-project

> Generated: 2025-03-23 | Files: 42 | Lines: 8,234
> Languages: Rust (28), Python (10), TypeScript (4)

## Directory Structure
src/
  main.rs
  parser/
    mod.rs
    rust.rs

## Public API Surface

**src/main.rs**
- `pub fn main() -> Result<()>`
- `pub struct App`

---

## src/main.rs

**Language:** Rust | **Size:** 1.2 KB | **Lines:** 45

**Imports:**
- `use anyhow::Result`
- `use clap::Parser`

**Declarations:**

`pub fn main() -> Result<()>`

`pub struct App`
> Fields: `name: String`, `config: Config`

Three output formats (-f): markdown (default), json, yaml.

Three detail levels (-d):

Languages

8 tree-sitter (full AST) + 19 regex (structural extraction):

Detection is by file extension. Full extraction details: docs/languages.md

Filtering

indxr --filter-path src/parser              # subtree
indxr --kind function --public-only         # public functions only
indxr --symbol "parse"                      # symbol name search (case-insensitive substring)
indxr --filter-path src/model --kind struct --public-only  # combine
indxr -l rust,python                        # language filter

All filters compose. --kind accepts: function, struct, class, trait, enum, interface, module, method, constant, impl, type, namespace, macro, table, service, message, rpc, and more.

Git Structural Diffing

Declaration-level diffs against any git ref:

indxr --since main
indxr --since v1.0.0
indxr --since HEAD~5

## Modified Files

### src/parser/mod.rs
+ `pub fn new_parser() -> Parser`
- `fn old_helper()`
~ `fn process(x: i32)` → `fn process(x: i32, y: i32)`

Markers: + added, - removed, ~ signature changed. Supports --filter-path, -l, --public-only, -f json.

Token Budget

Progressive truncation to fit context windows:

indxr --max-tokens 4000

Truncation order: doc comments → private declarations → children → least-important files. Directory tree and public API surface are preserved first.

File importance scoring: entry points (main.rs, lib.rs, index.ts) > root proximity > public declaration count.

MCP Server

JSON-RPC 2.0 over stdin/stdout, MCP spec 2024-11-05:

indxr serve ./my-project

MCP config:

{
  "mcpServers": {
    "indxr": {
      "command": "indxr",
      "args": ["serve", "/path/to/project"]
    }
  }
}

Setup guides: docs/mcp-server.md

Caching

Incremental binary cache in .indxr-cache/cache.bin. Two-tier validation: mtime + file size (fast path), xxh3 content hash (fallback). Cache format is versioned — automatically rebuilt on indxr upgrades.

indxr --no-cache          # bypass cache
indxr --cache-dir /tmp/c  # custom location

Performance

Parallel parsing via rayon. Incremental caching via mtime + xxh3.

Architecture

1. Walk directory tree (.gitignore-aware, via ignore crate)
2. Detect language by file extension
3. Check cache — skip unchanged files (mtime + xxh3)
4. Parse with tree-sitter or regex (parallel via rayon)
5. Extract declarations, metadata, relationships
6. Apply filters (path, kind, visibility, symbol)
7. Apply token budget (progressive truncation)
8. Format as Markdown, JSON, or YAML
9. Update cache

Documentation

License

MIT