Quickstart

You need Python 3.12 or newer, uv, git, and an API key from Anthropic or OpenRouter. Culprit is developed on macOS and meant for Linux CI runners too; Windows hasn't been tested.

Install#

uv tool install culprit-cli

This puts the culprit command on your PATH. If your shell can't find it afterwards, run uv tool update-shell and open a new terminal.

Other ways: pipx install culprit-cli or pip install culprit-cli. To try a command without installing, prefix it with uvx culprit-cli, as in uvx culprit-cli init. Culprit needs uv on your PATH either way, because it installs your agent with it.

Your first bisect#

Your agent's repo needs an eval module and a suite first. Prepare your agent covers what they look like.

1. Set up the repo. Saves your key and writes culprit.toml. See culprit init.

   TerminalCopy

   culprit init

2. Find the commit. Give it a ref that was good and one that is bad. It prints a run ID. See culprit run.

   TerminalCopy

   culprit run --good v1.0 --bad HEAD --budget-usd 3

3. Find the lines and fix them, using that run ID. See culprit localise and culprit fix.

   TerminalCopy

   culprit localise 77f60c9fccf8
   culprit fix 77f60c9fccf8

4. Read the report. See culprit report.

   TerminalCopy

   culprit report 77f60c9fccf8

Upgrade or uninstall#

uv tool upgrade culprit-cli
uv tool uninstall culprit-cli

Uninstalling leaves your saved keys and each repo's .culprit/ folder and culprit.toml in place. Where Culprit keeps things lists them. The changelog says what each version changed.

Next#

• CI and pull requests: run the check on every pull request.
• How bisect works: why Culprit can trust noisy evals.