Code Intelligence

Local Indexer

The code intelligence indexer runs entirely on your machine. It uses a local SQLite database and web-tree-sitter WASM parsers — no code is sent to external services. The indexer supports 21 languages including:

• TypeScript, JavaScript (including JSX/TSX)
• Python, Go, Rust, Java, C, C++
• Ruby, PHP, Swift, Kotlin, Scala
• C#, Dart, Elixir, Lua, Zig
• Objective-C, OCaml, Bash

Two-Phase Pipeline

Indexing happens in two phases to balance speed with depth:

• Fast pass — Regex-based import extraction at approximately 1ms per file. Captures import/require statements and resolves relative paths. This is the primary indexing mode and runs for all files.
• Full parse — Tree-sitter AST parsing for symbol definitions, call sites, and detailed structural analysis. Provides richer data for community detection and call graph traversal.

Wave-Based Background Indexing

Full repository indexing runs in a background worker process and proceeds in waves to deliver results incrementally:

1. Wave 1: Neighborhood — The current working directory and its parent. Indexes the files you are most likely working on first for instant results.
2. Wave 2: Workspace — The current package or module. Broadens context within the local project boundary.
3. Wave 3: Full repo — Everything else in the repository. Complete coverage of all supported files.
4. Wave 4: Community detection — Analyzes the import graph to detect structural communities (clusters of tightly connected files). Used for the Knowledge Map visualization.

Incremental re-indexing only processes files whose modification time has changed since the last index, keeping subsequent runs fast.

Auto-Expansion

When you call query_insights with file_context, Surchin automatically expands your file list by traversing the code graph. Files that import or are imported by your context files are added to the query, so you receive insights about structurally related code without having to specify every relevant path.

Results from connected code appear in a separate “From Connected Code” section in the response, clearly distinguished from direct matches.

To disable auto-expansion for a specific query, pass expand_context: false.

// Auto-expansion enabled by default
query_insights({
  query: "auth token validation",
  file_context: ["src/auth/validator.ts"]
})

// Disable auto-expansion
query_insights({
  query: "auth token validation",
  file_context: ["src/auth/validator.ts"],
  expand_context: false
})

Knowledge Map

The dashboard includes a Knowledge Map visualization at /dashboard/knowledge-map. It renders a force-directed graph of your codebase's import structure overlaid with insight density. Communities detected during Wave 4 are highlighted as clusters, and a treemap view provides an alternative layout showing relative file sizes and insight coverage.

MCP Tool: index_codebase

Use the index_codebase MCP tool to trigger a manual re-index. This is useful after large refactors, branch switches, or when you want to ensure the code graph is up to date before running queries. The indexer runs in the background and reports progress via wave completion messages.