{"id":50907000,"url":"https://github.com/randomittin/heimdall","last_synced_at":"2026-07-11T05:00:16.736Z","repository":{"id":349523606,"uuid":"1202700430","full_name":"randomittin/heimdall","owner":"randomittin","description":"Autonomous Claude Code agent — 14 specialized agents, 10-parallel execution, project-specific skill learning, mechanical checkpointing, wave-based planning with acceptance gates, caveman ultra (~75% token savings). One prompt → finished project.","archived":false,"fork":false,"pushed_at":"2026-07-01T14:33:12.000Z","size":8361,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T16:24:42.611Z","etag":null,"topics":["agent-orchestration","ai-agent","ai-coding","ai-orchestration","anthropic","automation","autonomous-agent","claude-agent","claude-ai","claude-code","claude-plugin","claude-skill","cli","coding-assistant","developer-tools","devtools","llm-agent","llm-framework","llm-tools","multi-agent"],"latest_commit_sha":null,"homepage":"https://github.com/randomittin/superx#readme","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/randomittin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T09:57:34.000Z","updated_at":"2026-07-01T14:33:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/randomittin/heimdall","commit_stats":null,"previous_names":["randomittin/superx","randomittin/heimdall"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/randomittin/heimdall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fheimdall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fheimdall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fheimdall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fheimdall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/randomittin","download_url":"https://codeload.github.com/randomittin/heimdall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fheimdall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35351426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","ai-agent","ai-coding","ai-orchestration","anthropic","automation","autonomous-agent","claude-agent","claude-ai","claude-code","claude-plugin","claude-skill","cli","coding-assistant","developer-tools","devtools","llm-agent","llm-framework","llm-tools","multi-agent"],"created_at":"2026-06-16T06:03:22.278Z","updated_at":"2026-07-11T05:00:16.713Z","avatar_url":"https://github.com/randomittin.png","language":"Shell","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# Heimdall 🛡️\n\n**A cloud bot that fixes your GitHub issues and opens a proven PR. You review, you merge.**\n\nEvery 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.\n\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-e056a0?style=flat-square)](https://code.claude.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-9b59b6?style=flat-square)](LICENSE)\n[![Version](https://img.shields.io/badge/version-2.0.12-00d4ff?style=flat-square)](CHANGELOG.md)\n\n---\n\n## Get a bot PR on your repo\n\nOnce you've installed the Heimdall Maintainer GitHub App on your repo and run `claude setup-token`, it's two commands:\n\n```bash\nrr connect                                    # registers your App install + captures your Claude cred\nrr \"fix the flaky test in payments and open a PR\"\n```\n\n**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.\n\n**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).)\n\n### Why it's safe to point at your repo\n\n- **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).\n- **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.\n- **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`.\n- **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.\n\n---\n\n## Under the hood — the verification orchestrator\n\nThe 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.\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/v2.0.12/install.sh | bash\n```\n\nNo sudo. No telemetry. Idempotent — re-run to upgrade. Reversible:\n\n```bash\nhmd uninstall    # removes everything; nothing else was touched\n```\n\n**Prefer to inspect first?**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/randomittin/heimdall/v2.0.12/install.sh -o install.sh\nless install.sh  # function-wrapped, no eval, no base64 — what you read is what runs\nbash install.sh\n```\n\n**Prerequisites:** Claude Code 1.0+ · Git · `jq` (`brew install jq`)\n\n---\n\n## First run\n\n```bash\nhmd demo --run\n```\n\nScaffolds 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.\n\n---\n\n## Why Heimdall\n\n- **Catches the silent failures** — ordering races, whole-sequence invariants, missing subsystems that pass a naive green suite.\n- **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.\n- **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)\n- **Full audit trail** — `hmd report` produces a machine-readable telemetry report of every gate, mutation score, and corpus catch-rate from the last run.\n\n---\n\n## What's inside\n\n| Capability | Command | Status |\n|---|---|---|\n| Verification gates (secret-scan, bloat, falsify) | `/hmd:verify` in Claude · `bin/falsify` | Shipped |\n| Demo task runner | `hmd demo` / `hmd demo --run` | Shipped |\n| Issue-resolution loop | `hmd` (auto-retries failures against corpus) | Shipped |\n| Telemetry report | `hmd report` | Shipped |\n| Design match (visual diff vs spec) | `hmd designmatch` | Shipped |\n| Redum / conformance checker | `heimdall-redum` · `heimdall-check` | Shipped |\n| Reuse engine (cold-repo analysis) | `bin/lib/reuse_analyzer.py` | Shipped |\n| Debloat scanner | `heimdall-debloat --report-only` | Shipped |\n| Parallel workers | `hmd --team N \"task\"` (N tmux panes, independent — no shared state) | Shipped (no coordination layer) |\n| Benchmark suite | `heimdall-bench` | Shipped |\n\n---\n\n## Viral statusline — watchman, team wall, gate animation\n\nHeimdall'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:\n\n**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:\n\n```bash\npython3 sentinels/hmd-sigil.py --seed $HMD_HAID --size large   # share/banner render\nbash hooks/hmd-banner.sh --share                               # postable \"my watchman\" card\n```\n\nThe seed is your **HAID by default** — automatic, stable, no PII in the art. Works solo on day one, before any teammate shows up.\n\n**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.\n\nPresence is **opt-in per repo** — each running `hmd` heartbeats `\u003crepo\u003e/.heimdall/team/\u003chaid\u003e.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.\n\n**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.\n\n```bash\nbash sentinels/hmd-gate-anim.sh deny \"oracle/falsify\" $HMD_HAID\n```\n\n**Wiring** (`settings.json`):\n\n```json\n{\n  \"statusLine\":         {\"type\":\"command\",\"command\":\"bash ${CLAUDE_PLUGIN_ROOT}/hooks/statusline.sh\"},\n  \"subagentStatusLine\": {\"type\":\"command\",\"command\":\"bash ${CLAUDE_PLUGIN_ROOT}/sentinels/hmd-subagent-statusline.sh\"}\n}\n```\n\n`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.\n\n`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:\n\n```bash\npython3 sentinels/hmd-statusline.py --widget   # just the watchman + verdict segment\n```\n\nThe 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.\n\n---\n\n## Running on your own work\n\n```bash\ncd /path/to/your/project\nheimdall --auto \"build a real-time dashboard with auth and charts\"\n```\n\n`--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.\n\n---\n\n## Failures visible on purpose\n\nLive flagship status: [`evals/flagship/STATUS.md`](evals/flagship/STATUS.md) — the ❌ rows are kept in view. The corpus dip log and golden provenance are at [`evals/corpus/CORPUS-STATUS.md`](evals/corpus/CORPUS-STATUS.md) and [`evals/oracles/emulator-gb/fixtures/golden/VERIFICATION.md`](evals/oracles/emulator-gb/fixtures/golden/VERIFICATION.md).\n\nA verification system that can't show you its own failures can't be trusted with yours.\n\n---\n\n## Contributing\n\n- **Stack packs** ([`skills/stacks/`](skills/stacks/)) — teach Heimdall a framework's conventions and build commands.\n- **Oracle packs** ([`evals/oracles/`](evals/oracles/)) — add a falsifiable external gate for a new domain.\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n## Self-maintenance (auto-update + self-heal)\n\nhmd keeps itself and its host current, in the background, on session start — both are\nthrottled (~24h), detached (never block the session), idempotent, and opt-out:\n\n- **Plugin auto-update** (`bin/heimdall-autoupdate`): checks the installed version vs the\n  latest GitHub release; if newer, re-runs the latest installer in the background (takes\n  effect next launch; never hot-swaps the running session). Off: `HEIMDALL_NO_AUTOUPDATE=1`\n  or `~/.heimdall/no-autoupdate`.\n- **Claude Code self-heal** (`bin/heimdall-cc-selfheal`): on a NATIVE Claude Code install,\n  auto-repairs the \"✘ Auto-update failed\" class — a stale npm-global `@anthropic-ai/claude-code`\n  conflicting with the native updater. It removes ONLY that conflicting package, ensures\n  `autoUpdates:true`, and re-runs `claude update`. Never touches an npm/brew-managed install,\n  never uninstalls anything else, never touches credentials. Off: `HEIMDALL_NO_SELFHEAL=1`\n  or `~/.heimdall/no-selfheal`. Inspect: `heimdall-cc-selfheal status`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandomittin%2Fheimdall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frandomittin%2Fheimdall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandomittin%2Fheimdall/lists"}