HEIDES

HEIDES

The code nervous system

HEIDES is a deterministic harness that gives AI coding agents what they do not have on their own: a persistent map of the code, warnings derived from that map, and a verdict before a patch lands. The agent suggests. HEIDES decides what is safe.

One binary. No cloud, no model, no account. It runs on a laptop, on a server, in CI, and on a phone running Termux.

heides scan                 # map the codebase once

heides check # run every guard, exit non-zero on a blocker or critical heides staged patch.diff # judge a patch before it lands heides mcp # expose it to any MCP client

check is a gate, not a report. It exits non-zero when it finds a blocker or a critical, so CI fails on a real SQL injection without anyone parsing the output. A clean workspace exits 0. --exit-zero restores the old always zero behaviour, and --exit-threshold=warning makes it stricter.

Every guard is local, and that is the whole design

heides reports only what it can prove from the files it read. Each finding names a file and a line, and the same tree produces the same verdict on a laptop, in a container, and on a phone with the network off. There is no cache to go stale and no registry that can fail.

That used to not be true. heides carried a dependency guard that asked whether a pinned version was a known CVE, and every way of answering it inside the tool was a way of being wrong:

• Over the network, a gate verdict depended on network conditions rather than on the tree. check took 3242 ms with the guard and 117 ms without, on the same five file fixture.
• From a cache, worse. The offline cache expired a clean answer after 24 hours, so a CVE published that morning read as "no known vulnerability" until the entry was re-fetched. Nothing in the output distinguished the two.

A guard that cannot tell *no vulnerability* from *has not heard of it yet* reports false confidence, and false confidence is indistinguishable from a pass. So the guard was removed rather than made opt-in: an opt-in default that is safe is still a slow default, and a cache that is correct is still a cache.

