A cloud bot that fixes your GitHub issues and opens a proven PR. You review, you merge.
Every PR ships the runnable evidence that the fix passes. 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.
Once you've installed the Heimdall Maintainer GitHub App on your repo and run claude setup-token, it's two commands:
rr connect # registers your App install + captures your Claude cred
rr "fix the flaky test in payments and open a PR"What happens: rr signs your task with your own Ed25519 key and enqueues it. A gated worker clones your repo with your team's Claude subscription and your GitHub App installation, runs the issue-resolution loop until the fix passes the gates, and opens a heimdall/* PR on your repo. You review it. You merge it.
Nothing to paste — no token, no URL. The public control plane is baked in and enrollment is automatic: your first signed call registers this device on first use. Just rr connect and go. (Running your own deployment, or need to re-gate enrollment behind a bootstrap token? That's an operator concern — see OPERATORS.md.)
- Tenant isolation is a falsifiable oracle, not a promise. Every cross-tenant attack — IDOR by repo slug, cred read across teams, queue drain, installation-id swap, signed-request replay — has a named invariant and a red-line mutant test. Drop any gate and
test/heimdall-cp-authz-gate.test.shgoes red; the keystone suite passes only when every mutant is caught. Full invariant + attack matrix:docs/specs/2026-07-03-rr-isolation-invariants.md. - BYOC — no shared keys. You pay your own Claude tokens; your credential lands in your own per-team Secret Manager secret and is injected env-only into your job — never logged, never echoed, never readable by another tenant.
- Least-privilege bot. The App holds exactly Contents + Issues + Pull requests — no Administration, no Actions/Workflows, no merge capability. It can open a PR; it cannot touch branch protection or push to
main. - Honest bring-up. This loop was hardened over a live multi-tenant bring-up that shook out a run of production-only failures — Google's GFE rejecting GET-with-a-body, cold-start identity drift, jobs starving under scale-to-zero — each now documented as fixed in
deploy/cloud-run/README.mdand the runbook.
The bot is powered by Heimdall's local engine: a Claude Code plugin that turns one prompt into finished, proven work. Every plan wires an external, falsifiable oracle so the implementation can never grade its own homework, and the merge stays blocked until the work is proven correct. Install it to run the same gates on your own machine.
curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/168646ba9e3ded2b7f1297d0109ac4afc33439d2/install.sh -o heimdall-install.sh \
&& echo "fafe31e30b481882a43ab93aaab742b1e90b0d4bde31498aa8f58f3f23585b33 heimdall-install.sh" | shasum -a 256 -c - \
&& bash heimdall-install.shPinned to the v2.3.8 tag and checked against the sha256 of that tag's install.sh. The &&
chain is load-bearing: if the bytes do not match the digest, shasum -c prints FAILED and
nothing runs — so a tag moved under you, a CDN cache poisoning, or a truncated download stops
the install instead of executing. On a Linux box without shasum, sha256sum -c - takes the same
digest. Re-derive it yourself any time:
curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/168646ba9e3ded2b7f1297d0109ac4afc33439d2/install.sh | shasum -a 256
# fafe31e30b481882a43ab93aaab742b1e90b0d4bde31498aa8f58f3f23585b33No sudo. Idempotent — re-run to upgrade. Reversible:
hmd uninstall # removes everything; nothing else was touchedPrefer to inspect first? Same download, same check — just read it before you run it:
curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/168646ba9e3ded2b7f1297d0109ac4afc33439d2/install.sh -o heimdall-install.sh
echo "fafe31e30b481882a43ab93aaab742b1e90b0d4bde31498aa8f58f3f23585b33 heimdall-install.sh" | shasum -a 256 -c -
less heimdall-install.sh # function-wrapped, no eval, no base64 — what you read is what runs
bash heimdall-install.shSignature (stronger than the digest). A digest you copy from this README only proves the bytes
match what this README says; a signature proves they came from the maintainer's key. Every release
signs install.sh with minisign and publishes install.sh.minisig as a release asset:
curl -fsSL -O https://github.com/randomittin/heimdall/releases/download/v2.3.8/install.sh.minisig
minisign -Vp release/heimdall-signing.pub -m heimdall-install.sh -x install.sh.minisigThe public key ships in this repo at release/heimdall-signing.pub, so that command assumes a
clone. SIGNING.md has the full model — including the bundled pure-python verifier
for machines with no minisign binary, and the fail-closed behavior of the auto-updater.
Prerequisites: Claude Code 1.0+ · Git · jq (brew install jq)
Also on npm: npx runheimdall — same pinned tag, same sha256 check, zero clone required.
Gates run 100% locally. Your code never leaves your machine.
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 is the one thing that 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.
Full data contract and every field collected: DATA.md.
hmd demo --runScaffolds a real full-stack task, builds it, ends with a summary card and a follow-up prompt. Safe to run sight-unseen — hmd demo (without --run) prints the plan and does nothing.
- Catches the silent failures — ordering races, whole-sequence invariants, missing subsystems that pass a naive green suite.
- Falsifiable gates — every gate is proven able to go red before it is trusted green. The corpus of real failure cases replays on every change; a regression that once shipped can never ship twice.
- Proof of correctness, not just generation — the delta Heimdall sells is the receipt that proves the proof can fail. Generalizes: 0.50 median reuse across 8 cold repos.
- Full audit trail —
hmd reportproduces a machine-readable telemetry report of every gate, mutation score, and corpus catch-rate from the last run.
| Capability | Command | Status |
|---|---|---|
| Verification gates (secret-scan, bloat, falsify) | /hmd:verify in Claude · bin/falsify |
Shipped |
| Demo task runner | hmd demo / hmd demo --run |
Shipped |
| Issue-resolution loop | hmd (auto-retries failures against corpus) |
Shipped |
| Telemetry report | hmd report |
Shipped |
| Design match (visual diff vs spec) | hmd designmatch |
Shipped |
| Redum / conformance checker | heimdall-redum · heimdall-check |
Shipped |
| Reuse engine (cold-repo analysis) | bin/lib/reuse_analyzer.py |
Shipped |
| Debloat scanner | heimdall-debloat --report-only |
Shipped |
| Parallel workers | hmd --team N "task" (N tmux panes, independent — no shared state) |
Shipped (no coordination layer) |
| Benchmark suite | heimdall-bench |
Shipped |
Heimdall's status bar is a full-width, four-row watchman HUD. It renders entirely shell-side (zero model, zero context cost) and reads Claude Code's statusLine JSON on stdin. Three surfaces, by how far they spread:
Your sigil — the identity hook. Every Heimdall identity (HAID) gets a unique, deterministic pixel watchman: same identity, same sigil, forever. It anchors the left of the line, prints big on the install card, and shares as a postable block:
python3 sentinels/hmd-sigil.py --seed $HMD_HAID --size large # share/banner render
bash hooks/hmd-banner.sh --share # postable "my watchman" cardThe seed is your HAID by default — automatic, stable, no PII in the art. Works solo on day one, before any teammate shows up.
The team watch wall — the headline, and the moat. When teammates also run hmd in the same repo, the bottom row becomes a live wall of their watchmen and what each agent is doing — gate state colored in, a teammate's cell flashing red the instant their gate denies. Nobody else can render this; it needs Heimdall's coordination substrate. The wall is empty until your team joins, so the feature recruits your team for you.
Presence is opt-in per repo — each running hmd heartbeats <repo>/.heimdall/team/<haid>.json (TTL ~30s; a stale file means the agent left). Names live in the repo's team dir and never leave it; default off for non-team repos. The watchman watches your gates, not your team. At squad scale the wall caps at the ~6 most-recently-active teammates plus a +N more tail so a wide terminal never wraps.
The deny flash — the clip. When a gate blocks, hmd-gate-anim.sh redraws the big watchman inline: a scanning pulse settling to a green sparkle on pass, or three red beats and ✗ BIFRÖST CLOSED on deny. TTY-only — in CI or a pipe it collapses to one clean final frame so logs stay readable.
bash sentinels/hmd-gate-anim.sh deny "oracle/falsify" $HMD_HAIDWiring (settings.json):
{
"statusLine": {"type":"command","command":"bash ${CLAUDE_PLUGIN_ROOT}/hooks/statusline.sh"},
"subagentStatusLine": {"type":"command","command":"bash ${CLAUDE_PLUGIN_ROOT}/sentinels/hmd-subagent-statusline.sh"}
}install.sh wires this for you — it registers both entries into your ~/.claude/settings.json (honoring $CLAUDE_CONFIG_DIR) using the absolute installed path, idempotently and without clobbering a statusLine you set yourself. The ${CLAUDE_PLUGIN_ROOT} form above is the plugin-hook spelling; a user-level statusLine resolves no such variable, so the installer fills in the resolved absolute path — which is why the HUD now reaches every dev, not just whoever hand-wired it in dev setup.
hooks/statusline.sh drives the full-width watchman and falls back to the legacy single line if python3 is missing — it never errors, never blocks. Already a ccstatusline (9.2k★) user? Keep your line and drop the watchman in as a Custom Command widget:
python3 sentinels/hmd-statusline.py --widget # just the watchman + verdict segmentThe sigil ships solo-first (viral-cheap, no team required); the watch wall is the team-gated headline that lights up once presence is wired into your gate hooks.
cd /path/to/your/project
heimdall --auto "build a real-time dashboard with auth and charts"--auto runs a background safety classifier that blocks prompt injection and risky escalation. It is the default. --dangerously-skip-permissions exists but is not the default — only use it in a throwaway sandbox.
Live flagship status: evals/flagship/STATUS.md — the ❌ rows are kept in view. The corpus dip log and golden provenance are at evals/corpus/CORPUS-STATUS.md and evals/oracles/emulator-gb/fixtures/golden/VERIFICATION.md.
A verification system that can't show you its own failures can't be trusted with yours.
- Stack packs (
skills/stacks/) — teach Heimdall a framework's conventions and build commands. - Oracle packs (
evals/oracles/) — add a falsifiable external gate for a new domain.
See CHANGELOG.md for release history.
hmd keeps itself and its host current, in the background, on session start — both are throttled (~24h), detached (never block the session), idempotent, and opt-out:
- Plugin auto-update (
bin/heimdall-autoupdate): checks the installed version vs the latest GitHub release; if newer, re-runs the latest installer in the background (takes effect next launch; never hot-swaps the running session). Off:HEIMDALL_NO_AUTOUPDATE=1or~/.heimdall/no-autoupdate. - Claude Code self-heal (
bin/heimdall-cc-selfheal): on a NATIVE Claude Code install, auto-repairs the "✘ Auto-update failed" class — a stale npm-global@anthropic-ai/claude-codeconflicting with the native updater. It removes ONLY that conflicting package, ensuresautoUpdates:true, and re-runsclaude update. Never touches an npm/brew-managed install, never uninstalls anything else, never touches credentials. Off:HEIMDALL_NO_SELFHEAL=1or~/.heimdall/no-selfheal. Inspect:heimdall-cc-selfheal status.