Assurance

assurance

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

Quick start · Co-change · Use cases · Commands · After every turn · Workflow · 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 or Codex:

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

pip 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.

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.

In use

The plugin figures are Anthropic's, from the Claude plugin directory. The download figures are PyPI's, via pypistats.org. This tool has no server, no account and no telemetry of its own.

The Claude Code plugin, over 30 days

PyPI downloads, all time

Read 2026-11-12 05:36 UTC. PyPI data complete through 2026-11-11.

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:

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

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 it

uvx assurance