Source intelligence

Source intelligence is Horus's understanding of your code. It lets Horus resolve incident hints into concrete symbols, trace impact across call paths, detect recent changes, and connect async boundaries such as queues. It is not a separate product: it is the code-analysis layer that runs behind the Horus CLI.

What source intelligence is

When you investigate an incident, you usually ask questions like: What code handles checkout? Who changed it recently? What calls the payment service? What else breaks if it fails? Source intelligence gives Horus the structured code context it needs to answer those questions deterministically.

It is built from three pieces:

1. A parsed representation of your repository: functions, classes, files, imports, and relationships.
2. A graph that connects those symbols through calls, imports, async messages, and shared data.
3. A local host that answers Horus queries over HTTP so evidence stays fast and private.

Why Horus uses a source-intelligence host

Parsing a codebase is slow. Querying it should be fast. The host parses your repository once, stores the graph, and serves queries on demand. This separation means:

• horus explain can resolve a symbol in milliseconds.
• horus investigate can ask many graph questions without re-parsing.
• Multiple Horus commands share the same indexed view of the code.

The host is tied to a repository on disk. horus init --source <url> records an external host URL in .horus/config.json; otherwise horus init is what analyzes the repo, hosts it, and records the host URL. When you run horus hosts, you see every registered host and whether it is currently running.

Indexing with horus init

horus init is the command that refreshes source intelligence for a project. Beyond writing and registering config on first run, it does three things:

1. It analyzes the repository when no index exists or the existing one is stale, and makes sure the source-intelligence host is running, reusing a healthy one.
2. It runs the stitcher to build the queue map, connecting queue producers to workers across async boundaries.
3. It builds a local project-knowledge snapshot of the repository into .horus/index/ (an offline, code-context index you can query with horus knowledge or expose to agents via horus mcp).

cd /path/to/your-repo
horus init
horus init --env production

If the host is not running, horus init attempts to start it. If that fails, see Troubleshooting.

Code graph concepts

The graph is the mental model Horus uses. Every node is a symbol, file, or external system. Edges describe relationships.

These concepts show up as evidence in investigations. For example, if Horus suspects PaymentGateway caused a spike, it can show callers, callees, recent changes, and downstream queue consumers as supporting evidence.

Source-intelligence commands

horus explain

Explain a symbol: where it lives, what calls it, what it calls, and how important it is to the system.

horus explain AuthService.login
horus explain AuthService.login --depth 2 --json

Use --depth to control the impact depth (how many hops to follow). Use --json when you want structured output for scripts.

horus search

Search symbols across all configured repositories. Useful when you know a keyword but not the exact symbol name.

horus search "checkout"
horus search "checkout" --limit 10 --json

horus architecture

Discover the living architecture of the project: subsystems, async boundaries, external systems, and fragility points. This is not a hand-drawn diagram; it is derived from the current code.

horus architecture
horus architecture --json

horus blast-radius

Given a symbol, show what could break if it fails. Horus walks upstream and downstream dependencies, including async boundaries, and returns a scoped impact view.

horus blast-radius PaymentGateway
horus blast-radius PaymentGateway --depth 2 --json

horus trace and horus insights

horus trace <from> <to> finds the shortest static relationship path between symbols across calls, imports, inheritance, implementations, and type usage. horus insights shows hubs and cross-community bridges in that same graph. Neither reconstructs distributed runtime spans.

horus trace CheckoutController PaymentGateway --json
horus insights --hubs 8 --bridges 8 --json

See trace and insights for depth, relationship, and result-limit options. Refresh the graph with horus init --reindex after a backend upgrade when old capabilities are reported.

horus owner

Estimate ownership for a symbol or component from git history, with confidence and evidence. It is a heuristic, not org-chart truth.

horus owner PaymentGateway --json

horus repos and horus hosts

horus repos lists configured repositories and their host health. horus hosts lists source-intelligence host processes and whether they are running.

horus repos
horus hosts

horus status

Show the health of source intelligence alongside connectors and project configuration.

horus status

horus knowledge and horus mcp

Alongside source intelligence, horus init writes a local project-knowledge snapshot into .horus/index. horus knowledge queries that offline snapshot — no Cloud — with subcommands status, search, contracts, trace, ask, validate, push, and pull. horus mcp runs the Horus MCP server over stdio, exposing the same local project-knowledge index to agents.

