Local PR review tool that orchestrates AI agents over git diffs via GitHub Copilot or Claude Code CLI.

These details have not been verified by PyPI

Project links

Project description

PR Sentinel

Local pull-request review tool. Reads a git diff, runs four specialized review agents over it via a local AI CLI, and emits a structured JSON + Markdown report so you can fix issues before raising the PR.

No API keys. No hosted services. PR Sentinel shells out to a provider CLI you already have — the GitHub Copilot CLI (default) or claude -p (--provider claude) — and uses that tool's existing authentication. See Providers.

How it works

git diff main...HEAD
        │
        ▼
[ diff_parser ] ── filters built-in noise + user skip patterns
        │             (--skip-files, .prsentinelignore)
        ▼
[ router ] ── per file, decides which agents are relevant for those file types
        │
        ▼
[ chunker ] ── packs each agent's files into ≤100k-char chunks (hybrid batching)
        │
        ▼
[ orchestrator ] ── runs (agent × chunk) tasks in a bounded thread pool
        │
        ├── Security Agent      (provider CLI + prompts/security.md)
        ├── Code Quality Agent  (provider CLI + prompts/quality.md)
        ├── Performance Agent   (provider CLI + prompts/performance.md)
        └── Testing Agent       (provider CLI + prompts/testing.md)
                │
                ▼
[ cache ] ── sha256(provider + model + prompt) → response, on disk
                │
                ▼
[ Summary Agent ] ── single provider call that dedupes/merges findings across agents
        │             (prompts/summary.md; falls back to raw findings on failure)
        ▼
[ report_generator ] ── merges findings, computes risk level
        │
        ▼
reports/report.json + reports/review-report.md

File-type routing

Not every agent has something useful to say about every file. PR Sentinel skips agents that have nothing meaningful to contribute to a chunk's file types, reducing token usage with no loss in review quality.

File type	Security	Quality	Performance	Testing
`*.cs` (source)	✅	✅	✅	✅
`Test.cs`, `Spec.cs`, `Fixture.cs`	✅	✅	—	✅
`.cshtml`, `.razor`, `*.html`	✅	✅	—	—
`.js`, `.ts`	✅	✅	✅	✅
`.css`, `.scss`, `*.less`	—	✅	—	—
`*.svg`	✅	—	—	—
`.csproj`, `.props`, `*.targets`	✅	✅	—	—
`*.sln`	—	—	—	—
`appsettings.json`, `.yml`, `.yaml`, `.xml`, `*.json`	✅	✅	—	—
`Dockerfile`, `.bicep`, `.tf`	✅	✅	—	—
`*.sql`	✅	✅	✅	—
`.csv`, `.tsv`, `*.resx`	✅	—	—	—
`.md`, `.txt`, `*.http`	✅	—	—	—
Unknown extension	✅	✅	✅	✅

Three rules behind the table:

Security runs on almost everything — secrets and PII appear in docs, config files, and data files.
Performance and Testing only run on executable code.
Unknown extensions always get all four agents — nothing is silently skipped.

If a chunk contains mixed file types (e.g. a .cs file and a .css file together), the agents for the union of both types are run. Binary files (*.png, *.dll, *.zip, etc.) are dropped entirely before routing — their diffs are unreadable.

Requirements

Python 3.11+
At least one supported provider CLI, installed and authenticated:
- Claude (default) — Claude Code CLI. claude --version must work from your shell.
- Copilot (optional, --provider copilot) — GitHub Copilot CLI. copilot --version must work, and you must have run copilot login.
Git, if you want to review live branches (not required for --diff mode).

Install

From PyPI:

pip install pr-sentinel

From source (for development):

git clone https://github.com/kishor2004reddy/Pull-Request-Sentinel-CLI.git
cd Pull-Request-Sentinel-CLI
pip install -e .[dev]

Verify:

pr-sentinel --help
pr-sentinel agents

Quickstart

Review your current branch against main:

pr-sentinel review --base main

Or review a saved diff file (works without a git repo):

git diff main...HEAD > my.diff
pr-sentinel review --diff my.diff --out reports

Open reports/review-report.md.

Commands

`pr-sentinel review`

