pr-checkmate
v4.2.0
Published
Security-first PR gate for CI: secret scanning, grype dependency scanning, SBOM — plus linting and formatting across 11 languages
Maintainers
Readme
♟️ PR CheckMate
A security-first PR gate for CI: secret scanning, dependency vulnerability checks, and a CycloneDX SBOM plus an independent VirusTotal scan of the exact published tarball on every release — plus 54 code-quality checks across 11 languages, bundled. One npm package, one
pr-checkmate.json, no per-language toolchain setup for the bundled ones. Also an MCP server and a Claude Code plugin: your AI coding agent runs the same gate while it writes code.
Language is auto-detected. Checks run in parallel phases, results post as one PR comment that updates in place, and formatter fixes are committed back to the branch.
Using Claude Code? Install it as a plugin, one command, no npm install needed to start:
/plugin install pr-checkmate --marketplace Mybono/pr_checkmate_publicIt connects the MCP server and adds a skill that sets the package up in your repository when you agree. Details below.
Quickstart
1. Install.
npm install --save-dev pr-checkmate2. Set it up. init detects your languages and writes pr-checkmate.json plus
.github/workflows/pr-checkmate.yml. Safe to re-run — it updates the config rather than
replacing it, and never overwrites a workflow that already exists.
npx pr-checkmate init3. Run.
npx pr-checkmate allScope. In CI it reviews the pull request diff; locally, every tracked file. --full
forces the whole repository anywhere. Only PR Size, Missing Tests and Lockfile Drift need a
diff and drop out of a full run.
CI only — no install
Two files, taken straight from the public repository. Nothing goes into your
package.json.
- pr-checkmate-workflow.yml → put in
.github/workflows/. Runs the container, image tag already pinned. - pr-checkmate.json → put in the repository root. Every check with its default value and a comment.
Commit both and it runs on the next pull request. Both are regenerated on every release.
Running in CI → — the generated workflow line by line, which three lines are load-bearing, adopting it on a codebase that is not clean yet, and the setup step each runner-dependency language needs.
AI agents (MCP)
PR CheckMate is also an MCP server, so Claude Code, Cursor or any other MCP client can run the gate while it writes code, not after the pull request is open. The agent reads the repository's rules first, checks its own changes as it goes — uncommitted files included, nothing has to be staged — and runs the full gate once before it says it is done.
npm install -g pr-checkmate
claude mcp add --scope user pr-checkmate -- pr-checkmate mcp # once, for every project
npx pr-checkmate agent-setup # per repository, belowThen check it: claude mcp list shows pr-checkmate ✔ Connected; sessions that were already open
need a restart. claude comes from the Claude Code CLI (an editor extension keeps its own copy off
your PATH). To stop Claude Code asking before every call, allow mcp__pr-checkmate in
permissions.allow
(details).
Claude Code plugin. The one-command install at the top of this page replaces the two commands
above. It runs the MCP server with npx, pinned to the released version, and adds a skill that
offers to install the npm package if it is missing. The tools are named
mcp__plugin_pr-checkmate_mcp__*, so allow that prefix instead of mcp__pr-checkmate. Claude
Code still asks before the first call of each tool.
| Tool | The agent calls it |
|---|---|
| get_rules | before writing — what blocks a PR, what only warns, your custom rules and banned imports |
| check_changes | while working — fast checks on what it has changed so far |
| scan_secrets | before committing config, environment or credential files |
| apply_fixes | instead of fixing style by hand — formats and autofixes only the files it changed |
| check_dependency | before adding a package — does it exist, advisories (malware included), look-alike names |
| verify | once, when it believes the work is done — every check, the slow ones included |
| suggest_config / write_config | set pr-checkmate up for this repository: propose, then write once you agree |
agent-setup registers the server in .mcp.json, adds a short instructions block to AGENTS.md /
CLAUDE.md telling the agent when to call each tool, and — in Claude Code — installs a hook that
checks staged changes on git commit and blocks the commit with the findings. It only adds, and is
safe to re-run. While a project has no pr-checkmate entry in .mcp.json, the summary printed by
npx pr-checkmate all ends with an AI AGENT: line pointing at the command (not shown in CI), and
init adds it to the commands block of an existing pr-checkmate.json.
Limits. An agent can ignore a tool, so nothing here guarantees that npx pr-checkmate all finds
nothing: the CI gate stays the authority. Two tools write files, apply_fixes and write_config;
the rest only read. The protocol is implemented in this package, with no MCP SDK or HTTP framework
behind it.
Turn it off or narrow it. The mcp block of pr-checkmate.json controls what the agent sees,
from its next request and without a restart:
"mcp": { "enabled": true, "disabledTools": ["check_dependency"], "readOnly": false }enabled: false leaves the server connected with nothing to offer, disabledTools hides tools by
name, and readOnly: true hides the two that write files.
Language Support
Bundled languages need nothing on the runner. Runner-dependency languages need their tool installed; the check skips gracefully when the tool is absent.
| Language | Checks | Toolchain |
|---|---|---|
| TypeScript / JavaScript | ESLint, Prettier, tsc --noEmit | Bundled |
| Python | Ruff (lint + format), mypy/pyright (types) | Fetched on first use — Ruff, and pyright for types; the runner's own mypy is preferred when it has one |
| C++ | clang-format | Bundled |
| Swift | SwiftLint | swiftlint on the runner |
| Kotlin / Java | ktlint | ktlint on the runner |
| Go | go vet, gofmt | gofmt bundled; go vet needs the Go toolchain on the runner |
| Rust | cargo clippy, cargo fmt | Rust toolchain on the runner |
| C# | dotnet format | .NET SDK on the runner |
| Ruby | RuboCop | rubocop on the runner |
| PHP | PHP-CS-Fixer | php-cs-fixer on the runner |
| Shell | ShellCheck | shellcheck on the runner |
Secret scanning (gitleaks) and the universal git-diff checks are bundled and run for every language.
Checks
55 checks, run in parallel within each phase:
| Group | Count | What it covers |
|---|---|---|
| Universal git-diff | 18 | Secret scan, diff security, GitHub Actions and Dockerfile hardening, migration safety, sensitive files, custom rules, and the rest — language-agnostic and bundled |
| Per-language | 17 | Lint, format and type-check for the languages above |
| Dependencies | 7 | Unused/missing, circular, outdated, licence compliance, npm audit, and two vulnerability scanners |
| Quality | 7 | Duplicate code, dead code, spellcheck, markdown, YAML, broken symlinks, config validation |
| PR hygiene | 4 | Size, title, body, commit-message convention |
Check reference → — every check has its own page: when it runs, every config key it reads, the defaults, how to turn it off.
Configuration
One file, deep-merged over the defaults, so it holds only your deviations. The severity
map keys any check by the name it shows in the report:
{
"severity": {
"PR Size": "error", // oversized PRs now fail the run
"Spellcheck": "off"
},
"prSize": { "maxFiles": 40, "maxLines": 800 }
// Skip a single line by appending `// pr-checkmate-ignore` to it.
}ignoreDirs, duplicate.ignore and deadCode.ignoreFiles REPLACE their defaults rather
than extending them.
Config guide → · Annotated full config →
Programmatic API
Besides the CLI, PR CheckMate ships a typed API for embedding the same gates in your own
tooling. Import runChecks, defineCheck, and the outcome helpers, then run the
registry or your own checks. The full reference is at the
API docs site.
import { runChecks } from 'pr-checkmate';
const report = await runChecks({ cwd: process.cwd(), reporter: 'github' });
if (!report.ok) process.exit(1);runChecks never throws on violations and never calls process.exit; the caller
decides. report.ok is true when nothing failed, and warnings and skips do not
affect it.
License
LicenseRef Proprietary © 2025-2026 Artur Polishchuk. Free to install and run via the published npm package, and that right is irrevocable for every published version (see LICENSE for the exact grant); the source is not open-source and is not licensed for copying, modification, or redistribution.
