HEIDES

The code nervous system

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

Refinement. Grounding takes an objective or a plan and checks it against the Spine and against the outside world. It confirms feasibility, surfaces missing prerequisites, and returns a bounded specification that the agent then builds against. For new projects it turns a plan into a scaffold, indexes the newborn workspace immediately so it reads back through the same map, and hands a clean foundation back to the agent. For facts that change over time it can consult the web and update its own knowledge.

How it works

HEIDES is event driven. It wakes when a session starts or a file changes, works, and sleeps when the job is done. Nothing is stale because everything recomputes on demand against the persistent index.

1. The agent or user summons HEIDES before any change.
2. The Spine maps the codebase and saves the index.
3. Harmony derives warnings, edge cases and security notes from the map.
4. The user states the objective. Grounding refines it. This is not feasible as stated, it needs these pieces, this variant is sound.
5. The agent builds against the grounded spec while HEIDES guards every proposed patch.
6. The job ends. HEIDES goes dormant until the next trigger.

How the guards work

• Staged apply. An agent proposes a patch that changes add(a, b) into add(a, b, c). HEIDES applies the patch in memory, parses the changed file again, compares signatures against the spine, finds that main still calls add with two arguments, and reports a blocker with the exact call site. Nothing has been written to disk.
• Security taint. A line assigns from req.query. A later line passes that variable into db.query. HEIDES reports the sink line and names the source line. SQL, shell, filesystem and prompt injection sinks are covered across every deep language. Django mark_safe is the single framework sink, user content that reaches it reports critical with the source line named.
• Edge cases. unwrap calls, JSON.parse without try, bare except blocks, mutable python defaults and unguarded storage reads are flagged with a severity.
• Best practices. Leftover debug output, unfinished markers, hardcoded secrets and overlong functions are reported as info or warnings.
• Dependencies. Manifests are read, every pinned package is checked against the OSV vulnerability database, and the latest published version is fetched for comparison.

Connectivity

One core, every shell. The same binary speaks to everything.

• CLI. Native commands are scan, status, query, describe, export, check, staged, plan, scaffold, deps, watch, mcp and version. Query reads callers, imports, definition, calls, neighbors and search for one symbol or phrase. Describe prints the workspace manifest in one read. Export writes the whole map as one file.
• MCP. A Model Context Protocol server over stdio. Any MCP aware agent, editor or harness attaches directly. Also listed in the official MCP registry as io.github.AbduljabbarBXR/heides, installable by name from registry aware clients.
• Agent systems. Claude Code, Codex, Cursor, OpenCode, Hermes and custom builds via MCP.
• Skills. HEIDES exposes its capabilities as MCP tools and resources, so skill systems can compose it.
• VS Code. Native MCP support in VS Code attaches to the same server. An extension is planned.
• Mobile. The same static binary runs on Android Termux and other Unix systems.

No ports, no daemon protocol, no cloud account. Just one process on stdio.

MCP tool reference

The server exposes eleven tools.

• spine.scan. Map the current codebase into the persistent spine index.
• spine.query. Ask who calls a symbol, who imports a module, where a definition lives, what a function calls, or search names, signatures and docs as free text.
• spine.describe. Read the whole workspace manifest in one call, languages, symbol counts, entrypoints, hubs and doc coverage per language.
• spine.neighbors. Show every side of a symbol, its definition with the captured doc, its callers and the calls it makes out.
• harmony.check. Run every guard on the workspace and return findings with evidence.
• harmony.report. Run every guard and return the verdict as structured JSON with severity counts.
• harmony.staged. Check a unified diff before applying it. Blocks conflicts and signature breaks.
• grounding.plan. Evaluate a plan against the codebase. Confirms symbols, flags missing ones, checks paths.
• grounding.scaffold. Scaffold a new project from a plan and index it immediately.
• deps.check. Check dependencies for known vulnerabilities and outdated versions.
• web.confirm. Confirm a fact against the package registries on the web.

Security model

• Deterministic by design. Findings carry a file, a line and a reason. No black boxes.
• Local by default. Nothing leaves the machine except explicit web calls for dependency checks and grounding.
• No telemetry, no analytics, no account.
• One static binary, no runtime dependencies.

Use cases

• Guardrail for agentic coding sessions in the terminal.
• Pre merge review for AI generated pull requests.
• Onboarding a new agent to an unfamiliar codebase.
• Security review of agent applications, especially prompt injection.
• Dependency hygiene for older projects.

Install

One line installer, downloads the prebuilt binary for your platform, linux, macos, windows and Termux Android.

curl -fsSL https://raw.githubusercontent.com/AbduljabbarBXR/heides/main/scripts/install.sh | bash

Pin a version with HEIDES_VERSION.

HEIDES_VERSION=0.6.0 curl -fsSL https://raw.githubusercontent.com/AbduljabbarBXR/heides/main/scripts/install.sh | bash

Or install the heides command from npm (no Rust toolchain needed):

npm install -g heides
heides --help