heimdall
starsforks
How to install heimdall?
randomittin/heimdall
$git clone https://github.com/randomittin/heimdallVerification gates for AI coding agents — nothing ships unproven. Falsifiable oracle gates, team wall, receipts. Works with Claude Code today; Cursor, Codex, Gemini CLI & every git repo next.
README.md
| 1 | # Heimdall 🛡️ |
| 2 | |
| 3 | **A cloud bot that fixes your GitHub issues and opens a proven PR. You review, you merge.** |
| 4 | |
| 5 | 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. |
| 6 | |
| 7 | [](https://code.claude.com) |
| 8 | [](LICENSE) |
| 9 | [](CHANGELOG.md) |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## Get a bot PR on your repo |
| 14 | |
| 15 | Once you've installed the Heimdall Maintainer GitHub App on your repo and run `claude setup-token`, it's two commands: |
| 16 | |
| 17 | ```bash |
| 18 | rr connect # registers your App install + captures your Claude cred |
| 19 | rr "fix the flaky test in payments and open a PR" |
| 20 | ``` |
| 21 | |
| 22 | **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. |
| 23 | |
| 24 | **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`](OPERATORS.md).) |
| 25 | |
| 26 | ### Why it's safe to point at your repo |
| 27 | |
| 28 | - **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.sh`](test/heimdall-cp-authz-gate.test.sh) goes red; the keystone suite passes **only** when every mutant is caught. Full invariant + attack matrix: [`docs/specs/2026-07-03-rr-isolation-invariants.md`](docs/specs/2026-07-03-rr-isolation-invariants.md). |
| 29 | - **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. |
| 30 | - **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`. |
| 31 | - **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.md`](deploy/cloud-run/README.md) and the runbook. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## Under the hood — the verification orchestrator |
| 36 | |
| 37 | 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. |
| 38 | |
| 39 | ## Install |
| 40 | |
| 41 | ```bash |
| 42 | curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/9b8a01da690fc64ecb059268866c3fec3d534018/install.sh | bash |
| 43 | ``` |
| 44 | |
| 45 | No sudo. No telemetry. Idempotent — re-run to upgrade. Reversible: |
| 46 | |
| 47 | ```bash |
| 48 | hmd uninstall # removes everything; nothing else was touched |
| 49 | ``` |
| 50 | |
| 51 | **Prefer to inspect first?** |
| 52 | |
| 53 | ```bash |
| 54 | curl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/9b8a01da690fc64ecb059268866c3fec3d534018/install.sh -o install.sh |
| 55 | less install.sh # function-wrapped, no eval, no base64 — what you read is what runs |
| 56 | bash install.sh |
| 57 | ``` |
| 58 | |
| 59 | **Prerequisites:** Claude Code 1.0+ · Git · `jq` (`brew install jq`) |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## First run |
| 64 | |
| 65 | ```bash |
| 66 | hmd demo --run |
| 67 | ``` |
| 68 | |
| 69 | Scaffolds 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. |
| 70 | |
| 71 | --- |
| 72 | |
| 73 | ## Why Heimdall |
| 74 | |
| 75 | - **Catches the silent failures** — ordering races, whole-sequence invariants, missing subsystems that pass a naive green suite. |
| 76 | - **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. |
| 77 | - **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.](https://runheimdall.dev/proof) |
| 78 | - **Full audit trail** — `hmd report` produces a machine-readable telemetry report of every gate, mutation score, and corpus catch-rate from t |
People who liked this also viewed
6 picksType
- fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!MCP ServersNov 2025
- lean-lsp-mcpLean Theorem Prover MCPMCP ServersJul 2026
- rulesyncA Utility CLI for AI Coding AgentsMCP ServersJul 2026
- FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.MCP ServersJul 2026
- repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.MCP ServersJul 2026
- mcp-serverMCP server for AI-assisted development of CAP applicationsMCP ServersJul 2026
