Heides

HEIDES is a deterministic harness that gives AI coding agents what they do not have on their own. Senses, memory and judgment for code. Before an agent touches anything, HEIDES maps the entire codebase into a persistent graph, derives warnings and edge cases from that map, and grounds every plan against reality. The agent suggests. HEIDES decides what is safe.

HEIDES does not compete with agents. It is the substrate beneath them. One binary, no cloud, no model required for the core. It runs on a laptop, a server, a CI runner, and a phone running Termux.

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. Linters and tests catch that damage after it lands, and only on paths that actually run. 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 at the moment that matters, before the patch is applied. It answers questions no tool answers in that instant. Who calls this function? Which imports does this file really use? Does this change conflict with the current graph? Is user input flowing into a SQL string, a shell, or a prompt?

Architecture

HEIDES is 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 is updated incrementally as files change. Every later query, from Harmony guards to Grounding plans to the agent itself, reads the same map. 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?

One command, describe, prints the whole map as a workspace manifest. Entrypoints, files that run module level code, the most connected symbols, call cycles and which files talk to which. An agent reads the manifest and the neighbors of one symbol instead of walking the tree, kilobytes instead of megabytes. One command, export, writes the entire map to a single file, every file sheet with its symbols, signatures, docs and edges, plus a presence ledger that lists every file the walker saw even when it was not parsed, so nothing in a codebase is ever invisible.

Harmony

Judgment. Harmony runs the guard modules against the Spine graph and against proposed patches. Every guard is deterministic and reports evidence, never guesses.

• Staged apply. Compares current code against proposed code and blocks conflicts before anything is written to disk.
• Edge cases. Flags missing null, empty, error path and boundary handling on every changed function.
• Security taint. Traces user input into SQL, shell, filesystem and prompt sinks, and through the mark_safe framework sink into rendered output.
• Dependency. Detects upgrades that break the imports this project actually uses.
• Practices. Surfaces violations of project conventions.

Warnings are delivered the way a senior reviewer would deliver them. A file, a line, a severity, and the reason.

Here is what a finding looks like.

[critical] user controlled input reaches a SQL sink on this line. source at line 3 (security.taint) at app.js:12

Grounding