Repository intelligence

Repository intelligence

Holaryn builds a local, disposable map of the repository behind each Code session. The map gives
coding agents compact typed tools for definitions, references, implementations, diagnostics,
dependencies, relevant tests, and task-specific context. Every returned excerpt names its file,
one-based source range, symbol, analyzer provenance, selection reason, content hash, and applicable
repository-instruction snapshot.

The index is an accelerator, not a source of truth. File browsing and editing continue when it is
missing, stale, or corrupt.

Use it

The Code side panel has an Index view. It shows the branch and revision, file/symbol/diagnostic
counts, cache size, language-service health, and safe failure details. Refresh changed files
updates only content or instruction snapshots that changed. Rebuild from source discards the
current revision cache and recreates it.

The equivalent CLI commands are:

holaryn repository C:\work\project status
holaryn repository C:\work\project refresh
holaryn repository C:\work\project query definition Greeter
holaryn repository C:\work\project query references Greeter
holaryn repository C:\work\project context "change Greeter error handling" --token-budget 4000
holaryn repository C:\work\project rebuild
holaryn repository C:\work\project delete --all-revisions

On Linux and macOS, use the same commands with the appropriate workspace path.

Coding sessions expose three model tools:

• repo_query for search, definition, references, implementations, diagnostics, outline,
  dependencies, and relevant tests;
• repo_context for a deterministic ranked context pack under an explicit token budget; and
• repo_index for status, refresh, rebuild, and deletion of the derived cache.

The Code API mirrors these operations beneath
/api/code/sessions/<chat-id>/index. It returns the same typed JSON used by the tools and UI.

Language support and honest fallback

Python uses the standard-library AST for definitions, inheritance, imports, calls, references, and
syntax diagnostics. TypeScript and JavaScript ship with a bounded structural map for declarations,
methods, imports, inheritance/implementation edges, calls, and gross delimiter diagnostics. An
operator may inject a richer language service through the provider-neutral LanguageService
interface; a repository cannot configure or launch an executable language-server command.

Rust declarations and Markdown headings have structural fallbacks. Other text formats remain
lexically mapped and appear as fallback health, rather than pretending compiler-quality analysis.
Editing never waits for a language service.

Boundaries and configuration

The scanner honors Git's tracked/untracked inventory and ignore rules when Git is available. It
otherwise walks the workspace while excluding generated/vendor directories. Canonical path checks
reject symlinks that escape the workspace. Binary/non-UTF-8 files and files over 1 MB are skipped
with visible diagnostics.

Optional .holaryn/intelligence.json is data-only:

{
  "include": ["src/**/*.py", "web/**/*.ts"],
  "exclude": ["**/fixtures/**"],
  "max_file_bytes": 1000000,
  "max_files": 50000
}

Only those four keys are accepted. Commands, environment variables, hooks, and language-server
executables are ignored.

Indexes live under the Holaryn state directory, outside the repository, partitioned by canonical
workspace, Git worktree, schema, and revision. Content hashes update the current namespace after
edits or checkpoint restores. A branch/revision switch selects a distinct namespace. Source
content is not stored in SQLite; the cache holds metadata, symbols, relations, diagnostics, hashes,
and instruction snapshots. Delete it at any time; refresh recreates it. A corrupt database is
deleted and rebuilt automatically on refresh.

Context benchmark

The committed benchmark compares a naive full UTF-8 repository context with the ranked structural
pack using the same four-characters-per-token estimate:

uv run python scripts/repository_intelligence_benchmark.py . RepositoryIntelligence --token-budget 4000

Record the JSON result with release evidence. The baseline intentionally represents the expensive
fallback this feature replaces; it does not claim model-quality equivalence. Acceptance requires a
matching definition/context result and a material token reduction on the release checkout.

The reviewed SA-134 baseline indexed 1,528 files and 38,497 symbols in 26.4 seconds. The
RepositoryIntelligence query found the Python AST definition and selected 10 excerpts totaling
3,928 estimated tokens, compared with 8,297,316 estimated tokens for the full UTF-8 checkout: a
99.953% reduction. The machine-readable evidence is
benchmarks/baselines/repository-intelligence-v1.json.

Troubleshooting and rollback

If the Index panel reports Needs refresh, use Refresh changed files. If diagnostics or
counts remain implausible, use Rebuild from source. Inspect fallback rows to see whether a full
language service is unavailable. Index notices contain paths and safe parser details, not source
content.

Rollback requires no state migration: revert the feature and delete repository-intelligence
under the Holaryn state directory. Repository files, Git state, checkpoints, and transcripts are not
modified by index deletion.