Dependencies, secrets and exposure live in [GRIM](https://pypi.org/project/grim-mcp/), which is public, published, and backed by a continuously updated feed rather than by this repository's cache. heides deps and the deps.* tools still exist and say exactly that, so an agent holding one of those names learns where the answer went instead of concluding the tool is broken.

What heides still proves locally is the part that matters for a change you are about to make:

Every one of those is a fact about your repository rather than about the world, which is why they belong in the same tool and the CVE question does not.

Over MCP

harmony.check and harmony.report return findings with the guard, severity, message, file and line. harmony.report carries security_gate and security_posture so an agent can gate on the verdict without parsing prose, and the coverage receipt travels inside the JSON, because an agent that receives a clean result must be able to see how much was actually inspected without a second call.

One lesson outlived the guard it was written for. An MCP server handles every client in one process, so a setting that changes behaviour must be scoped to the call that asked for it and never set on the process. An earlier version of harmony.check set a process global and never restored it, so one client passing an argument silently changed the security posture of every later request from every client.

Why it exists

An AI agent is powerful and blind. It can write a perfect function and still break three callers it never read, because it has no persistent map of the code. Linters and tests catch that after the change lands, and only on paths that happen to run. The classic failure: an agent changes a signature, the unexercised call sites break, the suite stays green, and production breaks at two in the morning.

HEIDES closes that gap at the moment that matters, before the write. It answers the questions no other tool answers at that instant. Who calls this function? Which imports does this file really use? Does this patch conflict with the graph? Is user input flowing into a SQL string, a shell, or a prompt?

The Spine

HEIDES walks the tree once and builds a persistent graph in one embedded SQLite file: files, symbols with their captured doc comments, call edges, import edges, and two FTS5 tables, one over names and docs, one over literals and comments. Every later question is an index lookup, so an agent asks the graph instead of reading files.

The spine is not a model and not a guess. heides describe reads the whole workspace manifest in one shot, including entrypoints, hubs and doc coverage per language. A function nobody calls in the workspace is not automatically dead code: Express, Flask, Django and Go route registrations are recognised, so a handler stops being reported as an uncalled root.

The cost contract is enforced on every push by the CI scale phase, not by a number frozen into this file: index time linear in files, queries on indexes, bounded memory, and analysis that never needs the network.

Taint

Taint is the part that finds real bugs. Sources are request data and environment reads per language. Flow is tracked block scoped, across function boundaries and across module level code, with a hop cap and silence past it. Sinks include SQL, SSRF, NoSQL, shell, filesystem, prompt, eval and Django's mark_safe.

SSRF and NoSQL use a stricter gate than SQL on purpose. A hardcoded health-check URL and a literal query object inside a request handler are both safe, so those rules require the tainted value to actually reach the sink line rather than merely a source existing somewhere in the handler:

app.get('/health', async (req, res) => {

const id = req.query.id; // a source is in scope here const r = await fetch('https://api.internal/health'); // ...and this must stay silent });

A tainted fetch aimed at a cloud metadata address is reported as credential theft rather than as a generic SSRF, because that is what it is:

user controlled input reaches a cloud metadata fetch sink on this line. source at line 4

The report only claims what it can see. A tainted host passed in through a variable is reported as SSRF, because the address never appears on the line and the tool will not guess where it points.

The rule that matters most is restraint. run, raw, literal and prepare are ambiguous names, so they only count as SQL on a database-ish receiver:

db.run("DELETE FROM users WHERE id = " + id)   // critical SQL finding

run(taskName) // silence, a task runner is not a database

The same applies to a document query, where the method name alone is ambiguous but the receiver is not:

UserModel.find(JSON.parse(req.query.filter))  // critical NoSQL finding

items.find(i => i.id === id) // silence, that is an array method

Both halves have a regression test, so the shortcut cannot come back.

Languages

Taint and indexing are separate, and the table is honest about which is which. Every row below was measured against the released binary, not inferred from the grammar list.

TypeScript was silently unscanned for taint until 0.16.0: the parser mapped .ts to typescript and the rule tables had no typescript rows, so every TypeScript file was skipped without a word. Ruby could not taint at all until this series, for three separate reasons: no rb extension, no source row, and a block detector that understood braces but not def and end. Rust is indexed but not taint scanned, so a shell or SQL sink in Rust code is not reported.

.tsx is parsed with the TSX grammar rather than the plain TypeScript one. The two are not interchangeable: a JSX element opens node kinds that the plain grammar cannot name, and the walk stopped there, so a component file yielded fewer symbols than the same code with the .ts extension. C and C++ are indexed with symbols and call edges, and are not taint scanned: a sprintf into a fixed buffer feeding system produces nothing.

The gate

heides staged is the part an agent loop actually uses. It judges the diff, not the file: signature widening and not just removal, callers and imports the patch breaks, taint the patch introduces, and the project's own tests when it has them. The verdict is structured, so an agent can gate on it without parsing prose, and it exits non-zero with a file and a line for every finding.

Install

One line installer, downloads the prebuilt binary for 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. It takes a bare version, and a leading v is stripped, so both 0.16.0 and v0.16.0 work. The npm installer reads the same variable, so one pin covers both paths.

# any published tag, bare or with a leading v

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

Or install from npm, no Rust toolchain needed:

npm install -g heides

If the binary is missing when you run heides, the launcher downloads it on the spot and says so. This is not a fallback you should ever need: npm 11.16 and newer block dependency lifecycle scripts by default, and on npm 11.17 the --allow-scripts flag aborts the install outright, so the postinstall hook that fetches the binary never runs. Rather than tell you to reinstall, which is the thing that just failed, the launcher runs the same installer the hook would have. The platform table lives in install.js, so there is one copy of it.

Or with cargo:

cargo install heides

Or take a prebuilt binary for your platform from the releases page, or build from source with cargo build --release.

Every channel is on the same version, and a test fails the build if the npm wrapper and the binary ever drift apart.

Quick start

heides scan                       # build the spine index

heides check # every guard, human readable heides query callers send_order # who calls it heides query search refresh # names, docs, literals and comments heides describe # the workspace manifest in one shot heides plan "add a health endpoint" # is this plan grounded in what exists heides staged patch.diff # judge a patch before applying it heides mcp # serve the eleven tools over stdio

A worked example, on a small Express service where two bugs are planted:

$ heides check

0 blocker(s), 3 critical, 0 warning(s), 1 info

[critical] user controlled input reaches a SQL sink ... at src/knexish.js:6 [critical] user controlled input reaches a SQL sink ... at src/knexish.js:7 [c