culprit

culprit is a root cause analysis tool for agent-driven development, with the goal of enabling coding agents, before committing, to find out what introduced a bug and to verify whether their own fix is complete.

Purpose

Although a coding agent can dig through git history on its own to find the problem, it will not spend a dozen-plus tool calls on it every time, nor will it necessarily stop before committing to check whether the helper function it just changed still has other callers. culprit turns these two things into a single deterministic call and returns structured JSON for the agent to use directly. Its positioning is as an accelerator for agents, not a replacement, and not a blame tool that is smarter than the agent.

Main capabilities

• Instant: does not run tests or perform bisect. Benchmarks show a 41% reduction in agent tool calls.
• Read-only and offline: does not write to the repository or PR, requires no API key, and requires no network.
• MCP-native: provides 11 tools via stdio, is listed in the official MCP registry, and has a one-click plugin.
• Language-agnostic: suspect commit analysis works anywhere git is available; blast radius analysis supports 12 language families.
• verify_fix pre-commit gate: run it against the agent's own diff before committing, and it returns verdicts such as complete (no remaining unchanged call sites), partial (one was missed), or risky (high risk), along with information such as untouched_references (the specific files still using the modified symbol), skipped_symbols, adds_test, and notes. Loop until complete before committing.
• HTML report: --html writes a self-contained file, requires no CDN, can be opened offline, presents the verdict and risk factors at the beginning, along with the primary suspect commit and the bug's survival time, and reconstructs the process by which the bug arose: every commit that touched the problematic line, from creation to breakage (red, with the exact diff) and then to the fix (green).
• Optional bisect confirmation: --bisect "<cmd>" runs a real bisect in a disposable git worktree, without touching your working copy. When the first failing commit matches the suspect commit, the report is marked as git bisect confirmed.
• CI gate: reflects risk only through exit codes, does not write PR comments, and does not write.

Usage

Requires Python 3.10+ and uv to run the MCP server; the CLI can run on 3.9+.

The Claude Code plugin installs the MCP server and a skill that tells the agent when to use it. Supports any MCP client, such as Cursor, Windsurf, VS Code, Codex CLI, Zed, Continue, Cline, Amazon Q, Goose. The CLI can also be used without an agent.

Benchmark reproduction command: python benchmarks/run.py, which clones the repository and scores each case.

CI configuration: copy examples/github-actions/culprit-pr.yml into .github/workflows/.

The base branch resolution order is: the --base flag, the CULPRIT_BASE environment variable, .culprit.toml (base = "origin/main"), and finally HEAD~1. --last forces the latest commit view.

PR titles and labels use the GitHub CLI when present, otherwise use the unauthenticated REST API for public repositories (GITHUB_TOKEN or GITLAB_TOKEN can be set to raise rate limits). Deep links cover GitHub, GitLab, Bitbucket, Gitea.

Accuracy notes

Benchmarked on 50 real regression cases, 25 from git and 25 from systemd, with the introducing commit confirmed by each fix's Fixes: trailer (author-verified ground truth). Given only the fix commit, culprit ranks the bug-introducing commits by attributing the removed lines.

Comparative testing on 10 regression cases shows: the agent wins on accuracy, and culprit does not make it more accurate. culprit's value is completing the investigation in about half the steps, reducing each investigation by about 8000 tokens. Tool calls dropped in all 10 cases, and tokens dropped in 7 cases. In the hardest case, the agent alone needed 42 tool calls and 124k tokens, while with culprit it was 16 calls and 84k tokens. Thesesavings already account for the overhead of reading culprit's output. culprit's own run is a deterministic call, with no model, in under a second.

When to use

• Coding agents verifying fix completeness before committing.
• As a risk gate in CI.
• Offline root cause analysis on unseen codebases such as large C codebases.
• Blast radius analysis of changes across multilingual codebases.

Limitations

• The comparative test sample is n=10, and that slice is easier than the full 50 cases.
• It is not better than an agent using git on accuracy; it is positioned as an accelerator, not a replacement.
• The optional LLM narration is the only non-deterministic step, isolated behind an adapter, so the engine itself does not need an API key.
• The MCP server requires Python 3.10+ and uv; the CLI requires 3.9+.