@codacy/verity-cli

CLI for Verity — a compounding quality system for AI-generated code.

Install

npm install -g @codacy/verity-cli
cd your-project
verity init

verity init is the whole setup. It asks two things, and every other choice is a default that it states in one line:

┌  Verity · acme/payments
◇  Looked at your repository
◇  Verity reviews every turn, every commit and every push
│  To change it, run verity config moments, or just ask Claude.
◇  Hooks here: this project's .claude/settings.json
◇  Signed in as [email protected]                         ← question 1
◇  Profile sent · no source code                        ← question 2
◇  6 rules for this repository · from 500 commits and 2 docs · 14s
◇  Standard v1 saved
└  Ready in 41s.

1. Sign in. Enter opens GitHub's device page in your browser with the code already on your clipboard. If the Verity GitHub App cannot see the repository, init opens the install page and waits for it. Press s to skip: then only the local security scan runs, because AI review needs sign-in.
2. Send a repo profile? Only asked when you are signed in and the repository has no Standard yet. The profile holds languages, frameworks and dependency names, folder names, commit subjects with the paths they changed, and CLAUDE.md and AGENTS.md without their code blocks. This step sends no source code, diffs or author names, and Verity does not store the profile. Read it first: init writes it to .verity/repo-profile.json, and v shows it. The service writes review rules for this repository from it. Later, each review sends the code that changed.

When it ends, start a new Claude Code session: Claude Code reads hooks when a session starts. Under the plugin, Verity reviews from your next turn.

Where the Standard comes from

The catalogue Standard is a lookup, not a guess: languages and frameworks are counted and read from your manifests. Add project rules to it later with verity standard generate, or edit .verity/standard.yaml and run verity standard push.

Defaults, and how to change them

A re-run keeps what you chose before: the recorded moments, a kept Standard, and anything you set with verity config.

Press Ctrl-C at any point: every step can run again, so nothing is left half-written. verity setup is an alias for the same command. Run verity doctor any time to see prerequisites, the hook wiring, and what is still missing.

What init reports

Once you are signed in, init sends one small event per step to the Verity service, so that we can see where setup stops. Each event holds the step, how it ended (for the profile step: sent, declined or not asked), and the time since init started. A random id links the steps of one run, and the events are linked to your account. Init sends no repository name, no paths and no machine id.

Before you sign in, nothing is sent. The steps wait in ~/.verity/init-trace.json and go with your next signed-in run. A run that is never followed by a sign-in is never sent, and its entry is dropped after 30 days. Set DO_NOT_TRACK=1 to turn all of this off. It is also off in CI.

Output

Human output goes to stderr; stdout carries only data (--json). The wordmark, the colours and the motion appear only when stderr is a terminal. In CI, in a pipe, or when init runs inside a Claude Code session you get the same results as plain lines: no art, no motion, no escape sequences, and no question that nobody can answer. NO_COLOR and TERM=dumb keep the motion and drop the colour; VERITY_REDUCED_MOTION=1 keeps the colour and drops the motion; VERITY_NO_BROWSER=1 stops sign-in from opening a browser.

Permission denied?

If npm install -g fails with EACCES, your npm global directory needs fixing:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc
npm install -g @codacy/verity-cli

Upgrade

npm install -g @codacy/verity-cli@latest

Existing projects keep working — new compound features (knowledge extraction, graph memory, pre-work injection) activate automatically.

0.32.6: the knowledge graph is no longer committed

.verity/memory/ used to be git-tracked. That put Verity's generated notes into every diff and pull request, so teams ended up reviewing the knowledge base in GitHub as if they had written it. New projects now ignore it — the files stay on disk, and for a signed-in project the service syncs them back into any worktree that is missing them.

If you are not signed in, the graph is local-only. Restoring nodes from the service mirror requires an authenticated run, so an anonymous project's graph lives only in its own working tree: it is not committed, and it is not rebuilt elsewhere. That is a deliberate trade — anonymous runs write nothing durable to a shared store — but it means verity memory untrack on an anonymous project leaves you with one copy, on one machine.

Projects that already commit their graph are not changed. A .gitignore rule cannot remove a file that is already tracked, so the switch is offered rather than imposed:

verity memory untrack   # keeps every file on disk, stages their removal from git
verity memory track     # keep committing it on purpose, and stop being asked

verity doctor reports which way your project is set up.

Coming from GATE.md (@codacy/gate-cli)?

GATE.md is now Verity. One-time switch:

npm rm -g @codacy/gate-cli
npm install -g @codacy/verity-cli
verity init   # per project — moves .gate→.verity, keeps your token, Standard & memory

No re-setup needed: your token, Standard, and run history all carry over.

Quick reference

Skills (Claude Code)

Formal verification (opt-in)

At git push, beside the review, Verity can build a small Lean 4 model of one risky function in the change, search every interleaving of its actions up to a bound, and, when a property breaks, replay the failing trace on the real code in a disposable container. Only a counterexample that reproduces on the real code can block the push; a model's opinion alone never does.

Most pushes get no formal check. The phase runs only when the push touches a function that looks worth it: history says the file has been fixed before, the text shows a risky shape (check-then-act, retries, money, auth, a transaction, a cache), and a cheap ranking call scores it above the bar. A push of docs, tests or plain code stops in under a second with a named reason. Counterexamples can only be replayed for TypeScript, JavaScript and Python; other languages stop before any model is paid for.

For a new project, verity init turns this on and starts the Lean 4 download in the background (≈800 MB, 2.7 GB on disk; verity lean status shows the progress). Until Lean is ready, a push reports formal: skipped (no-toolchain: Lean installing, 63%) and the gate decision does not change. Init does not start the download in CI (unless VERITY_LEAN=1), with VERITY_NO_LEAN=1, with formal off, or with less than 3.75 GB free. A re-run of init never turns formal on.

verity config formal off      # turn it off for this checkout
verity lean install           # the toolchain, if the background download did not run
verity prove auto             # try it by hand on what is ahead of upstream

The service keeps a structured record of each phase (the function, the model's name, each promise's id and the line number or rule it rests on, each counterexample's trace of action names and its verdict) and never the code, the model, the harness or any prose about them. The full account — what gets selected, the five structural rules, what a replay proves, costs and caps, and what the dashboard shows — is at https://verity.md/docs/formal.

How it works

Prompt → inject knowledge → Agent works → verity analyze → reviewer + knowledge → PASS/FAIL
                                              ↓
                                     extract learnings → .verity/memory/ (graph)
                                              ↓
                                     next prompt starts smarter

The quality gate catches problems. The knowledge system prevents them from recurring. Every analysis run teaches the next one.

Requires Node.js 20+.