Troubleshooting

Nothing appears on the pull request

Is the repository covered by the App? Check Repos in the web app, or the installation on GitHub. Verity gets no events for repositories outside the installation.
Is the check waiting? Waiting for session upload means a linked session is still uploading. The check updates when it settles, and at the time it names at the latest.

"No rules checked"

There's no .verity/rules.yml on the base branch, or Verity can't read it.

Run npx @verity/cli capture init to write a starter file, and merge it into the base branch. Rules are read from the base branch, so a file added in a pull request applies from the next one.
If the file is there, the App may not have the Single file permission yet. An org owner approves it on GitHub; the Setup page says when it's missing. See Install the GitHub App.

A rule fired and it shouldn't have

Rules fail closed. An unsure answer, or no answer, fires the rule. If a question rule fires often on good changes, make the question more specific, or narrow its files.
A rule that needs the session fired on a pull request without one. Set no_session: pass on the rule if that's fine for it.
The change is fine this time. A reviewer who isn't the author adds the label verity-override:<rule id>. See Overrides.

The label counts only when a GitHub user who isn't the pull request's author adds it. The comment says "not accepted (author or bot)" when it came from the author or a bot. Ask another reviewer to add it.

Sessions aren't uploading

Check that verity is on your PATH (npm install -g @verity/cli). The hooks do nothing without it.
Look in ~/.local/state/verity/capture.log for errors.
If the log says to run verity capture login, your sign-in expired. Sign in again: sessions waiting on the machine upload at the next hook.
Check that the repository is in the App's installation. Uploads to a repository it doesn't cover are refused, and the log says so.
Check that .claude/settings.json with Verity's hooks is committed on the branch you're working on.

No session linked

The check title ends in "no session linked", and there is no brief. Rules are still checked. Sessions are linked by the Agent-Session trailer that capture adds to commits; when it's missing, Verity matches sessions by branch and time.

If the commits say an agent wrote them, Verity also comments that no session was linked. The author installs the CLI and signs in (see Capture sessions), and the next push has a brief.

Limited briefs

Reason	What it means	What to do
No agent session linked	No session was uploaded for the pull request.	Set up capture; see above.
Mostly human or shell edits	Under half of the diff comes from edits in the session.	Nothing to fix: most of this change wasn't made through the agent's file tools. Review it as usual.
No steps of the session fall in this PR's slice	The linked session was split across pull requests, and none of it belongs to this one.	Check that the commits' trailers point at the right session.
The PR diff has no changes to attribute	The diff is empty.	Nothing to fix.
Unknown transcript format	Claude Code changed its transcript format.	Nothing to do on your side: Verity needs an update.

Session expired

Session expired means the linked sessions' transcripts passed the organization's transcript retention, so a new push can't be briefed again. The last report stays available until it expires. Org owners can change transcript retention in Settings.

Sessions started outside the repository

Verity works out the repository root from the pull request's diff when Claude Code was started in a subdirectory or above the repository. A session whose only edits in the diff were made with shell commands can't be placed this way.

Forks and open-source projects

Pull requests from forks have no session: their authors can't upload sessions to your repository.