Pi SourceLens

A Pi coding agent extension that indexes your codebase and provides structured, provenance-backed file access. Instead of reading entire files from scratch, SourceLens maintains a local index of symbols, regions, and coverage — then retrieves only the relevant code with exact line numbers.

Installation

pi install ./pi-sourcelens

Or from npm once published:

pi install npm:pi-sourcelens

Tools

SourceLens registers five tools for the Pi coding agent:

source_read

Read a file with a compact summary and task-relevant evidence. Returns a file capsule (purpose, key symbols, responsibilities) plus only the source spans relevant to your query, with exact provenance.

Parameters:

• path (required) — File path to read
• intent (optional) — Query intent for targeted retrieval
• mode (optional) — auto (default), structure, or deep
• maxTokens (optional) — Maximum tokens for the result (default: 3500)

source_query

Search indexed files for answers to natural language questions. Returns evidence ranked by relevance with source spans, not a final answer.

Parameters:

• paths (required) — Array of file paths to search
• query (required) — The question to answer
• maxTokens (optional) — Maximum tokens for the result (default: 3500)
• maxDepth (optional) — Maximum evidence expansion depth (default: 3)

source_span

Retrieve exact source lines with freshness verification. Returns literal lines and warns if the file has changed since last indexed.

Parameters:

• path (required) — File path
• startLine (required) — Starting line number (1-based)
• endLine (required) — Ending line number (1-based)

source_index

Explicitly index a file without returning source content. Returns status, coverage, region counts, symbol counts, and errors.

Parameters:

• path (required) — File path to index
• mode (optional) — structure or deep (default: structure)
• force (optional) — Force re-indexing even if current (default: false)

source_status

Inspect coverage, freshness, and index state for a file or all indexed files.

Parameters:

• path (optional) — File path to check. Omit to get global status message.

Human Commands

Use the /sourcelens slash command in the Pi chat:

Command	Description
/sourcelens status [path]	Show coverage and freshness for a file
/sourcelens index <path>	Build or refresh the index
/sourcelens refresh <path>	Force re-index
/sourcelens invalidate <path>	Invalidate cached data
/sourcelens stats	Show statistics
/sourcelens config	Show configuration
/sourcelens help	Show help

How It Works

SourceLens processes files through a pipeline:

1. Snapshot — Reads the file, computes a content hash, detects the language
2. Parse — Uses tree-sitter to extract symbols (functions, classes, variables, etc.) and semantic regions (meaningful code units like function bodies, class declarations)
3. Coverage — Every line is accounted for. Gaps are filled with fallback regions
4. Store — Results are saved to a local SQLite database with version tracking
5. Retrieve — Queries search the index via FTS and symbol lookup, rank candidates, expand evidence along relationships, apply token budgets, and hydrate exact source spans

Supported languages (with tree-sitter parsing): TypeScript, JavaScript, Python, C#, JSON, Go, Rust, Java. Other languages (Markdown, YAML, TOML, XML, HTML, CSS, Bash, etc.) fall back to generic parsing.

Configuration

SourceLens reads configuration from .pi/sourcelens/ in the project root and ~/.pi/agent/sourcelens/ globally. Current defaults:

Setting	Default	Description
analysisPolicy	auto	Analysis mode: auto, structure, or deep
analysisConcurrency	2	Max concurrent region analysis workers
capsuleTokenBudget	600	Max tokens for file capsule
hydrationTokenBudget	2500	Max tokens for hydrated evidence
metadataTokenBudget	500	Max tokens for retrieval metadata
maxEvidenceDepth	3	Max relationship expansion depth
maxEvidenceRegions	8	Max evidence regions

Code Quality

This project uses Biome for formatting and linting:

npm run check        # Run Biome check + TypeScript typecheck
npm run lint         # Run Biome linter
npm run lint:fix     # Auto-fix lint issues
npm run format       # Format all source files
npm run format:check # Check formatting without writing

Scripts

Script	Description
build	Compile TypeScript
test	Run vitest tests
test:watch	Run vitest in watch mode
typecheck	TypeScript type checking
check	Biome check + typecheck
lint	Biome linter
lint:fix	Auto-fix lint issues
format	Format all source files
format:check	Check formatting without writing