Getting started
Quickstart
Install Verity as a Claude Code plugin or as a global CLI, run one command, and read your first verdict. Under two minutes.
Before you start
- macOS or Windows — Linux is not supported yet. On Windows, git means Git for Windows; see Troubleshooting → Windows.
- Node.js 20+ and git, with a repository whose
originremote is on GitHub. - Claude Code — Verity installs as its skills and hooks.
- A GitHub account — for the optional sign-in that turns on history, memory and the dashboard.
The Codacy analysis CLI (@codacy/analysis-cli) comes with Verity. It runs Trivy, the deterministic layer of every review. You do not install it.
1 · Install Verity
Two ways in. They give you the same gate — the difference is who keeps it up to date and where the wiring lives. The plugin is the shorter path; the global CLI is what you want for CI, where there is no Claude Code to host a plugin.
As a Claude Code plugin
In Claude Code:
/plugin marketplace add codacy/verity/plugin install verity@verityThe plugin carries its own pinned copy of the CLI, and the CLI carries the analyzer. So there is nothing else to install. Claude Code fetches both on install and again on every plugin update. Then, in your project:
/verity:init/verity:init asks the setup questions in the session, then runs verity init with your answers. Under the plugin the skills and hooks come from the plugin itself, so nothing is written to your .claude/ — see Files & configuration.
codacy up to 0.32.1. That name belongs to Codacy's skills marketplace, so it moved to verity in 0.32.2. An older install still runs but will never update again:/plugin uninstall verity@codacy
/plugin marketplace add codacy/verity
/plugin install verity@verityAs a global CLI
From the root of your repository:
npm install -g @codacy/verity-cli && verity initverity init is the whole setup. It asks only what it cannot decide for you, and it prints every other choice as a default. It:
- checks Node.js, git and Claude Code. The analysis CLI comes with Verity, so init installs nothing.
- copies the
/verity-*skills into.claude/skills/, and wires the Claude Code hooks in.claude/settings.json— the review moments plus intent capture, the session baseline, and the compaction and session-end hooks (How it works explains each). - says when Verity reviews: every turn, every commit and every push. It does not ask.
verity config momentschanges it (Moments). - asks you to sign in. Press Enter: your browser opens on GitHub's device page, and the code is already on your clipboard. Press
sto skip (step 2). - asks about cost & usage telemetry, once for the whole machine. It asks only when you are signed in, telemetry is off, and you did not say no before (Token telemetry & cost).
- writes your Standard. If your team already has one on the service, init asks: use it (Enter), or create a new one. If there is none, or you create a new one, init asks whether to send a profile of the repository, so the service can write rules for it (step 3). When you are signed in, the Standard names the review packs that fit your repository.
- turns formal verification on for a new project, and starts two downloads in the background: Trivy's vulnerability database and Lean 4 (Formal verification).
- creates
.verity/, adds the memory pointer and guidance block toCLAUDE.md, fixes up.gitignore, and migrates a legacy.gate/install if it finds one.
┌ 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 dev@example.com
◇ Cost & usage telemetry on
◇ Profile sent · no source code
◇ 6 rules for this repository · from 214 commits and 1 doc · 38s
◇ Standard v1 saved
│ Review packs: core, agent behavior, api (express). What each holds: verity standard catalogue
◇ Formal verification at push: on
◇ Getting ready in the background
│ Trivy security scanner · Lean 4 for formal checks at push (800 MB)
│ Changed: .gitignore, CLAUDE.md, .claude/settings.json, .verity/standard.yaml, VERITY.md, .claude/skills/, ~/.claude/settings.json. Details: verity doctor
└ Ready in 52s.
Start a new Claude Code session. Verity reviews from its first turn.The Changed: line names each file this run changed, so the edits in git status have an explanation. Init never pushes a Standard over your team's Standard. Its push holds only if the service still has the version init saw. If someone shares a Standard while init runs, init uses theirs.
It is safe to re-run. A re-run keeps your Standard, your moments, your telemetry answer and your formal verification setting. --yes asks nothing: it skips sign-in unless you are signed in already, leaves telemetry as it is, uses your team's Standard, and sends no profile. Flags give the answers without a question: --standard use|new, --profile send|skip, --telemetry on|off and --moments stop,pre-commit,pre-push (or none). --force reinstalls the skills. CLI & commands lists every flag.
Not finished: and the reason, and exits with code 1. Scripts and /verity:init stop there. Fix the cause it names, then run verity init again. See Troubleshooting.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-cli2 · Sign in with GitHub
This is the first question verity init asks. You can also sign in at any time, from any directory:
verity loginVerity prints a code and a link. Open the link, enter the code, and approve — that is GitHub's device flow, so it works over SSH and on a headless machine. If the Verity GitHub App is not yet installed on the organization that owns your repository, the CLI prints an install link, and after you install it GitHub sends you to a page that tells you to come back to the terminal and press Enter. Both screens are explained in Authentication.
Logged in as dev@example.com. ✓
Access granted to 17 repositories.
This login expires on 2026-11-30 — "verity login" again to renew.
✓ This repository is covered.One login covers every repository you can write to, on this machine, for 90 days. Nothing secret lands in your repo. The step is skippable: without it Verity still reviews your code, it just records nothing — no history, no memory, no dashboard.
3 · Project rules
The review packs cover the general rules for your stack. Project rules are the ones only your repository has, such as "every route under api/ uses the auth middleware". When init asks, send the repository profile, and the service writes rules for this repository into custom_patterns. The profile holds no source code. Init writes it first to .verity/repo-profile.json, so you can read it before you answer. Security & privacy lists what it holds. If you skipped it, run this later:
verity standard generateThe service saw the profile, not the code. So read the new rules in .verity/standard.yaml and remove any that do not fit. In Claude Code, /verity-setup reads the code, checks each rule against it, and adds what is missing. It also seeds the knowledge base from your README and CLAUDE.md. You can do this later, or never — the gate is already running.
4 · Work as usual
When your agent stops — and at any other moment you enabled — Verity reviews what the agent wrote this turn and returns a verdict. In the terminal it looks like this:
› scope 3 files authored this turn (1 unchanged since last verdict)
› layer 1 @codacy/analysis-cli → 0 blocking
› layer 2 independent review…
auth/login.ts:42 string-built SQL query → SQL injection (CWE-89) [parameterized-queries]
✗ FAIL · 1 critical finding
› agent self-healing (iteration 1/2)…
✓ PASS · 3 of 3 changed files reviewed · ready to commitPASS— the change meets your Standard.WARN— something worth a look, or something Verity could not review. Never blocks.FAIL— a blocking finding in the code the agent wrote. The agent reads it and fixes it, up to two attempts per problem, then the rest is deferred to you.
On a clean turn with nothing to say, Verity says nothing. When it has a note on a passing turn, the agent relays it. What every part of a verdict means — and every way to answer a finding — is in Findings & verdicts.
5 · Look at what it recorded
From the terminal, at any time:
verity statusIt prints who you are signed in as, the Standard version, the active moments, the last verdict and trend, any housekeeping window you declared, the .verityignore rules in force, and the findings still open. verity status --history adds recent runs.
On the web, sign in at verity.md/login with Continue with GitHub — the same account as the CLI — to see sessions, runs, tasks, the knowledge base and usage for every repository you can read. The dashboard describes each page. Or open the live demo first.
What got created
| Path | What it is | Commit? |
|---|---|---|
.verity/standard.yaml | Your Standard | Yes |
.verity/memory/ | The knowledge base (its log.md is gitignored) | Yes |
.claude/settings.json | The Claude Code hooks | Yes |
.claude/skills/verity-*/ | The eight skills | Yes |
VERITY.md | Project overview and service pointer | Yes |
CLAUDE.md (a managed block) | How agents should use memory, waives and housekeeping | Yes |
.verity/setup.json | The answers you gave init, so a re-run starts from them | No |
.verity/static-analysis.json | Verity's Trivy config | No |
.verity/repo-profile.json | The repository profile, for you to read before it is sent | No |
~/.claude/settings.json | Telemetry, for the whole machine — no token in it | — |
~/.verity/credentials | Your login, outside the repo, mode 0600 | — |
Every file Verity touches, including the machine-local state under .verity/, is described in Files & configuration.
Adding a teammate
The Standard and the hooks are in git, and the Standard is on Verity too — so a teammate who clones the repository runs one command and is done:
npm install -g @codacy/verity-cli && verity init # skills, hooks and their own GitHub sign-inOr, on the plugin path, three lines in Claude Code:
/plugin marketplace add codacy/verity
/plugin install verity@verity
/verity:initWhen they sign in, init finds the repository's Standard on Verity and offers it. Enter uses it. Init never pushes a competing version over it without that choice. Their runs are attributed to them. The Standard, history and memory stay shared across the repository.
Keeping it up to date
Server-side improvements reach every installed copy on deploy day with nothing to do. For the client, it depends which way you installed:
| Installed as | Update with |
|---|---|
| Claude Code plugin | claude plugin update verity@verity in your shell, then /reload-plugins in any open session (or restart Claude Code). There is no /plugin update slash command. You can also turn on Enable auto-update in /plugin → Marketplaces → verity, which Claude Code leaves off for third-party marketplaces by default. Updating the plugin reinstalls the CLI and the analyzer it pins, so they never drift. |
| Global CLI | npm install -g @codacy/verity-cli@latest. verity --version prints what you have. |
A release that changes the skills reaches a global install only when you re-run verity init --force; on the plugin the skills come from the plugin, so the update is the whole story.