horus knowledge status
horus knowledge search "checkout"
horus mcp

How source evidence appears in investigations

When you run horus investigate, Horus combines runtime evidence with source evidence. Source evidence can include:

• Symbols matching the incident hint.
• Call paths from a suspected cause to runtime entry points.
• Recent commits touching a suspected symbol.
• Downstream queue consumers or upstream callers that explain blast radius.
• Architecture context such as subsystems and external dependencies.

Source evidence is always labeled as such. It never overrides runtime evidence in scoring; it enriches it.

What is local vs remote

With the default setup, the backend and graph run on your machine and answer graph queries locally. An external host configured through horus init --source <url> runs wherever you host it. Local source analysis does not require a remote AI service.

Optional --ai sends report context (the hint, evidence titles and short excerpts, causes, and hypotheses) to Anthropic after deterministic investigation. Optional Cloud sync uploads saved reports and horus knowledge push uploads code-derived knowledge snapshots. An explicitly configured external --source host receives graph queries. See Security for the complete data flows.

Storage backend (SQLite)

As of horus-source 2.0.0, the code graph and its embeddings are stored in SQLite. Each repository keeps a single .horus/source/horus.db file (WAL mode) that combines three things: the graph (nodes and edges), vector search via the sqlite-vec extension (vec0 brute-force cosine — the same algorithm the previous backend used), and keyword search via SQLite's built-in FTS5 (BM25). This replaces the previous KùzuDB backend, retiring an end-of-life dependency and dropping its native library for a lighter install. The backend ships inside the Horus release bundle — one bundle, one version — so the CLI always installs and validates the backend version paired with its own release.

Upgrading from a KùzuDB store

Update the backend, then re-index. The graph is rebuildable from source, so there is no manual data migration — the next index auto-detects a legacy .horus/source/kuzu store, prunes it, and rebuilds on SQLite.

# Update the bundled CLI and source-intelligence backend
horus update

# Rebuild the source graph after a backend upgrade
horus init --reindex

Platform requirement: glibc

If you run the backend in a container, use a glibc base image (for example Debian or Ubuntu) rather than Alpine. Current CLI releases validate the bundled backend version; installing a historical PyPI backend is not a supported workaround for that pin.

Transitional KùzuDB backend

The source backend bundled with the current CLI still implements a temporary KùzuDB alternative selected by HORUS_SOURCE_STORAGE_BACKEND=kuzu. It requires the optional kuzu dependency in the same release-paired backend environment; the default install does not include that extra. This is a deprecated transition path, not a reason to install an older backend from PyPI: the CLI validates the backend version against its own bundle. Use SQLite on macOS or a glibc-based Linux runtime for the default setup.

Prerequisites and limitations

• Source intelligence is optional. You can run runtime-only investigations, but impact analysis, queue stitching, and symbol resolution will be weaker.
• Indexed languages are Python, TypeScript, JavaScript, Go, Java, and Rust.
• The backend itself runs on Python 3.11+ (independent of the languages it analyzes) and ships as a wheel inside every Horus release — curl installer, npm, and Homebrew. The curl installer installs it with uv (or pip); on npm and Homebrew installs, horus init installs the bundled wheel with uv when the backend is missing. Python 3.11+ is the only prerequisite, plus uv for npm and Homebrew installs (the curl installer falls back to pip).
• The SQLite storage backend requires a glibc-based Python (Linux glibc x86_64/aarch64 or macOS); Alpine/musl is not supported. See Storage backend.
• Very large monorepos may take longer to index. horus init re-analyzes only a missing or stale index; run horus init --reindex after large refactors to force a full rebuild.
• Dynamic language features (runtime monkey-patching, string-based imports) may not appear in the graph.

Common failure modes

Shipped vs planned

Shipped today:

• Multi-language indexing — Python, TypeScript, JavaScript, Go, Java, and Rust in one code graph.
• Symbol search and explanation.
• Call-graph and ownership heuristics.
• Architecture and blast-radius analysis.
• Queue-boundary stitching via horus init — BullMQ (JS/TS) and Celery, Dramatiq, huey, and procrastinate (Python).
• Local source analysis, with optional external hosts and Cloud knowledge sync.
• Shortest relationship paths (horus trace) and graph hubs/bridges (horus insights).

Planned or under development:

• Incremental indexing for very large repositories.
• Cross-language graph edges for polyglot systems.
• Richer type-aware impact analysis.