Checkmate
Automated code quality enforcement for Claude Code. Runs your linters, formatters, and type checkers after every edit. Routes completed subagent work to reviewer agents. Catches errors before they compound.
Table of Contents
Why Checkmate?
- Immediate feedback loop. Claude edits a file → checks run automatically → errors block until fixed. No context lost. No forgotten linting steps.
- Task review gates. Subagent completes work → reviewer agent triggered automatically. Map
*-engineer → *-reviewer with wildcard patterns.
- Monorepo-native. Different tools per directory. Python API with uv, TypeScript frontend with pnpm, C++ engine with clang-format -all in one config.
- Zero-config start. Run
/checkmate:init and it discovers your toolchain.
- Works with any tool. Predefined parsers for common tools. Custom regex parsers for everything else.
- Respects git operations. Skips checks during rebase, bisect, and am to avoid corrupting repo state.
How It Works
When Claude edits a file, the PostToolUse hook fires and loads .claude/checkmate.json. Checkmate matches the file path to an environment, retrieves the checks for that extension, and runs each tool in sequence. Output is parsed into structured diagnostics. If errors are found, Claude is blocked until it fixes them. Clean files pass silently.
By default, Checkmate ensures that tools report errors without auto-fixing files. Auto-fix tools desynchronize Claude Code's internal state and cause false positives during non-atomic changes—for example, flagging an unused import before Claude adds the code that uses it.
See this article for a deep dive.
Installation
# From marketplace
/plugin marketplace add rcrsr/claude-plugins
/plugin install checkmate@rcrsr
# Or load locally
claude --plugin-dir /path/to/checkmate
Automatic Configuration
The checkmate-init skill discovers your tools and creates .claude/checkmate.json. Done.
/checkmate:checkmate-init
Use checkmate-refresh to sync config with installed tools:
/checkmate:checkmate-refresh
Manual Configuration
Simple Project
{
"environments": [
{
"name": "root",
"paths": ["."],
"checks": {
".py": [
{ "name": "ruff", "command": "uv", "args": ["run", "ruff", "check", "$FILE"], "parser": "ruff" }
],
".ts,.tsx": [
{ "name": "eslint", "command": "pnpm", "args": ["exec", "eslint", "$FILE"], "parser": "eslint" }
]
}
}
]
}
Monorepo
{
"environments": [
{
"name": "frontend",
"paths": ["apps/web", "packages/ui"],
"checks": {
".ts,.tsx": [
{ "name": "eslint", "command": "pnpm", "args": ["exec", "eslint", "$FILE"], "parser": "eslint" }
]
}
},
{
"name": "api",
"paths": ["services/api"],
"checks": {
".py": [
{ "name": "ruff", "command": "uv", "args": ["run", "ruff", "check", "$FILE"], "parser": "ruff" }
]
}
}
]
}
First matching environment wins. Put specific paths before general ones.
Schema Reference
Environment:
| Field | Required | Description |
|---|
name | No | Descriptive label |
paths | Yes | Directories this environment covers |
exclude | No | Glob patterns to skip |
checks | Yes | Extension → check array mapping |
agents | No | Extension → agent name mapping |
Check:
| Field | Required | Description |
|---|
name | Yes | Display name in diagnostics |
command | Yes | Executable to run |
args | Yes | Arguments; $FILE = file path |
parser | No | Predefined name or regex object |
maxDiagnostics | No | Max errors shown (default: 5) |
_auto | No | Marks auto-discovered checks (boolean) |
Custom Parser
For tools without predefined parsers, use a regex with named capture groups:
{
"name": "golangci-lint",
"command": "golangci-lint",
"args": ["run", "$FILE"],
"parser": {
"pattern": ":(?<line>\\d+):(?<column>\\d+):\\s*(?<message>.+)",
"severity": "error"
}
}
Named groups: line, column, message, rule, severity.
JSONL Parser (recommended for Custom Tools)
For custom scripts, output JSON Lines for structured diagnostics:
