Automated PR Review

Static analysis finds bugs. Blast radius tells you which ones matter.

A SQL injection in dead code is noise. A SQL injection reachable from 47 callers including your auth endpoint is critical. Cartomancer bridges the gap between "pattern matches" and "this matters."

✓ Open source · MIT
✓ Self-hosted · single binary
✓ Works with any language opengrep supports
✓ Local-first LLM via Ollama (or Claude)

Quick Install

Cargo cargo install cartomancer

View on GitHub How it works Documentation

MIT License · Rust · Single binary · GitHub native

cartomancer review

$ cartomancer review acme/api 42 --dry-run # Fetching PR #42 metadata... # Scanning with opengrep (3 custom rules + 3000 built-in)... # Enriching 5 findings with cartog blast radius... # Escalating severity... Finding 1/5 CRITICAL sql-injection src/api/users.rs:47 Blast radius: 23 callers (auth, payment) Escalated: Warning -> Critical (auth domain, 23 callers) LLM: "Unsanitized user input reaches SQL query via authenticate() -> fetch_user(). Affects all login flows and payment verification." Fix: suggested diff attached Finding 2/5 INFO unused-import src/utils.rs:3 Blast radius: 0 callers Category: Nitpick Review: 2 actionable, 3 nitpicks. Posted to PR #42.

Pipeline

From PR event to actionable review in seconds

Every PR goes through an 11-stage pipeline. Each stage adds context that makes the next one smarter.

Scan

opengrep

3000+ rules + your custom YAML rules. Baseline-aware: only flags new findings in the diff.

Enrich

cartog

Blast radius, caller graphs, domain detection. Knows if a finding touches auth or payment flows.

Escalate

severity matrix

Findings auto-upgrade based on blast radius, domain tags, and caller count. Per-rule overrides.

Deepen

LLM

High-severity findings explained by Ollama or Claude. Suggested fix as diff + AI agent prompt.

Post

GitHub API

Categorized inline comments, off-diff caution banners, summary with actionable counts.

The output

This is what lands in the PR

Cartomancer posts structured, review-quality comments — not a noisy wall of linter output.

cartomancer-bot commented on src/api/users.rs · just now

● Critical Actionable sql-injection

Unsanitized user input reaches a SQL query. Escalated from Warning to Critical — this function sits in the auth domain and has 23 callers including login() and verify_payment().

Blast radius · 23 callers across 7 files

authenticate()  ->  fetch_user()     [this finding]
login_handler() ->  authenticate()
oauth_callback() -> authenticate()
verify_payment() -> authenticate()
...19 more

Suggested fix · unified diff

- let query = format!("SELECT * FROM users WHERE id = {}", user_id);
+ let query = "SELECT * FROM users WHERE id = $1";
+ let row = sqlx::query(query).bind(user_id).fetch_one(&pool).await?;

AI agent prompt · copy-paste to Claude / Cursor

In src/api/users.rs line 47, replace string-formatted SQL
with a parameterized sqlx query. The user_id parameter
comes from an unauthenticated HTTP handler — treat as
untrusted. See also callers in auth/login_handler.rs...

Who it's for

If you've ever said any of these, keep reading

“Our SAST tool floods us with 500 findings per PR and we've learned to ignore it.”
Cartomancer ranks by structural impact — so the top of the list is what actually matters.

“CodeRabbit is great but we can't ship our code to a third-party SaaS.”
Self-hosted, single binary, air-gap capable with Ollama. Your code never leaves your infra.

“Our reviewers keep missing that a change in a utility cascades into the payment flow.”
Blast radius from cartog surfaces the callers automatically, inline on the PR.

“We have team-specific conventions that no off-the-shelf linter knows about.”
Drop YAML rules in .cartomancer/rules/ and markdown context in knowledge.md — the LLM uses both.

Features

Not just another linter. A review brain.

Cartomancer combines static analysis, code graph intelligence, and LLM reasoning into one pipeline.

Blast radius awareness

Every finding is enriched with caller count, transitive impact depth, and domain tags (auth, payment, data). A bug in a utility used by 2 callers is not the same as one used by 47.

Severity escalation

Findings auto-upgrade based on structural context. A Warning in an auth-reachable function becomes Critical. Per-rule min_severity / max_severity overrides for your team's needs.

LLM deepening

High-severity findings are explained by Ollama (local) or Claude (production). Each gets a suggested fix as a unified diff and an AI agent prompt for automated remediation.

Company knowledge

Inject your team's conventions, architecture docs, and security policies into every LLM prompt via .cartomancer/knowledge.md. The LLM knows your codebase, not just the pattern.

Custom rules

Drop YAML rule files in .cartomancer/rules/ and they're auto-discovered. Encode team-specific business rules alongside opengrep's 3000+ built-in patterns.

Regression detection

Every finding is fingerprinted. Cartomancer compares against the base branch baseline to distinguish genuinely new issues from pre-existing ones. False positives can be dismissed.

