Verity docs

Verity is a GitHub App for teams whose pull requests are written by coding agents. It does two things:

  • Checks your team's rules on every pull request. You write each rule once in .verity/rules.yml, for example "a change to auth code must be behind a feature flag". Verity answers it from the diff and the agent's session, never from the PR description the agent wrote. A rule that fails can fail the check run, so the pull request can't merge until a reviewer looks.
  • Writes a review brief from the Claude Code session behind the pull request: what was asked, what the agent did, and how it knows the work is done. The brief points the reviewer at the few places that need a person.

Verity does not review code. It doesn't tell you whether the code is correct. It tells you what the agent was asked, what it ran, and where your rules need a human.

Set up in four steps

  1. Install the GitHub App on your organization and pick the repositories it covers. An org admin does this once.
  2. Add capture and rules to each repository with npx @verity/cli capture init, and commit the files it writes.
  3. Install the CLI and sign in once on each machine with npm install -g @verity/cli and verity capture login, so sessions upload to Verity.
  4. Open a pull request. Verity checks it when it opens and on every push.

After you sign in, the Setup page in the web app shows which of these steps are done.

Where results appear

  • On the pull request: one comment and a check run, both about your rules. They list which rules failed, warned or passed, and how to override one. The check run fails when a fail rule fires; otherwise it passes. See Org rules.
  • In the report: the review brief and the full session, opened from the comment's button. See Read the review brief.

Only people who can read the repository on GitHub can open its reports.

Requirements

  • Claude Code, for the review brief. Rules are checked on every pull request, including ones without a session.
  • Private GitHub repositories. Pull requests from forks have no session, because their authors can't upload to your repository.
  • macOS or Linux on the developer's machine, for capture.