rust cli mcp code analysis llm tokens 

HEIDES

The code nervous system. HEIDES gives any LLM instant, deterministic understanding of a codebase, so agents stop reading files and start knowing them.

Version

v0.14.4

License

MIT

Platforms

Linux, macOS, Windows, Termux

Interfaces

CLI, MCP

View on GitHubnpm packageMCP server

Why it exists

An AI agent is powerful and blind. It can generate a perfect function and still break three callers it never saw, because it has no persistent map of the code. To understand a codebase it reads files one by one, spends tokens on megabytes it does not need, and still misses the structure that matters. The classic failure: an agent changes a signature, unexercised call sites break, the test suite stays green, and production breaks at two in the morning.

HEIDES closes that gap in both directions. It gives the agent a persistent graph instead of a file dump, so the answer to who calls this, what imports this, does this change break anything, is a query, not a paste of the repository. And it guards changes against that graph at the moment that matters, before the patch is applied.

Token economics

The point is measurable. The HEIDES spine for a real workspace indexes 45 files, 152 symbols, and 1823 call edges in under a second. The question “who calls describeBrain” returns two callers with file and line numbers in roughly 200 tokens. Reading the same answer out of the source would cost tens of thousands of tokens, or an agent’s time walking the tree. In an agent loop that runs every turn, that difference is the difference between a budget that holds and a budget that burns.

The same manifest compresses the whole workspace. One command prints the map: entrypoints, the most connected symbols, call cycles, which files talk to which. An agent reads the manifest and the neighbors of one symbol instead of the tree. Kilobytes instead of megabytes.

Architecture

Three organs over one spine, all deterministic, all local, all explainable.

The Spine

Perception and memory. The Spine walks the codebase and builds a compact persistent graph of symbols, files, callers, callees, imports, signatures, docs, constants, fields and enum variants, with module level code first class. The index lives in a sqlite database at .heides/index.db in the workspace and updates incrementally as files change. No model is involved. This layer is pure analysis.

The graph answers these questions directly.

  • Who calls this symbol?
  • Who imports this module?
  • Where is this symbol defined?
  • What does this function call?
  • What does this file talk to?
  • What is this symbol for, from its own doc comment?

Harmony

Judgment. Harmony turns the graph into findings with evidence: dead code, unused imports, write only fields, duplicated files, infinite loops, resource leaks, missing error handling, and security taint. Then it guards changes with gates: staged diffs are checked against the graph before they land, so a breaking change is blocked with the exact caller that breaks, not a unit test that passed anyway.

Grounding

Planning. Grounding forces plans to cite the graph. Every proposed edit must name the files it touches, the symbols it affects, and the callers it risks. The plan that does not ground itself is refused.

Install

The npm package is a tiny installer that downloads the prebuilt binary for your platform and exposes the heides command. No Rust toolchain needed.

npm install -g heides
heides --help

CLI reference

# Build the graph of the current workspace
heides scan .

# Read the map: files, symbols, call edges, entrypoints, hubs
heides describe .

# Write the full map to a single file with a presence ledger
heides export . map.txt

# Check the workspace for blockers, criticals, warnings
heides check .

# Block a breaking patch before it lands
git diff > patch.diff
heides staged patch.diff .

# Ground a plan against the graph before applying it
heides plan .

MCP setup

HEIDES speaks Model Context Protocol natively. Start the server and point any MCP capable agent at it.

heides mcp

Once connected, the agent gains eleven tools.

  • spine.scan index a workspace
  • spine.describe read the workspace manifest
  • spine.neighbors list callers and callees of any symbol
  • spine.query ask the graph direct questions
  • harmony.check run guards and taint analysis
  • harmony.report full findings report as JSON
  • harmony.staged check a patch against the graph
  • grounding.plan ground a plan against reality
  • grounding.scaffold scaffold a workspace
  • deps.check scan dependencies for advisories
  • web.confirm confirm external references

This works in any platform that speaks MCP: CLI agents, Cursor style editors, VS Code extensions, Kilo, and plain terminals. The agent stops pasting files and starts asking questions.

CI integration

Add one command to the pipeline so every change is guarded before it ships.

- run: heides scan .
- run: heides staged ${{ github.event.pull_request.diff_url }} .
- run: heides check .

A breaking change fails the build with the exact caller that breaks.

Requirements

  • Linux, macOS, Windows, or Termux
  • No cloud, no account, no model required for the core
  • Works on a laptop, a server, a CI runner, and a phone

Repository

The full source is on GitHub with the complete architecture documentation, the changelog, and the MIT license.