runhmd 🛡️

runhmd makes your coding agent's work pass a test it didn't write — and proves that test can fail — before the push lands.

hmd is the one CLI; Heimdall is the engine underneath (NAMING.md). A Claude Code plugin: one prompt in, a gated, receipted change out. The gate is a plain git pre-push hook, so it holds in any repo and also gates Cursor CLI. Your agent's own tests are a claim; the oracle it wires is external, and is first shown to go red on a planted defect before its green is trusted.

Install — pinned to a tag and sha256-checked; if the digest fails, nothing runs (what it writes to your machine · what leaves it):

curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/v2.4.9/install.sh -o heimdall-install.sh \
  && echo "98ecc11bd6af7412692a2826d6c35be174a737b748010fce7d98a6b95ecf4934  heimdall-install.sh" | shasum -a 256 -c - \
  && bash heimdall-install.sh

Then attack a planted bug (the installer clones this repo to ~/.heimdall; hmd attack asks for consent before it runs anything):

hmd attack ~/.heimdall/fixtures/attack/buggy-webhook

Real output from this tree (hmd attack fixtures/attack/buggy-webhook --card --yes):

╭──────────────────────────────────────╮
│ 🛡 runhmd attack                     │
│                                      │
│ VERDICT: DENIED                      │
│                                      │
│ 23 attacks · 17 survived · 6 killed  │
│                                      │
│ ✗ duplicate settlement (webhook+retry│
│   within 50ms)                       │
│                                      │
│ Cost: $0.00 · Time: 0.5s             │
╰──────────────────────────────────────╯

What hmd attack does

hmd attack <path> asks "can I break this?" and answers PROVEN or DENIED, with a counterexample.

• Target: a directory that declares its attack surface in runhmd.attack.json, or a single .mjs module. A directory that declares nothing exits 2: a verdict over nothing would be a false green. --diff and PR URLs are not supported in this build.
• Engine: deterministic and offline: no model, no network, $0.00. The target runs in an ephemeral temp dir, in a scrubbed environment.
• Output: the card above; --json prints the canonical runhmd.verdict/1 document; --out DIR writes the evidence.
• Exit codes: 0 PROVEN · 1 DENIED · 2 usage/config · 3 consent required (non-TTY without --yes) · 4 budget cap · 5 infrastructure.
• Receipts: --receipt issues a signed runhmd.receipt/1, stored locally and checked with hmd receipt verify. The hosted runhmd.dev service is not built yet (docs/RECEIPTS.md).

hmd demo is dry by default: it scaffolds a full-stack task into ./heimdall-demo-app and prints the next step; it executes nothing until you add --run.

Install

Three paths, each labelled with what it does to your machine. The one-liner above is path 1 and carries the highest risk: a script fetched over the network, run with your privileges, with the sha256 check as the only thing between you and those bytes. Path 2 is npx runheimdall (the same script, same digest, same privileges) and path 3 is a Docker sandbox built from your own clone. Full text: docs/INSTALL.md.

Pinned to the v2.4.9 tag and checked against the sha256 of that tag's install.sh. A signature is stronger than a digest copied from this page; every release signs install.sh with minisign (SIGNING.md):

curl -fsSL -O https://github.com/randomittin/heimdall/releases/download/v2.4.9/install.sh.minisig
minisign -Vp release/heimdall-signing.pub -m heimdall-install.sh -x install.sh.minisig

What the installer writes outside the repo (measured from a real run against a throwaway $HOME; no sudo, idempotent, hmd uninstall reverses all of it):

• ~/.heimdall/, ~/.local/bin/hmd and ~/.local/bin/heimdall: a full clone of this repo, and symlinks into it.
• ~/.claude/settings.json: a statusLine and subagentStatusLine, and the plugin under enabledPlugins / extraKnownMarketplaces (honors $CLAUDE_CONFIG_DIR; never clobbers a statusLine you set).
• ~/.zshrc / ~/.bashrc / ~/.profile: one appended export PATH=… line, only when ~/.local/bin is not already on PATH.
• macOS only: a nightly 03:00 LaunchAgent, ~/Library/LaunchAgents/com.heimdall.dream.plist (opt out with HEIMDALL_NO_DREAM_SCHEDULE=1).
• ~/.heimdall/team.json: an auto-minted solo team secret, a bearer capability: treat it like a credential.

