heides

# HEIDES

![HEIDES, the code nervous system](assets/banner.webp)

## 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

![The Spine maps the codebase into a persistent graph](assets/spine.webp)

Perception and memory. The Spine walks the codebase and builds a compact persistent graph of symbols, files, callers, callees, imports and signatures. The index lives on disk 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 four questions directly.

* Who calls this symbol?
* Who imports this module?
* Where is this symbol defined?
* What does this function call?

### Harmony

![The HEIDES architecture](assets/graph.webp)

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.
* 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

![Grounding refines plans against the spine and the web](assets/grounding.webp)

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, confirms security and best practices, 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

![How HEIDES works, the event driven flow](assets/how-it-works.webp)

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

![How the HEIDES guards run](assets/guards.webp)

* 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.
* 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

![Every shell HEIDES connects to](assets/connectivity.webp)

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

* CLI. Native commands are scan, status, query, check, staged, plan, scaffold, deps, watch and mcp.
* 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 eight 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, and what a function calls.
* harmony.check. Run every guard on the workspace and return findings with evidence.
* 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.

## Compatibility

Model agnostic is the design, not a slogan. HEIDES guards the code, never the model. Whatever drives the agent, frontier API, open weights, local, it speaks MCP or runs the CLI and the same binary gates the same way. The logos below are the front doors, the harness itself has no model dependency at all.

[![Claude](https://img.shields.io/badge/-Claude-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://www.anthropic.com/claude)
[![OpenAI GPT](https://img.shields.io/badge/-OpenAI%20GPT-000000?style=for-the-badge)](https://openai.com)
[![Gemini](https://img.shields.io/badge/-Gemini-886FDF?style=for-the-badge&logo=googlegemini&logoColor=white)](https://gemini.google.com)
[![DeepSeek](https://img.shields.io/badge/-DeepSeek-4D6BFE?style=for-the-badge&logo=deepseek&logoColor=white)](https://deepseek.com)
[![Llama](https://img.shields.io/badge/-Llama-0467DF?style=for-the-badge&logo=meta&logoColor=white)](https://llama.com)
[![Mistral](https://img.shields.io/badge/-Mistral-FA5000?style=for-the-badge&logo=mistralai&logoColor=white)](https://mistral.ai)
[![Qwen](https://img.shields.io/badge/-Qwen-6136F2?style=for-the-badge&logo=qwen&logoColor=white)](https://qwenlm.github.io)
[![Grok](https://img.shields.io/badge/-Grok-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.ai)
[![Ollama](https://img.shields.io/badge/-Ollama-000000?style=for-the-badge&logo=ollama&logoColor=white)](https://ollama.com)
[![OpenRouter](https://img.shields.io/badge/-OpenRouter-8439F4?style=for-the-badge&logo=openrouter&logoColor=white)](https://openrouter.ai)

One static binary with no runtime dependencies runs on every platform HEIDES claims, desktop, server, CI and phone. The Android build runs under Termux on the same filesystem as the desktop builds, byte for byte the same analysis.

[![Linux](https://img.shields.io/badge/-Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)](https://www.kernel.org)
[![macOS](https://img.shields.io/badge/-macOS-000000?style=for-the-badge&logo=apple&logoColor=white)](https://www.apple.com/macos)
[![Windows](https://img.shields.io/badge/-Windows-0078D6?style=for-the-badge)](https://www.microsoft.com/windows)
[![Android](https://img.shields.io/badge/-Android-3DDC84?style=for-the-badge&logo=android&logoColor=black)](https://www.android.com)
[![Termux](https://img.shields.io/badge/-Termux-000000?style=for-the-badge)](https://termux.dev)

Deep analysis, taint, dataflow and the call graph, targets eight languages. Rust, JavaScript, TypeScript, Python, PHP, Go, Java and C#. Every language in the deep set gets the same symbols, signatures, call edges, parameter names and interprocedural taint summaries, so the guarantees do not change when the language does.

[![Rust](https://img.shields.io/badge/-Rust-000000?style=for-the-badge&log