Flag	Default	Description
`--base`	`main`	Branch to diff against. Runs `git diff <base>...<head>`.
`--head`	`HEAD`	Source branch/ref to review. Use with `--base` to diff arbitrary refs without checking them out.
`--diff PATH`	—	Review a saved diff file instead of running git. Mutually exclusive with `--staged`.
`--staged`	off	Review staged changes (`git diff --cached`).
`--repo PATH`	cwd	Path to the git repository to review. Ignored when `--diff` is used.
`--agents`	`security,quality,performance,testing`	Comma-separated agents to run.
`--out`	`./reports`	Output directory.
`--format`	`both`	`json`, `markdown`, or `both`.
`--max-file-size`	`20000`	Per-file diff size cap (chars). Larger files get truncated with a marker.
`--chunk-budget`	`100000`	Max combined diff size per provider call before chunking kicks in.
`--provider`	`claude`	AI CLI to run the agents through. `claude` shells out to `claude -p`; `copilot` shells out to the GitHub Copilot CLI. See Providers.
`--model`	provider default	Model to use, forwarded verbatim to the selected provider. claude: shortcuts `sonnet`, `opus`, `haiku`, or a full ID like `claude-opus-4-8`, `claude-sonnet-4-6` (default `sonnet`). copilot: a Copilot model ID such as `claude-sonnet-4.6`, `gpt-5` (default `claude-sonnet-4.6`).
`--max-parallel`	`12`	Max concurrent provider calls across all (agent, chunk) pairs.
`--timeout`	`600`	Per-call timeout in seconds for each `claude` subprocess.
`--no-cache`	off	Bypass the response cache for this run. Successful responses are still written to the cache.
`--skip-files`	—	Comma-separated glob patterns to skip on top of built-in noise filters (e.g. `".lock,vendor/,fixtures/.json"`). Combines with `.prsentinelignore` if present.

`pr-sentinel agents`

Lists available agents and their implementation status.

`pr-sentinel cache`

Inspect and manage the on-disk response cache.

Subcommand	Description
`cache size`	Show cache location, entry count, and disk usage.
`cache clear`	Wipe the entire cache (prompts for confirmation).
`cache prune --older-than 30d`	Delete entries older than the given age. Supports `s/m/h/d` suffixes. Add `--dry-run` to preview.

The cache lives at ~/.pr-sentinel/cache/ by default. Override with the PR_SENTINEL_CACHE_DIR environment variable. Keys are sha256(provider + model + prompt), so changing the provider, the model, or any prompt content invalidates the entry automatically (and a Claude run never collides with a Copilot run that happens to use the same model name).

Auto-pruning. Every pr-sentinel review run silently drops cache entries older than 90 days before doing any work. No flag, no output — it just keeps the cache from growing unbounded over time. The threshold is set via AUTO_PRUNE_AGE_DAYS in config.py. Use cache prune --older-than ... for manual prunes at a different age.

Providers

PR Sentinel doesn't talk to any AI service directly — it shells out to a provider CLI you already have installed and authenticated. Pick one with --provider:

Provider	CLI invoked	Prompt delivery	Default model
`claude`	`claude --model <m> -p`	stdin	`sonnet`
`copilot` (default)	`copilot --no-color [--model <m>]`	stdin	`claude-sonnet-4.6`

Notes:

Models are provider-specific. --model is forwarded verbatim to whichever provider you select; there's no translation between namespaces. sonnet means something to Claude, gpt-5 means something to Copilot. If you pass a model the provider doesn't offer, that CLI reports the error.
Discovering Copilot models. Available models depend on your GitHub Copilot plan and can't be listed non-interactively. To see what your account can use, run copilot and type /model. PR Sentinel defaults to claude-sonnet-4.6 for Copilot; override with --model if your plan doesn't include it.
Copilot runs read-only. PR Sentinel invokes Copilot without --allow-all-tools. The full diff is embedded in the prompt and the agent only returns a JSON verdict, so Copilot never needs to run shell commands or edit files in your repo.
Authentication is the provider's. No API keys live in PR Sentinel — Claude uses your Claude Code login, Copilot uses your copilot login session.

# Run the review through GitHub Copilot instead of Claude
pr-sentinel review --base main --provider copilot

# Pick a specific Copilot model
pr-sentinel review --diff my.diff --provider copilot --model claude-sonnet-4.5

Skipping files

PR Sentinel always filters built-in noise (lock files, build/dist dirs, minified, generated). To skip additional files — large fixtures, vendored code, anything that wastes tokens without adding review value — use either of these:

Per-run flag, good for one-offs:

