orunmila — The Diviner

Did your AI coding agent actually do what it said? Orunmila — named after the Yoruba orisha of wisdom and divination — reads the session and tells you the truth.

Agents narrate confidently regardless of what happened underneath. "I added validation and tested it" might mean exactly that, or a stub with a comment and no test ever run. Tool-call logs tell you a file changed; they don't check whether the agent's own account of the change was true.

Orunmila reconciles the agent's story against the evidence. See a live report → — a real rendered session, no install required.

Here is that session at the terminal — one ordinary ask, one honest write, one invented file, one unbacked "tests pass":

$ orunmila report

=== orunmila: session demo1 / turn t1 ===

Claims:
  ✅ verified
     "I added input validation to login.js"
  ❌ phantom - claimed, no evidence
     "wrote a test in login.test.js."
     evidence signals: high-specificity-mismatch (inference, not a verdict)
  🔥 phantom verification - claimed tested/works, no passing run
     "Tests pass."
     evidence signals: no-verification-attempted (inference, not a verdict)

Original ask, checked independently of what was claimed:
  ✅ addressed - "Add input validation to login.js"
  ℹ️  acknowledged as incomplete - "write a test for it."

Summary: 1 verified, 0 partial, 1 phantom, 1 phantom-verification,
         0 unverifiable, 0 silently dropped, 0 undisclosed, 0 untracked writes

100% free, Apache 2.0 licensed, runs entirely on your machine. No telemetry, no account, no API key required for the default mode.

One exception, stated up front because it is a privacy claim. The orunmila CLI itself makes no outbound requests. The HTML report it generates has one tab — 3D Graph — that fetches a 3d-force-graph bundle from unpkg (falling back to jsdelivr) when a viewer opens it. Opening that tab therefore reveals the viewer's IP, and the fact that they opened a report, to a CDN. Every other tab is fully self-contained and works offline. Tracked as P2-8.

One ordinary session. The agent wrote the validation, invented a test file, and said the tests passed. Ranked by severity, worst first.

Every finding becomes a prompt you paste straight back into the agent. It is not a diagnosis you then have to act on — it is the message that makes the agent act.

The two lenses

Orunmila does two different jobs. They install separately, because which one you want is genuinely not predictable — some teams want the record, some want the refusal, and the ones who want both want to switch them on independently.

	The Stain Map	The Closeout Gate
what it does	records + reports	refuses
when	after each turn	before a turn is allowed to end
can it stop the agent?	never	yes — 2 of its 6 laws block
agents	all supported agents	claude-code only
install	orunmila install	orunmila install --with-gate
add to an existing install	—	orunmila install --gate-only
turn off for one session	—	ORUNMILA_LAWS=off
read it	orunmila trail	orunmila laws

orunmila lenses        # the two side by side, and which you have installed right now

The Stain Map is the retrospective lens: it stains everything the agent touched, reconciles each claim against the evidence, and hands you a colour-coded map of where to look. It never refuses anything. Use it when you want to know what your agents are actually doing.

The Closeout Gate is the preventive lens: it runs on the Stop hook and can refuse to let a turn end on a claim the turn's own evidence doesn't support. Use it when you want the agent to fix its own story before it hands work back.

One dependency between them, stated plainly: the gate judges the events the Stain Map records, so the gate needs the Stain Map underneath it. The Stain Map is useful entirely on its own. --gate-only will tell you if you've installed a gate with nothing to judge rather than looking successful and sitting silent.

Quickstart

Two install routes. Both carry both lenses — the route only changes how you get the code, never what you get.

From npm

npm install -g orunmila                  # or use npx and skip the global install
orunmila install --with-gate             # both lenses
orunmila trail                           # the report, after you've worked a session

With npx and nothing installed globally:

npx orunmila install --with-gate
npx orunmila trail

From a git clone

Use this if you want to read the source, change the laws, or contribute. It is the same tool; the commands just run through node bin/orunmila.js instead of the orunmila binary.

git clone https://github.com/kalkudiary-ai/orunmila.git
cd orunmila
node bin/orunmila.js install --with-gate   # run from the project you want to watch
node bin/orunmila.js trail

npm test, npm run lint and npm run accuracy all work from a clone with zero dependencies installed — the runtime has none, and the dev tooling is only eslint, prettier and c8.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