Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/arihantdeva/heimdall/agents-mdgit clone --depth 1 https://github.com/ArihantDeva/heimdallWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.03467 | $0.03467 |
| Opus 5 | $0.01733 | $0.01733 |
| Sonnet 5 | $0.00693 | $0.00693 |
| Haiku 4.5 | $0.00347 | $0.00347 |
Grade A, and why
heimdall AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 115 lines — stays where its author put it; the contents beside it link to each section on GitHub.
AGENTS.md — Heimdall (working guide for AI agents)
Purpose (one line)
Heimdall is a trust-verified, self-healing knowledge layer for AI coding agents: it watches what an agent does, keeps a semantic-memory graph fresh across every project, and labels every search hit with a trust verdict (STRONG / WEAK / STALE) so an agent never acts on a dead path or a hallucinated match. It is the code behind the "kb_search before implementing" hard gate and the ~/knowledge-base/Graft machinery the harness rules reference.
The vendor repo lives at /Users/arihantdeva/Repos/heimdall; live runtime state lives OUTSIDE the repo under ~/.heimdall/ (journal, lock, hint queue, config) and ~/.graft/ (backend daemon + its sqlite DB), plus the ~/knowledge-base/ TSV/telemetry/stale logs. The repo is the engine; the home-dir files are the data.
Structure map
| Path | Role |
|---|---|
bin/heimdall.js |
npm CLI entrypoint — thin dispatch to bin/lib/cli-main.mjs |
bin/lib/cli-main.mjs |
CLI dispatch + init/insert/hint/verify/depth implementations |
bin/heimdall-reconciler.mjs |
the single writer daemon: watch + hint ingest + drain + periodic audit |
bin/lib/journal.mjs |
authoritative index: sqlite (node:sqlite) — paths, owned nodes/edges, pending edges, dedup queue, generations |
bin/lib/reconcile.mjs |
level-triggered convergence: read disk, make graph match; audit() = drift detector |
bin/lib/extract.mjs |
desired state per file: hash + L0-L3 node/edge extraction, node-id namespacing, tree-sitter bridge |
bin/lib/heimdall_extract.py |
Python bridge: calls graphify per-language extractors directly (never graphify.extract()) |
bin/lib/depth.mjs |
depth ladder (path/file/symbol/graph), capability probe, config, root matching |
bin/lib/lock.mjs |
O_EXCL single-writer lock with stale-PID reclamation |
bin/lib/hints.mjs |
the only channel a non-writer may use: append "look at this path" lines |
bin/lib/sink.mjs |
projection targets: MemorySink (tests) and GraftSink (graft CLI) |
bin/lib/adapters.mjs |
heimdall init --harness X config writers (pi, claude-code, codex, cursor, windsurf) |
bin/kb-search.sh |
ranked search: graft retrieve + verify + graft explore walk |
bin/kb_search_verify.py |
trust verdicts: STRONG/WEAK/STALE/REBUILT/REMOVED/NOPATH, content-aware, path extraction, stale handling |
bin/kb-stale-scan.py |
full-graph stale sweep: rehome via kb-rehome.sh or log+delete |
bin/kb-rehome.sh |
deterministic rehome of a stale node (bounded basename search) |
bin/kb-health.sh |
heimdall doctor: daemon up, CLI responsive, search smoke, inventory freshness |
bin/kb-rebuild.sh |
full graph rebuild: backup → wipe → parallel restore → re-seed → prune → verify |
bin/seed-graft.sh |
load ~/knowledge-base/.inventory.tsv into Graft (idempotent) |
bin/sync-edits.sh |
one-shot bootstrap: replay Pi session edit logs (write/edit/hashline_edit) as hints |
bin/telemetry.sh |
collect/view/usage — nodes/day, sync age, kb_* tool-call counts |
extensions/kb-tools.ts |
Pi extension: exposes kb_search/kb_insert/kb_sync agent tools |
extensions/kb-autosync.ts |
Pi extension: hook that appends path hints (never writes the graph) |
extensions/kb-orient.ts |
Pi extension: injects prior-work hits into the first user prompt of a session |
extensions/kb-search-guard.ts |
Pi extension: warns after 3 consecutive grep-style actions without kb_search |
extensions/lib/kb-guard-core.mjs |
pure guard state machine (testable without the Pi runtime) |
vendor/graphify/ |
vendored graphify v0.3.17 (MIT) — per-repo code-graph extractors (tree-sitter) |
vendor/graft/ |
vendored Graft source (Apache 2.0) — backend daemon; not prebuilt, build from source |
config/heimdall.yaml.example |
example backend config → copy to ~/.graft/config.yaml |
launchd/com.heimdall.backend.plist.example |
launchd template for graftd |
docs/adapters.md |
what each heimdall init --harness X installs |
docs/heimdall_compare.{dot,png} |
graphify vs Graft vs Heimdall positioning diagram |
types/pi-coding-agent.d.ts |
minimal type stub of the Pi host API so extensions typecheck standalone |
tests/*.test.mjs |
node:test suites (44 tests) |
.pi-subagents/ |
subagent run artifacts (input/output/transcripts/meta) — gitignored, historical record |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 115 lines · 3,467 tokens per session scan A 9409c6904e04
heimdall AGENTS.md is an instructions file published in the GitHub repository ArihantDeva/heimdall (64 stars, last pushed 6d ago), licensed MIT. It adds 3,467 tokens to every session, about $0.0173 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
codesage AGENTS.md
Instructions for iliaal/codesage, covering codesage, build, sanity check before pushing, crate map and search pipeline.
codesage CLAUDE.md
Instructions for iliaal/codesage, a project described as: Code intelligence engine for AI coding agents. Structural graph queries plus semantic search, exposed via CLI and MCP.
repobrain copilot-instructions.md
Copilot instructions for study8677/repobrain, covering github copilot bootstrap instructions and hard rule — query the repobrain hub first.
honcho CLAUDE.md
Claude Code instructions for plastic-labs/honcho, covering claude.md, honcho overview, what is honcho?, core concepts and peer paradigm.
dense-mem AGENTS.md
Instructions for markhuangai/dense-mem, covering dense-mem repository guidance, project context, architecture decision records, current stack and target architecture.
trace-mcp AGENTS.md
Instructions for nikolai-vysotskyi/trace-mcp: IMPORTANT: For ANY code exploration task, ALWAYS use trace-mcp tools first. NEVER use Read/Grep/Glob/Bash(ls,find) for navigating source code.