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 · 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.
| where | command |
|---|
| macOS (Homebrew) | brew install uv |
| macOS / Linux | curl -LsSf https://astral.sh/uv/install.sh | sh |
| Windows | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
| Windows (WinGet) | winget install --id=astral-sh.uv -e |
| anywhere with Python | pipx install uv or pip install uv |
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.
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.
| Your work | What it checks for you |
|---|
| Payments and fintech | The tests your money code depends on ran after the last edit, and passed, before anything ships |
| Banking and regulated change | A record per session of what changed and what was tested, and whether the asker is cleared for every owner the change reaches |
| Healthcare and life sciences | Protected paths an agent changed without being asked; what an install will run, before it runs |
| Legal, insurance and documents | Whether a research agent read every document the question needs; missing periods in a folder of reports |
| Platform, DevOps and SRE | Pushes, deploys and migrations over untested code; what a change reaches; limits a session cannot raise |
| Teams building their own agents | Your agent's "done" and its gate's "allow", held against what then happened, from a run record or OTel traces |
prompt ─▶ agent edits ─▶ note ─▶ tests ─▶ suggested review ─▶ push / deploy ─▶ stop and check ─▶ CI gate
Commands
One install, one assurance command.
| Command | What it answers |
|---|
assurance audit | What did the Claude Code or Codex session in this folder, or your own agent's run or trace, do, and what did it skip? |
assurance hook | Run that audit after every Claude Code turn, or stop running it: install, remove, status. |
assurance notices | After each thing the hook said, did the next turn run the test, fix the failure or put the file back? Read from this machine's transcripts; nothing is sent. |
assurance serve | A local endpoint any agent sends its traces or runs to, and any workflow asks for a run's audit. |
assurance coupling | What usually changes with what you just changed, from git history — and which of those you have not touched. No graph, no configuration. |
assurance reach | What does a change to this file reach, by a code graph such as Graphify's, and how far behind the code is that graph? |
assurance clearance | Is the person who asked cleared for every owner their change reaches? |
assurance diff | Did the work cover everything it should have? For example, retrieved docs vs. required docs. |
assurance pin | Did an MCP server quietly change a tool's description after you approved it? |
assurance deps | What will pip install or npm install run on your machine? Read without running it. |
assurance budget | Where did an agent run's budget go, and where did it loop? |
assurance authority | May this task go ahead for the person who asked, without borrowing someone else's access? |
assurance check | Is a folder of dated reports complete, and which periods are missing? |
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:
| Level | When | Who is asked |
|---|
| note | Code changed this turn and nothing has tested it yet | You, once, with the command to run. Claude is not asked anything |
| suggested review | A test failed after the last edit, a protected path changed, or Claude says the tests pass with nothing behind it | You, and Claude: fix it or say why not |
| stop and check | Untested code was pushed, merged, published, deployed, migrated or committed on main | You, and Claude: verify it before anything builds on it |
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.
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.
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.
| Package | What it is |
|---|
assurance-cli | The assurance command: diff, check, pin, drift, init |
assurance-budget | audit for coding-agent sessions, budget for run logs |
assurance-deps | Reads what an install will run, without running it |
assurance-authority | Whether a task may go ahead for the person who asked |
assurance-reach | What a change reaches, by a code graph, and how far behind the code that graph is |
assurance-mcp | The checks as read-only MCP tools, limited to --root |
assurance-core | The pure decision library underneath. No I/O, no model, no dependencies |
Part of I-Ops. Keep your models, agents and orchestration, and put an independent check around them.
Apache-2.0 · Security · Contributing · Releases
