# HEIDES

> A deterministic harness that gives AI coding agents persistent code graph memory, security taint analysis, and pre-apply patch validation — all local, no cloud required.

HEIDES is an open-source, deterministic agent harness written in Rust that sits beneath AI coding agents to give them senses, memory, and judgment for code. It maps an entire codebase into a persistent SQLite graph before any agent touches anything, then guards every proposed patch against that map — blocking conflicts, signature breaks, and security sinks before a single byte is written to disk. The project is MIT-licensed and runs as a single static binary on Linux, macOS, Windows, and Android Termux with no cloud dependency and no telemetry.

## What It Is

HEIDES describes itself as "the code nervous system" — a substrate beneath AI coding agents rather than a competitor to them. Where agents are powerful but blind (they can generate a perfect function and still break callers they never saw), HEIDES closes that gap at the moment that matters: before the patch is applied. It is not a linter that checks style on the current file; it checks proposed changes against the whole graph of callers and imports, answering questions no other tool answers in that instant.

## Three-Organ Architecture

HEIDES is organized into three deterministic, local, explainable components over one shared spine:

- **The Spine** — Perception and memory. Walks the codebase and builds a compact persistent graph of symbols, files, callers, callees, imports, signatures, doc comments, constants, fields, and enum variants into a SQLite database at `.heides/index.db`. Updated incrementally as files change. No model involved — pure static analysis.
- **Harmony** — Judgment. Runs guard modules against the Spine graph and against proposed patches. Guards include staged apply (blocks conflicts before disk write), edge case detection, interprocedural security taint tracing (SQL, shell, filesystem, prompt injection, Django `mark_safe`), dependency vulnerability checks via OSV, and best-practice rules.
- **Grounding** — Refinement. Takes an objective or plan, checks it against the Spine and the outside world, confirms feasibility, surfaces missing prerequisites, and returns a bounded specification. Can scaffold new projects and index them immediately.

## Language and Platform Coverage

Deep analysis — taint, dataflow, and call graph — targets eight languages: Rust, JavaScript, TypeScript, Python, PHP, Go, Java, and C#. HTML and CSS are first-class web surface files, with inline script bodies parsed as real JavaScript so page code joins the call graph and taint engine. The same static binary runs on desktop, server, CI runners, and Android Termux.

## Connectivity and Agent Integration

HEIDES exposes its full capability through multiple surfaces from one binary:

- **CLI** — Commands include `scan`, `status`, `query`, `describe`, `export`, `check`, `staged`, `plan`, `scaffold`, `deps`, `watch`, `mcp`, and `version`.
- **MCP server** — A Model Context Protocol server over stdio exposing eleven tools (`spine.scan`, `spine.query`, `spine.describe`, `spine.neighbors`, `harmony.check`, `harmony.report`, `harmony.staged`, `grounding.plan`, `grounding.scaffold`, `deps.check`, `web.confirm`). Listed in the official MCP registry as `io.github.AbduljabbarBXR/heides`.
- **Agent systems** — Claude Code, Codex, Cursor, OpenCode, Hermes, and custom builds via MCP.
- **VS Code** — Native MCP support attaches to the same server; a dedicated extension is planned.
- **npm install** — Available as `npm install -g heides` for environments without a Rust toolchain.

## Update: HEIDES 0.14.4

The latest release is v0.14.4 (published September 6, 2026), with the README describing the project as "eight milestones deep" at version 0.13.0 and subsequent patch releases. Notable recent milestones include: 0.9.0 adding HTML/CSS as first-class web surface languages; 0.10.0 widening dependency checks to Go, Python, Maven, and Composer manifests; 0.11.0 adding Django `mark_safe` as a provable XSS taint sink; 0.12.0 adding `harmony.report` as structured JSON output for agent gating; and 0.13.0 fixing a cross-working-directory path resolution bug discovered by running HEIDES against its own codebase. The project ships a comprehensive test gate: lint, build, unit suite, hostility suite (random bytes, code soup, truncated real code), a serial battle suite of 77 end-to-end checks, and a byte-identical determinism test — all run on GitHub Actions for every push.

## Performance and Security Model

The README reports measured performance on an Android phone running Termux: a synthetic workspace of 101,622 lines across 2,400 files scans in 1.6 seconds, indexes in 0.95 MB (~9.6 bytes per line), peaks at 16 MB memory during fresh scan, answers graph queries in 39 ms, and rescans a single changed file in 82 ms. The security model is deterministic by design — every finding carries a file, a line, and a reason with no black boxes. Nothing leaves the machine except explicit web calls for dependency checks and grounding (package names and versions only). No telemetry, no analytics, no account required.

## Features
- Persistent codebase graph via SQLite index (The Spine)
- Staged apply guard — validates patches in memory before disk write
- Interprocedural security taint tracing (SQL, shell, filesystem, prompt injection)
- Django mark_safe XSS taint sink detection
- Edge case detection (null paths, bare except, mutable defaults, unguarded reads)
- OSV vulnerability database dependency checks (Cargo, npm, Go, Python, Maven, Composer)
- MCP server over stdio with 11 tools
- CLI with scan, query, describe, export, check, staged, plan, scaffold, deps, watch commands
- Incremental index updates — only changed files are reparsed
- FTS5 full-text search over names, signatures, and docs
- HTML and CSS as first-class web surface languages
- Workspace manifest (describe) and full map export
- Grounding — plan feasibility check and new project scaffolding
- Watch mode with live severity deltas
- harmony.report structured JSON output for agent gating
- Single static binary, no runtime dependencies
- Runs on Linux, macOS, Windows, Android Termux
- Model-agnostic and agent-agnostic design
- No telemetry, no cloud account required
- npm install support (no Rust toolchain needed)

## Integrations
Claude Code, Cursor, OpenAI Codex, OpenCode, Hermes, VS Code (native MCP), MCP registry (io.github.AbduljabbarBXR/heides), OSV vulnerability database, npm registry, PyPI, Go proxy, Maven Central, Packagist, Android Termux, GitHub Actions

## Platforms
CLI, API, WINDOWS, MACOS, LINUX, ANDROID, VSC_EXTENSION

## Pricing
Open Source

## Version
0.14.4

## Links
- Website: https://github.com/AbduljabbarBXR/heides
- Documentation: https://github.com/AbduljabbarBXR/heides
- Repository: https://github.com/AbduljabbarBXR/heides
- EveryDev.ai: https://www.everydev.ai/tools/heides