Capture sessions

Capture records each Claude Code session as it runs, removes secrets on the developer's machine, and uploads the session to Verity. It also adds an Agent-Session trailer to each commit the session makes, which tells Verity which session wrote which pull request.

Install the CLI

Capture is part of the verity CLI, published on npm as @verity/cli. You can run any command once with npx:

npx @verity/cli capture init

The hooks that capture sessions call verity directly, so every developer whose sessions should be captured installs it globally once, which puts verity on their PATH:

npm install -g @verity/cli

The commands below use verity. Without the global install, put npx @verity/cli in its place.

Add capture to a repository

Run this once in each repository, then commit the result:

verity capture init
git add .claude/settings.json .verity/rules.yml
git commit -m "Capture agent sessions"

init adds Verity's hooks to .claude/settings.json and installs a git prepare-commit-msg hook that adds the Agent-Session trailer. Because the settings file is committed, everyone on the team can see that capture is on.

It also writes a starter .verity/rules.yml, built from the files in your repository, with every rule set to warn so nothing blocks a merge yet. Commit it too, and read Org rules to tune it. An existing rules file is only checked, never changed. Pass --no-rules to skip it.

For developers without verity installed, the hooks do nothing.

If you use husky or lefthook

If core.hooksPath is set, init can't install its git hook. It prints a line to add to your hook manager's prepare-commit-msg instead:

command -v verity >/dev/null 2>&1 && verity capture git-hook prepare-commit-msg "$@" || true

Sign in

Each developer signs in once per machine, with GitHub:

verity capture login

It opens GitHub's device sign-in and saves which Verity server you signed in to, so uploads keep going there.

The token is kept in the OS keychain, or, where there is none, in ~/.config/verity/credentials.json, which only you can read. verity capture logout signs out.

What is uploaded, and when

  • Sessions upload in the background while Claude Code runs. The hooks only note what happened and start a background worker: they never print anything or block Claude.
  • Secrets are redacted on the machine before anything is uploaded. Verity's server redacts again before storing the session, and checks once more before any model sees text. See Security.
  • When a pull request opens, Verity waits for its linked sessions to finish uploading (up to ten minutes) before it analyses them.

When you're signed out

Sessions are kept on the machine instead, redacted, in ~/.local/share/verity/sessions/<owner>/<repo>/. Nothing is uploaded. Sign in again to upload new sessions.

Logs

Capture writes any problems to ~/.local/state/verity/capture.log. Look there first if sessions aren't showing up. See also Troubleshooting.

Platforms

macOS and Linux.