Home / Docs / Code Indexing

Helixor Code Indexing

Helixor Code indexing compiles local source trees into typed structural code artifacts that AI coding agents can query through MCP. The index is engineered to answer deep code questions with compact, freshness-stamped payloads instead of dumping raw file trees into model context.

What The Index Provides

The index captures source structure across 12 languages: files, symbols, type definitions, imports, callers and callees, control and data flow, architecture motifs, quality signals, and impact graphs. Agents access the index through dedicated MCP tools:

MCP Tool	Description & Action Modes
`code.index`	Status, build, workspace registration, refresh, rebuild, concept diff, and deletion.
`code.search`	Structural symbol search, definition lookup, flow explanation, symbol registry, and compare.
`code.diff`	Concept diffs, topic comparisons, working-tree diffs, and impact-oriented structural views.
`code.graph.analyze`	Imports, importers, callers, call trees, impacted tests, and graph density summaries.
`code.review`	Freshness, architecture rule checks, quality assessments, and negative motif detection.
`code.impact.analyze`	Computes blast radius and lists likely impacted code paths and test targets before refactoring.
`code.tests.find`	Identifies unit and integration tests that exercise a given concept, API, symbol, or file.

Artifact Storage & Root

By default, structural index artifacts reside locally on the developer machine at:

~/.helixor/code_index

Override the artifact root when starting the companion or invoking an index command:

helixor up --index-root /path/to/custom-root
helixor index /path/to/repo --index-root /path/to/custom-root

Root Mismatch Safety

If the CLI is instructed to index against a root differing from the running companion process, it fails closed with HELIXOR_INDEX_ROOT_MISMATCH to prevent cross-root pollution.

Building Repository Indexes

Index a repository with standard options:

helixor index /path/to/repo

Specify an explicit codebase identifier:

helixor index /path/to/repo --codebase-id payment-gateway

Run a high-speed sparse parse (symbols and imports only):

helixor index /path/to/repo --sparse

Run a full deep parse with flow and bond compilation:

helixor index /path/to/repo --full

Preview an indexing run without persisting artifacts to disk:

helixor index /path/to/repo --dry-run

Workspace Discovery

When indexing a multi-repo directory or monorepo workspace, Helixor detects individual subproject boundaries instead of flattening distinct projects into a single monolithic index. Discovery looks for key project markers:

Ecosystem	Project Boundary Markers
Git	`.git`
Python	`pyproject.toml`, `setup.py`, `setup.cfg`
JavaScript / TypeScript	`package.json`
Java / Kotlin / Gradle	`pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`
Rust	`Cargo.toml`
Go	`go.mod`

Lazy vs. Eager Workspaces

Choose between lazy and eager indexing models for large engineering workspaces:

Lazy Indexing (Default): Records the workspace project router and defers full compilation of individual subprojects until an AI agent queries that specific module. Saves gigabytes of disk and minutes of initial indexing time.
```
helixor index ~/code/workspace --index-strategy lazy
```
Eager Indexing: Immediately compiles every discovered project below the directory root. Recommended for build servers, CI, or small repos.
```
helixor index ~/code/workspace --index-strategy eager
```

Commit-Aware Freshness

Source code is constantly modified while coding. Rather than forcing a complete re-index on every keystroke or returning stale symbol lookups, Helixor monitors git working tree status and splices uncommitted diffs into queries in real-time.

The agent receives an explicit freshness badge alongside results (e.g. freshness: clean or freshness: stale in 2 files; git diff spliced), completely eliminating false confidence from outdated caches.

Previous ← CLI Reference Next Local Desk (/desk) →