Assurance

Coding agents finish with "All done — tests pass." Assurance reads what actually happened and tells you, in plain sentences, what was done, what was skipped, and what it could not verify.

Quick start

Run this in any project where you've used Claude Code or Codex:

uvx assurance audit                        # with uv: runs it without installing anythingpip install assurance && assurance audit   # without uv

It reads the newest session either agent left for this folder — nothing to configure, and no flag saying which one you used. Used neither yet? uvx assurance audit --demo shows the report on a bundled sample session.

Here is the real output on a sample session in this repo. The agent was asked to fix a rounding bug in invoice.py "and make sure pytest -q tests/test_invoice.py passes", and ended with "All done — the totals are correct now."

$ assurance audit examples/audit/sample-session.jsonlClaude Code session demo-8f2 — 13 min in /home/you/my-app10 tool calls, 3 failed — Bash 6, Edit 2, Grep 1, Read 1
  Looped: 3 rounds of Bash `pytest -q tests/test_invoice.py` failing the same way, with nothing new read  After the last edit (14:09): no test or check it recognises; 2 unclassified commands ran after it (make lint-fix, python script)  Against the last prompt (14:00, "The invoice totals are off by a cent for EUR. Fix it in inv…"):    invoice.py: changed at 14:04 (src/billing/invoice.py).    pytest -q tests/test_invoice.py: did not run after the last edit to src/billing/rates.py (14:09); it last failed at 14:08, before that.    Only what the last prompt names is checked here; whether the work does what it asks is not.  Not classified: 2 shell commands (make lint-fix, python script), so whether they read, wrote or tested anything is unknown.  Also in the transcript: 1 assistant turn, 1 user turn, 1 bookkeeping record.  Not read: 0 lines.

What "All done" left out:

• ❌ The tests failed three times in a row, the same way each time.
• ❔ No test it recognises ran after the last edit. Two commands did, and it can't vouch for them either way, so it names them. Silence is not a pass.
• ❔ The test the prompt asked for last ran before the last edit, and failed. The file it named was changed. Whether the fix is right is not something it claims to know, and it says so.

What usually changes with what you just changed

The other half of an unfinished change is the file you forgot. assurance coupling reads your git history — no graph, no configuration, no model — and names what travels with the files you touched and that you have not touched this time.

uvx assurance coupling    # in any git repository

Run in this repository with nothing changed, it falls back to the repository as a whole, and the first thing it says is about its own release process:

  plugins/assurance/.claude-plugin/plugin.json    plugins/assurance/scripts/assurance.sh         34 of its 35 commits    4.8x chance    packages/assurance/pyproject.toml              34 of its 35 commits    4.4x chance    packages/assurance/README.md                   35 of its 35 commits    4.0x chance    packages/assurance/CHANGELOG.md                34 of its 35 commits    4.1x chance

The release version lives in those files and they move as one set. Twice in one day the author of this paragraph moved some of them and not the others, and a test caught it both times. The tool had already said so, from history, before either mistake.

Every report ends with the git log command that checks its own first line, so you never have to take its word for it.

Use cases

Where Assurance sits in the work you already do. Each page is short: what goes wrong, where it sits, the lines that set it up.

prompt ─▶ agent edits ─▶ note ─▶ tests ─▶ suggested review ─▶ push / deploy ─▶ stop and check ─▶ CI gate

Commands

One install, one assurance command.

Every command works as a CI gate as it is:

Run it after every turn, if you want that

Everything above is something you run. This is the same audit as a Stop hook, running itself each time Claude finishes a turn, which some people want and some people do not.

Worth knowing before you turn it on: keeping an agent working until a condition holds is something Claude Code ships on its own, with /goal. What that condition is judged against is the difference. /goal's own documentation says its evaluator "doesn't run commands or read files independently" and "can only judge what Claude has already surfaced in the conversation" — so an agent that says the tests passed can satisfy it by saying so. This reads the session's tool records and computes whether a test actually ran after the last edit, from the exit status that was recorded. Neither is better at everything; they answer different questions, and only one of them is unimpressed by a confident sentence.

It speaks only when there is something to say, at one of three levels, named first:

assurance · note: no test or check has passed since the last edit to src/billing/invoice.py (14:04). Run pytest -q tests/test_invoice.py before you commit or push.assurance · suggested review: the last test run after the last edit to src/billing/invoice.py (14:04) failed: pytest -q tests/test_invoice.py (tests/test_invoice.py::test_eur_rounding; 1 failed, 11 passed in 0.33s).assurance · stop and check: pushed at 14:06 with no passing test or check after the last edit to src/billing/invoice.py (14:04).

uvx assurance@latest hook install   # shows the change to ~/.claude/settings.json, asks, then writes ituvx assurance hook remove           # takes it out again; nothing else changes

It knows the test commands of Maven, Gradle, Bazel, Django, Rails, jest, vitest, go, cargo and more, reads your package.json, Makefile and justfile scripts to learn yours, and never counts a run of zero tests as a pass. What it recognises.

Or as a Claude Code plugin: claude plugin marketplace add i-ops-hq/assurance, then claude plugin install assurance@i-ops-hq. It never blocks or fails a session. Everything about pinning, sharing it with a team, Windows and what the plugin runs: the hook guide.

Where it sits in your workflow

flowchart LR    s0(["Prompt"])    s1["AI agent<br/>edits code"]    s2["Agent runs<br/>the tests"]    A["🛡️ Assurance<br/>checks what<br/>really happened"]    s4(["Commit, push,<br/>deploy"])    s0 --> s1 --> s2 --> A --> s4    style A stroke:#dc2626,stroke-width:3px

The red box is Assurance. Everything else is your workflow as it is today: after each turn, Assurance reads what the agent actually did, tells you when something needs a look, and says nothing otherwise. The same check can gate CI.

One fix, step by step:

flowchart LR    s0(["Fix the EUR<br/>rounding"]) --> s1["Edits<br/>invoice.py"] --> A1["🛡️ note<br/>run pytest first"] --> s2["pytest:<br/>1 failed"] --> A2["🛡️ suggested review<br/>fix it"] --> s3["pytest:<br/>12 passed"] --> s4(["Push"])    style A1 stroke:#dc2626,stroke-width:3px    style A2 stroke:#dc2626,stroke-width:3px

Guides

• Run it after every session: the levels in full, pinning, team setup, the plugin, Windows
• Your project's rules: declare your own tests, what must pass, what must not be touched, and limits the agent can't raise
• Your own agent: run records, OpenTelemetry traces, and a local endpoint
• More checks: retrieval coverage, MCP pinning, installs, what a change reaches, MCP tools

What it won't do

• Guess. If it can't establish a number, it says so instead of making one up.
• Call a model or the network. Every result is arithmetic you can check yourself.
• Claim more than it saw. audit reads Claude Code transcripts, Codex rollouts, and the run records your own agent writes. A record shape it does not know is counted as unread, never guessed into a tool call — the report prints that count. Other agents' own logs are next: tell us which one you use.

Tell us where it's wrong

It's early, and the most useful thing you can do is run it on real work.

• 🎯 It gave a wrong or misleading answer. This is the most valuable report there is.
• 🐛 Something broke
• 💡 Support another agent, lockfile or framework
• 🤝 Contribute: pick a good first issue and read CONTRIBUTING.md.

If it's useful to you, a ⭐ helps other people find it.

Packages

pip install assurance gives you all the commands. Each part also installs on its own.