pr-sentinel review --skip-files "vendor/**,fixtures/*.json,*.snap"

Repo-wide ignore file, good for project defaults — drop a .prsentinelignore at the repo root:

# generated docs
docs/api/**

# huge test fixtures
tests/fixtures/large/**

# vendored deps
vendor/**

Syntax: one glob per line, # for comments, blank lines ignored. Patterns use fnmatch (same as the built-in noise filter), matched against both the full path and the basename. The two sources combine — flag patterns are appended to the ignore file's patterns. Skipped files are listed in the "Skipped noise file(s)" panel at the top of the run output.

Examples

Review current branch vs main:

pr-sentinel review --base main

Run only the security agent:

pr-sentinel review --base main --agents security

Review what's currently staged:

pr-sentinel review --staged

Review a feature branch without checking it out:

pr-sentinel review --base main --head feature/new-auth

Use a stronger model for higher-stakes reviews:

pr-sentinel review --base main --model opus

Force a fresh run, ignoring cached responses:

pr-sentinel review --base main --no-cache

Skip extra files for this run only:

pr-sentinel review --base main --skip-files "vendor/**,*.snap"

Prune cache entries older than a week:

pr-sentinel cache prune --older-than 7d

Report structure

The markdown report always emits these five sections in this fixed order, regardless of findings:

Summary — risk level, source, branch, timestamp, agents, finding counts
Merge Verdict — deterministic verdict driven by risk level (not a separate Claude call)
Key Findings — top blocking issues (High + Medium)
Key Recommendations — deduplicated fixes
All Findings — per-agent summary table + full per-issue detail

The JSON report contains the same data in a single structured object suitable for piping into other tools. Key fields:

riskLevel — High / Medium / Low / None / Unknown (see table below)
coverageComplete — false if any agent failed during the run
agentsExecuted, failedAgents — who ran and who didn't
findings — flat list, sorted by severity then file
rawFindingCount — only present when the Summary Agent ran; how many findings existed before dedup

Risk levels

Level	Trigger
High	Any High-severity finding, or 5+ Medium-severity findings
Medium	One or more Medium-severity findings (and fewer than 5)
Low	Only Low-severity findings
None	No findings across all executed agents (full coverage)
Unknown	All executed agents failed, or some agents failed and the rest found nothing (can't call it clean with incomplete coverage)

Architecture

src/pr_sentinel/
├── cli.py                  # Click entrypoint + Rich UI
├── config.py               # tunable defaults + shared constants (single source of truth)
├── git_diff.py             # git rev-parse, git diff, --staged
├── diff_parser.py          # per-file splitting + noise filter (+ --skip-files / .prsentinelignore) + truncation
├── chunker.py              # greedy packer to keep prompts under chunk-budget
├── providers/
│   ├── __init__.py         # provider dispatch: name -> runner module (get_runner)
│   ├── common.py           # shared JSON extraction + cache + 1-retry logic
│   ├── claude.py           # subprocess(claude -p), prompt on stdin
│   └── copilot.py          # subprocess(copilot --no-color), prompt on stdin
├── orchestrator.py         # parallel (agent, chunk) execution via ThreadPoolExecutor
├── router.py               # file-type routing table — decides which agents run per chunk
├── cache.py                # sha256-keyed disk cache + 90-day auto-prune
├── report_generator.py     # build_report + JSON/Markdown writers
├── agents/
│   ├── base.py             # BaseAgent: load prompt, chunk, call, validate
│   ├── security_agent.py
│   ├── quality_agent.py
│   ├── performance_agent.py
│   ├── testing_agent.py
│   └── summary_agent.py    # post-processes findings: dedupe/merge across agents
└── prompts/
    ├── security.md
    ├── quality.md
    ├── performance.md
    ├── testing.md
    └── summary.md

tests/
├── test_diff_parser.py
├── test_chunker.py
└── test_report_generator.py

Running tests

pip install -e .[dev]
pytest -q

Troubleshooting

copilot CLI not found on PATH — install the GitHub Copilot CLI (npm install -g @github/copilot-cli) and confirm copilot --version works in the same shell where you run pr-sentinel.

claude CLI not found on PATH — only relevant when using --provider claude. Install Claude Code and confirm claude --version works in the same shell.

copilot returned non-JSON output after retry — the provider CLI occasionally returns prose instead of JSON. The runner retries once; if it still fails, that chunk's findings are dropped and the agent is marked failed for the run. Re-running usually succeeds.

Slow runs — large diffs trigger chunking. Each chunk is one provider call per agent. Reduce scope with --agents security if you only want one perspective, or with --max-file-size to truncate huge files. The cache amortizes repeat runs against the same diff.

Lock files / minified files showing up — they shouldn't. If they do, add the pattern to NOISE_PATTERNS in config.py, or skip on a per-project basis with .prsentinelignore (see Skipping files).

Want to skip a non-noise file (huge fixture, vendored dep, generated snapshot)? Use --skip-files "pat1,pat2" for a one-off, or commit a .prsentinelignore for project-wide defaults.

Notes & limitations

The Performance Agent only sees the diff. It can flag pattern-level issues (N+1 queries, sync-over-async) but cannot reason about runtime behavior or system load.
lineHint is approximate — unified diffs have hunk headers, not absolute line numbers. The prompt asks Claude for a description of the location rather than a hallucinated number.
Agents cannot read other files in the repo. Review depth is limited to what's visible in the diff itself.
If any one chunk fails for an agent (timeout, exit code, unparseable JSON after retry), that agent is marked failed for the run and its partial findings are discarded. Other agents continue.
The Summary Agent makes one additional provider call per run to deduplicate and merge findings across the four review agents. If it fails (timeout, bad JSON), the report falls back to the raw findings — nothing is lost.

License

MIT

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

2.3.0a1 pre-release

Jun 19, 2026

2.2.1

Jun 18, 2026

2.2.0

Jun 18, 2026

2.1.0

Jun 15, 2026

2.0.1

Jun 14, 2026

2.0.0

Jun 13, 2026

2.0.0a1 pre-release

Jun 13, 2026

1.1.1

Jun 10, 2026

1.1.0

Jun 9, 2026

This version

1.1.0rc2 pre-release

Jun 3, 2026

1.1.0rc1 pre-release

Jun 3, 2026

1.1.0b1 pre-release

Jun 3, 2026

1.1.0a1 pre-release

Jun 2, 2026

1.0.0

Jun 1, 2026

0.1.5

May 31, 2026

0.1.3

May 27, 2026

0.1.2

May 27, 2026

0.1.1

May 26, 2026

0.1.0

May 23, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pr_sentinel-1.1.0rc2.tar.gz (47.3 kB view details)

Uploaded Jun 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pr_sentinel-1.1.0rc2-py3-none-any.whl (48.4 kB view details)

Uploaded Jun 3, 2026 Python 3

File details

Details for the file pr_sentinel-1.1.0rc2.tar.gz.

File metadata

Download URL: pr_sentinel-1.1.0rc2.tar.gz
Upload date: Jun 3, 2026
Size: 47.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.4

File hashes

Hashes for pr_sentinel-1.1.0rc2.tar.gz
Algorithm	Hash digest
SHA256	`2882665a7de16321ddcb1092312f7f9c57cb4334aa23ab09e466ef553bb291b1`
MD5	`f54cbe2a73455d435ad0518cbdd6dba6`
BLAKE2b-256	`f091a12eadad43e101b8603dd6b2bb625f56da0d040a439f6a1e29e16ab605b7`

See more details on using hashes here.

File details

Details for the file pr_sentinel-1.1.0rc2-py3-none-any.whl.

File metadata

Download URL: pr_sentinel-1.1.0rc2-py3-none-any.whl
Upload date: Jun 3, 2026
Size: 48.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.4

File hashes

Hashes for pr_sentinel-1.1.0rc2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`af3a0dc95dca60aa99766ca4a7630dd331e53190a57f291a299ce75e8ebdb3c4`
MD5	`4ec1476f6e1aea17ac771b9c7d1bfcc8`
BLAKE2b-256	`835aac3244e90ad83f511b092c9381ad560bdd090f97c6672dc6df18a70242b1`

See more details on using hashes here.

pr-sentinel 1.1.0rc2

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

PR Sentinel

How it works

File-type routing

Requirements

Install

Quickstart

Commands

pr-sentinel review

pr-sentinel agents

pr-sentinel cache

Providers

Skipping files

Examples

Report structure

Risk levels

Architecture

Running tests

Troubleshooting

Notes & limitations

License

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

`pr-sentinel review`

`pr-sentinel agents`

`pr-sentinel cache`