Concepts
How it works
Every change your agent makes goes through a two-layer review against your Standard — out-of-band, scoped to what the agent actually wrote — and comes back as a verdict the agent has to answer.
The review loop
When your agent finishes a turn (or is about to commit or push — see Moments), Verity runs:
- The hook fires. Claude Code runs
verity analyzewhen the agent stops, in its own process, outside the agent's context window. - The scope is resolved. Verity works out what the agent wrote this turn, what has changed since its last verdict, and what the task's goal is — from its own record of the session, not from a guess at the working tree. See What gets reviewed.
- Layer 1 — deterministic analysis. Trivy runs locally over the changed files, through the Codacy analysis CLI that ships with Verity. It produces reproducible facts: findings with file, line, rule and severity. See Static analysis.
- Layer 2 — independent review. The changed files, those facts, the goal, and the relevant notes from your knowledge base go to the Verity service, where a model that did not write the code judges the change against your Standard.
- A verdict comes back —
PASS,WARNorFAIL— with file-and-line findings, typically in under 30 seconds. - The agent answers it. On a
FAILthe agent reads the findings, fixes them, and the gate re-runs — within limits. On aPASSorWARNwith something worth saying, a short report is relayed to the agent instead.
Why two layers
Deterministic tools are precise but blind to intent; a model is context-aware but cannot be trusted to grade its own work — models prefer their own output and fold under pushback. Verity combines them: Layer 1 grounds the review in reproducible facts, and Layer 2 reasons over those facts with a model that is never the one that wrote the code. A static-analysis hit is taken at face value; a model finding is the reviewer's judgement of that specific instance.
Static analysis: Trivy
Layer 1 is Trivy, and nothing else. It checks what a reviewer cannot see in a diff:
- secrets
- malicious packages
- critical and high vulnerabilities in your dependencies
ESLint and Semgrep no longer run, on new and existing projects alike. The AI review covers the rest. Verity configures Trivy itself, in .verity/static-analysis.json, and no longer reads .codacy/. A change to a dependency file reaches Trivy too: the lockfiles, and requirements*.txt, go.mod, pom.xml and gradle.lockfile.
- Nothing to install. The analyzer,
@codacy/analysis-cli, ships with Verity.verity doctornames the copy Verity runs, and marks a global copynot used. - The first run on a machine downloads Trivy's database, about 1.5 GB on disk.
verity initstarts that download in the background. A review waits for the analyzer at most 45 seconds. After that, it says static analysis did not run for this review, and the download goes on in the background. - Windows: Trivy does not run there, so static analysis is off. The AI review is unchanged.
What gets reviewed
Most bad reviews are not bad judgement — they are the right judgement applied to the wrong code, or measured against the wrong goal. Verity is precise about scope on both axes.
The code your agent authored
Verity reads the full Claude Code session record on your machine — every edit, every command, including work done by subagents and workflows in their own transcripts — and builds an authorship record as it happens. That is what lets it separate what your agent wrote this turn from your own half-finished work in the same dirty tree, from a formatter's sweep, and from a rebase that touched forty files. When evidence is missing, the scope narrows and the run says so; it never widens to the whole tree and blocks hardest where it understands least.
The increment since the last verdict
Verity records the exact bytes it reviewed at each verdict. On the next turn it can tell which files are new work and which are byte-identical to something already judged, so a long session stops re-reading the same code — and a file that was under review is the only thing a finding can be about (see The verdict).
The goal for this task
Intent is checked against the goal of the task you are on — captured when you typed it — not a goal borrowed from earlier in the session, another task, or a teammate. Everything Verity holds is scoped to a person, a line of work and a session, so two terminals, two worktrees or two developers never contaminate each other's review. “Let's go” and “yes” are never treated as the goal, and an action that satisfies a goal (a fetch that found nothing to pull) counts as work.
What is left out, and why it is said out loud
Between the files git reports as changed and the bytes that reach the reviewer sit a number of subtraction stages, and every one of them names what it dropped:
- Verity's own files — its skills,
.codacy/configs, the hook settings,VERITY.md— never enter review, so the gate cannot fail your session over its own installer. - Paths your team excluded in
.verityignore, andexclude_pathsin the Standard (Findings & verdicts covers both). - File types without a reviewer: binaries, images, and the like.
- Budgets — on a stop turn, up to 40 files, 50 KB per file and 190 KB in total; commits and pushes get a much larger budget (Moments).
The result is the coverage line printed on every run: what was reviewed, what was not, and the reason for each. Verity reconciles the two sets every time — if anything is unaccounted for, the run cannot return PASS.
Modes
Not every turn is a code change. Verity classifies each one and reviews it accordingly:
| Mode | When | What the review does |
|---|---|---|
standard | The agent changed code. | The full two-layer review described above. |
plan | The agent produced a plan or design and changed no files. | Reviews the plan as a plan — gaps, risks, alignment with what you asked. Plan feedback is advisory and can never block. A report about finished work is not mistaken for a plan, and a plan you approved is reviewed as approved. |
debug | You reported a bug and the agent is fixing it. | Checks that the fix reaches the root cause without regressions. |
skip | Nothing to review. | A bare acknowledgment (“yes”, “1”) with no code change; a turn where you typed a ! command and nothing else acted; a run within 30 seconds of the last one; a declared housekeeping window. Exits fast and silent. A bare “yes” that did come with code is still reviewed — the skip consults the diff, never just the prompt. |
The transcript is ground truth: when what the agent did contradicts what the prompt suggested, the transcript wins. The mode is recorded with the run and shown in the dashboard, and verity analyze --mode forces one when you need to.
What it checks: three lenses
| Lens | What it covers |
|---|---|
| Security | Seven CWE-mapped patterns: hardcoded secrets (CWE-798), input sanitization (CWE-20), parameterized queries (CWE-89), dependency risk (CWE-1395), unsafe deserialization (CWE-502), access control (CWE-639), config integrity (CWE-15). |
| Quality | Four dimensions — comprehensibility, modularity, type safety, test adequacy — with thresholds calibrated for AI-written code. |
| Intent | Did the change do what was asked? The captured goal, any specs the session actually read, and — at a commit or push — the commit message or PR body are the rubric. |
The lenses, their thresholds, and your own project rules live in the Standard.
The verdict
- FAIL — a critical or high-severity finding in code the agent wrote this turn. Blocks: the agent must answer it.
- WARN — medium-severity findings, an intent gap, or a review that could not be completed. Surfaced, never blocking.
- PASS — meets the Standard, with everything in the change accounted for.
Three rules keep a verdict honest:
- No finding without the bytes. A finding can only block if it is about a file whose bytes were under review in this run. A finding citing a file that was not in the change is downgraded to pre-existing — kept and counted, never dropped, never blocking. What Verity said on a previous run is context for this one, not a fresh finding.
- A block needs a finding in the agent's own scope. An intent mismatch on its own never blocks; it arrives as a pending item and can turn a
PASSinto aWARN. - Every changed path is either reviewed or declared not reviewed, with a reason. If anything is unaccounted for — an unreviewed file type, an oversized file, a truncated budget, an unreachable service — the run returns
WARNand names what it skipped. At a commit or a push, the agent review reads the diff of a file over the size limit, and a finding it proves from that diff can block. The result names each such file it read only in part, or not at all. That never blocks you and never raises a finding's severity; it moves exactly one edge, so a green verdict always means a review that actually happened.
WARN — a review it could not complete is not recorded as one it did. Nothing is uploaded later: the offline record keeps paths and counts, never code.Self-healing, with a limit
On a FAIL, the agent reads the findings and fixes them, and the gate re-runs. Fixing is capped at two attempts per problem — fix-recheck cycles hit diminishing returns after the second round, and unguided self-fixing starts introducing new vulnerabilities past it. Distinct problems each get their own budget, and a hard ceiling of five consecutive blocks in a session backstops everything.
Blocking has to earn it: Verity forces another turn only when there is evidence the turn can help — code was actually reviewed, something moved since the last block, and the same problem has not exhausted its attempts. When it stops forcing turns it does not go quiet: the remaining findings are still rendered, recorded and counted as open, and the verdict is WARN, never a PASS it has not earned. The rest is deferred to you — see Findings & verdicts for how to answer it.
Verity speaks on good turns too
A PASS or WARN with something worth saying returns a short report to the agent through the hook's context channel, so it can act on it in the same session instead of learning about it from a dashboard later. That channel is deliberately narrow, because an advisory that becomes noise is worse than silence:
- At most 5 items and 1,500 characters per turn, and a clean turn with nothing to say says nothing.
- Notes ride a per-episode budget — 1 on a
PASS, 2 on aWARN— that resets when you type, on aFAIL, at a task boundary, or after a 30-minute lull. A long-running autonomous agent gets one note per task, not one per turn. - An item already raised is not raised again. Reviewers rephrase, so repeats are matched on meaning rather than wording — an item your agent has already answered stops being pushed at it.
- It is framed as a report to relay, not an instruction, so your agent tells you rather than obeying it.
What Verity remembers between turns
The gate keeps a small working memory for the session — outside your repository, in ~/.verity/sessions/ — carrying the goal you stated four turns ago, the findings still open, and what it has already reviewed. Two rules stop it from confidently recalling things that are no longer true:
- Every carried finding is re-anchored against the current code before it can be restated — within a few lines of where it was, or it is dropped. A finding you fixed does not come back on faith.
- Relevance decays on repository movement, not the clock. A week on an untouched branch is still one line of work; a session that jumped across fourteen branches is not.
Working memory dies with the session. What is worth keeping is written to the project knowledge base at that point; the rest is deleted.
Where it runs
- After every agent turn — the stop hook. On by default.
- Before a commit or push — a change is reviewed and must pass before it lands. Both on by default. See Moments.
- On demand —
/verity-analyzein Claude Code reviews specific files, a directory, or a sample of the whole repository, with no iteration limit;verity review --filesdoes the same from a shell, advisory only. - In a worktree —
.verity/lives in the main checkout, and the hooks find it from any linked worktree, including Claude Code's own.claude/worktrees/. - Offline or signed out — Layer 1 only, nothing recorded, nothing blocked.
The hooks it installs
verity init wires these into .claude/settings.json, with all three review moments on. verity config moments changes the selection later. Only the review moments can gate anything; the rest are local, fire-and-forget context:
| Claude Code hook | Verity command | What it does |
|---|---|---|
SessionStart | verity baseline capture | Photographs the working tree, so pre-existing changes are never blamed on your agent. |
UserPromptSubmit | verity intent capture | Records what you asked for — the goal intent is graded against — and injects the relevant knowledge-base notes before the agent starts. |
Stop | verity analyze | The review after every turn. |
PreToolUse (Bash) | verity guard --on commit,push | The commit and push gates, when enabled. |
PostCompact | verity compact | Re-states still-open findings after Claude Code compacts the conversation. |
SessionEnd | verity session end | Closes the session cleanly, so a /clear mid-task does not lose continuity, and writes the session digest. |
See what is wired at any time with verity hooks check; verity status lists the active moments.