[Introduction](https://verity.md/docs) [Quickstart](https://verity.md/docs/quickstart) [Authentication](https://verity.md/docs/authentication) [How it works](https://verity.md/docs/how-it-works) [Moments](https://verity.md/docs/moments) [Formal verification](https://verity.md/docs/formal) [Findings & verdicts](https://verity.md/docs/findings) [The Standard](https://verity.md/docs/standard) [Org Standards](https://verity.md/docs/org-standards) [Standards on the web](https://verity.md/docs/web-standards) [The terminal editor](https://verity.md/docs/terminal-editor) [Memory](https://verity.md/docs/memory) [Org knowledge](https://verity.md/docs/org-knowledge) [Token telemetry & cost](https://verity.md/docs/cost) [The dashboard](https://verity.md/docs/dashboard) [CLI & commands](https://verity.md/docs/cli) [Files & configuration](https://verity.md/docs/files) [Security & privacy](https://verity.md/docs/security) [Troubleshooting](https://verity.md/docs/troubleshooting)

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](https://git-scm.com/downloads/win); see [Troubleshooting → Windows](https://verity.md/docs/troubleshooting).
- **Node.js 20+** and **git**, with a repository whose `origin` remote 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@verity`

The 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](https://verity.md/docs/files).

Already installed as verity@codacy?

Verity published under the marketplace name `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@verity
```

### As a global CLI

From the root of your repository:

$`npm install -g @codacy/verity-cli && verity init`

`verity 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](https://verity.md/docs/how-it-works) explains each).
- says when Verity reviews: **every turn, every commit and every push**. It does not ask. `verity config moments` changes it ([Moments](https://verity.md/docs/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 `s` to 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](https://verity.md/docs/cost)).
- **writes your [Standard](https://verity.md/docs/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](https://verity.md/docs/standard) 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](https://verity.md/docs/formal)).
- creates `.verity/`, adds the memory pointer and guidance block to `CLAUDE.md`, fixes up `.gitignore`, and migrates a legacy `.gate/` install if it finds one.

verity init

```
┌  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](https://verity.md/docs/cli) lists every flag.

“Not finished” means no Standard was set up

When init cannot set up a usable Standard, it ends with `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](https://verity.md/docs/troubleshooting).

npm says EACCES?

Your npm global directory is not writable. Point npm at one you own, then install again:

```
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
```

## 2 · Sign in with GitHub

This is the first question `verity init` asks. You can also sign in at any time, from any directory:

```
verity login
```

Verity 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](https://verity.md/docs/authentication).

verity login

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

Restart Claude Code once init finishes

Claude Code reads hook wiring and telemetry settings at startup. Until you restart, a moment you just enabled will not fire and Token telemetry will stay empty.

## 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](https://verity.md/docs/security) lists what it holds. If you skipped it, run this later:

```
verity standard generate
```

The 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](https://verity.md/docs/memory) 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](https://verity.md/docs/moments) you enabled — Verity reviews what the agent wrote this turn and returns a verdict. In the terminal it looks like this:

verity · stop hook

```
› 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 commit
```

- `PASS` — 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](https://verity.md/docs/findings).

## 5 · Look at what it recorded

From the terminal, at any time:

```
verity status
```

It 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](https://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](https://verity.md/docs/dashboard) describes each page. Or open the [live demo](https://verity.md/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](https://verity.md/docs/files).

## 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-in
```

Or, on the plugin path, three lines in Claude Code:

```
/plugin marketplace add codacy/verity
/plugin install verity@verity
/verity:init
```

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

Next

Read [How it works](https://verity.md/docs/how-it-works) to understand what is reviewed and why, choose your [moments](https://verity.md/docs/moments), then tune the bar in [The Standard](https://verity.md/docs/standard).

[Previous Introduction](https://verity.md/docs) [Next Authentication](https://verity.md/docs/authentication)

Source: https://verity.md/docs/quickstart