A default module is a local proxy that can read your prompts. Headroom is default_included: true, but nothing installs it for you: until you run hmd modules add headroom, hmd modules status headroom reports NOT ATTEMPTED, and that command is a remote code install with no digest verified. Disclosure in full: docs/INSTALL.md and SECURITY.md.

Check the proof yourself

No trust required (~1 min, network-free after the clone):

git clone https://github.com/randomittin/heimdall && cd heimdall
bin/falsify exchange-lob --assert-score 1.0   # every mutant must turn the gate RED, or exit non-zero
bin/falsify emulator-gb  --assert-score 1.0

Real output from this tree (2026-09-19), last lines of each run — a survived mutant would print REJECTED and fail the assert:

SCORE: 6/6 = 1.0000 (golden passing) (incl. 2 guard, gate-invoked)
ASSERT PASS: score 1.0000 >= target 1.0 (golden passed, no mutant survived)

SCORE: 3/3 = 1.0000 (golden passing)
ASSERT PASS: score 1.0000 >= target 1.0 (golden passed, no mutant survived)

The ❌ rows are kept in view: evals/flagship/STATUS.md. The suite counts and how to reproduce them: docs/ARCHITECTURE.md.

Your code stays yours

Network posture is default-ON. Team presence and the cloud features reach the control plane as soon as you use them: a signed heartbeat carrying your handle, verdict, and current filename — scoped to your team, never your code or file contents. That is a feature, and it is on until you switch it off. hmd presence sever gives zero egress. Field-by-field contract: DATA.md. The precisely scoped claims are below.

Gates run 100% locally. Your code never leaves your machine unless you pair a phone with hmd app connect.

Team presence is a feature you can see and switch off: it sends {handle, verdict, current filename} — never code, never file contents — to your team's endpoint. hmd presence off makes you invisible; hmd presence on --no-files hides filenames.

Telemetry is specified, minimal, and yours to kill: DATA.md documents every field. hmd telemetry off. hmd telemetry purge deletes the local spool — nothing is transmitted in this release.

Auto-update checks GitHub Releases for new signed versions. HEIMDALL_NO_AUTOUPDATE=1 (or ~/.heimdall/no-autoupdate) disables it.

rr sends on purpose, and only when you run it: your BYO Claude credential (write-only), your GitHub App installation id, and the literal task text you typed — because that text is the job. It never uploads your working tree; the worker clones your repo from GitHub.

The phone companion is on by default for pairing (a session start in any repo registers a six-minute code with the relay, and nothing of your session is sent until a phone pairs; HMD_PAIR_WINDOW=0 turns that off for the machine, and hmd app disconnect or hmd app connect --no-code for one repo): once a phone is paired, your session state, and any diff you open on the phone, travel end-to-end sealed through a relay that sees only ciphertext; push notifications send short scrubbed text to Expo (HMD_PUSH=0 turns them off); pairing by code sends your gh auth token to the relay once for each code registered for a phone to claim (a session start of a repo with no phone paired, hmd app connect, or hmd app add-device), not on a timer and never while gh is signed out (--no-code pairs by QR instead and sends no token).

Full data contract and every field collected: DATA.md.

Get a bot PR on your repo

rr is the same gate, run in the cloud: a bot that fixes your GitHub issues and opens a PR whose fix has already passed a check the agent never wrote. The bot opens it on a heimdall/* branch as a scoped GitHub App — never as you, never on main, and it never self-merges. A human always gates the merge: test/no-auto-merge.test.sh fails if any shipped code path merges, pushes or deploys without a classified human trigger. Agent instructions count as code paths: the maintainer guide and the incident responder prepare a release or a fix and stop for the operator to run it, and the gate fails if that wording regresses, so it accepts no known gaps there. On every run it prints what it does accept: the human-run executables (for example hmd land and the release and deploy scripts) whose merge, push or deploy step has no in-code confirmation, because a human typing the command is the trigger, and it checks that no unattended surface names them. Setup, the isolation oracle and the bring-up notes: docs/ARCHITECTURE.md.

Running on your own work

heimdall --auto "<task>" runs Claude Code's auto permission mode (a background safety classifier). With no flag, heimdall launches Claude Code with --dangerously-skip-permissions (full autonomy): pass --auto first for the safer opt-in. More: docs/ARCHITECTURE.md.

Docs

Install and its disclosure · Architecture and capabilities · Naming · Parked · Receipts · Data contract · Security · Signing · Changelog · Contributing

Teach it a framework with a stack pack, or add a falsifiable external gate for a new domain with an oracle pack. A verification system that can't show you its own failures can't be trusted with yours.

License

MIT