Assurance

assurance

Your AI agent says it's done. Assurance tells you what it didn't check.

Quick start · While you work · Use cases · Commands · Guides · Feedback

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:

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

Not using Claude Code yet? uvx assurance audit --demo shows the report on a bundled sample session.

Don't have uvx? It comes with uv. One line to install it:

Open a new terminal afterwards so uvx is on your PATH. Or skip uv entirely and use pip install assurance, which gives you the same assurance command.

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.jsonl
Claude Code session demo-8f2 — 13 min in /home/you/my-app
10 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.

Run it after every session

Turn on the Stop hook and Claude Code runs the audit each time Claude finishes a turn. 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 it
uvx 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.

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:

| Exit code | Meaning | |:-:|---| | 0 | Checked, found nothing | | 1 | Something to look at, including something it couldn't check | | 2 | Couldn't run |

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, and the run records your own agent writes. 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.

Part of I-Ops. Keep your models, agents and orchestration, and put an independent check around them.

Apache-2.0 · Security · Contributing · Releases