GitHub native

Inline comments on diff lines, caution banners for off-diff findings, summary with actionable counts. Runs as CLI or webhook server for full automation.

Finding persistence

All scans and findings are stored in SQLite. Browse history, search by rule/severity/file, track trends across branches. Dismissals are fingerprint-based and survive line shifts.

Single binary

Written in Rust. No Python, no Docker, no language servers required. cargo install and you're reviewing PRs. Air-gap capable when using Ollama.

Capability	CodeRabbit	SonarQube	Opengrep alone	Cartomancer
Static analysis rules	LLM-based	proprietary	3000+ open	3000+ open + custom
Blast radius	none	none	none	cartog graph
Severity escalation	none	static	static	structural + per-rule
LLM analysis	yes	no	no	conditional + knowledge
Custom team rules	learning	yes	yes	YAML auto-discover
Self-hosted / local	SaaS only	yes	yes	single binary
Regression detection	no	yes	baseline flag	fingerprint-based
Cost	paid	paid (enterprise)	free	free / MIT

Escalation

Severity is structural, not just syntactic

Findings are escalated based on where they sit in your codebase, not just what pattern they match.

Condition	Effect
Blast radius ≥ 4× threshold	Critical
Blast radius ≥ threshold	Error (minimum)
Domain: `auth` or `payment`	Critical
Callers ≥ 10	Error (minimum)
Per-rule `min_severity`	Floor before escalation
Per-rule `max_severity`	Ceiling after escalation

Default blast_radius_threshold = 5. Configurable in .cartomancer.toml.

Install

Get started in one command

From crates.io

cargo install cartomancer

Requires Rust toolchain and opengrep in PATH.

Pre-built binaries

# macOS (Apple Silicon)
curl -L https://github.com/jrollin/cartomancer/releases/latest/download/cartomancer-aarch64-apple-darwin.tar.gz | tar xz
sudo mv cartomancer /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/jrollin/cartomancer/releases/latest/download/cartomancer-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cartomancer /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/jrollin/cartomancer/releases/latest/download/cartomancer-aarch64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cartomancer /usr/local/bin/

All platforms (including Windows) on GitHub Releases.

Your first review

# 1. Scaffold config + verify dependencies
cartomancer init
cartomancer doctor

# 2. Dry run a PR
export GITHUB_TOKEN=ghp_...
cartomancer review owner/repo 42 --dry-run

init writes a commented .cartomancer.toml, doctor checks git/opengrep/cartog/LLM, and --dry-run prints the review instead of posting to GitHub.

Webhook server

cartomancer serve --port 3000

Receives GitHub pull_request events. HMAC-validated, bounded concurrency, graceful shutdown.

FAQ

Questions you probably have

Is my code sent to a third party?

No — not unless you explicitly configure the Anthropic provider. The default LLM backend is Ollama running locally. Cartomancer itself is a binary on your box; only GitHub API calls leave the machine (PR metadata + posting comments). Fully air-gap capable.

Which languages are supported?

Static analysis: anything opengrep supports (Python, JS/TS, Go, Java, Rust, Ruby, C, C#, PHP, Kotlin, Swift, etc.). Blast radius via cartog: Python, TypeScript/JavaScript, Rust, Go, Ruby, Java. If cartog doesn't know your language yet, you still get static analysis + LLM — just without the structural escalation layer.

How is this different from CodeRabbit / Greptile / GitHub Copilot review?

Those are LLM-first: they read your diff and guess at issues. Cartomancer is analysis-first: opengrep's deterministic rules find real patterns, cartog's call graph measures impact, and the LLM is used surgically to explain and suggest fixes for the findings that already passed the structural bar. Fewer hallucinations, cheaper runs, and you can ship it on your own infra.

Does it work without an LLM?

Yes. LLM deepening is conditional — you still get the full opengrep scan, cartog enrichment, severity escalation, and GitHub comments without it. Turn it off entirely by setting the deepening threshold above critical.

What does “blast radius” actually measure?

The number of transitive callers of the function containing the finding, computed from cartog's call graph. Combined with domain tags (auth, payment, data) it turns static severity into structural severity: a Warning in a 47-caller auth path becomes Critical; an Error in dead code stays quiet.

How do I try it on a real PR without posting comments?

Pass --dry-run — the full pipeline runs and the review is printed to stdout instead of posted. Great for first-time evaluation and CI previews.

Can I run it in CI instead of as a webhook?

Yes. Invoke cartomancer review <owner/repo> <pr> from GitHub Actions, GitLab CI, or any job runner with access to GITHUB_TOKEN. The webhook server (cartomancer serve) is optional — use it when you want instant reviews without wiring CI.

It's v0.7.x — is it production ready?

It's a young project, shipping incrementally. The pipeline works end-to-end, has tests, and produces useful reviews today. Expect the CLI surface to stabilize before 1.0. File an issue or PR — feedback shapes the roadmap.