You completed a long Claude Code session and are ready to commit everything. But wait! You still need to run all the pre-commit checks (linting, type-checking, formatting). Now you spend many iterations getting everything fixed, and it gets messy—you're also dealing with potential regressions from refactoring.
Well, no longer. Checkmate immediately checks Claude Code's work after each file modification. It uses your existing toolchain and configuration, forcing Claude Code to assess and correct issues immediately, so they don't accumulate, resulting in clean commits.
This simple tool is now a key foundation of my workflow and completely eliminated time-consuming and token-wasting clean-up work, which sometimes could take multiple iterations lasting minutes.
How it Works
Checkmate is a simple plugin that executes a script after each file modification. The script determines whether the modified file path matches the checkmate configuration in your project and runs all configured tools in order (for example: format check, linting, then type checking). If there are failures, the script reports a "block" back to Claude Code with all the diagnostics included, causing Claude Code to fix the issue immediately.
Setup
Setup is trivial. First install the plugin:
# From marketplace
/plugin marketplace add rcrsr/claude-plugins
/plugin install checkmate@rcrsr
Then configure your project with:
/checkmate:checkmate-init
The initialization skill will explore your codebase, identify your stack, and create a configuration for your project with all the tools correctly set up. It will even work with multi-lingual monorepos, automatically detecting your language and folder-specific environments:
During the flow, you can customize or add to your setup if anything was missed.
The configuration will be written to .claude/checkmate.json. You can always edit and adjust the configuration directly or use /checkmate:checkmate-refresh to apply any changes to your environment.
Usage
Now, every time Claude Code modifies your files, Checkmate will run any configured tests (or ignore excluded or skipped files) and report back any issues that Claude Code will fix in the next turn:
That's pretty much it! Your commits will be substantially cleaner after your next long session.
Advanced Configuration
Checkmate is smart about discovering your toolchain. During initialization, it scans your project for configuration files and package manifests, then sets up the appropriate checks automatically. A TypeScript project with Prettier gets tsc and prettier checks. A Python project using Ruff gets ruff check and ruff format. It even handles polyglot monorepos—detecting that your backend/ folder needs Python linting while frontend/ needs ESLint.
Beyond the common tools (ESLint, TypeScript, Prettier, Biome, Ruff, shellcheck, and others), you can add your own checks. Checkmate understands several output formats out of the box, or you can supply a custom regex for parsing errors. I prefer my custom checks to output JSONL—one JSON object per line with file, line, and message fields—which Checkmate parses natively.
Reviewer Subagents
If you use specialized subagents for implementation, you can configure reviewer subagents that trigger automatically after an agent completes. For example, you could have a code-reviewer triggered after a matching engineer task.
Try it on your next session and watch commit cleanups disappear! See the Checkmate GitHub repo for complete documentation.
Common Questions
Why am I getting "hook returned blocking errors" twice?
This is a Claude Code quirk. When a hook returns blocking errors, the message appears twice even though the hook was only invoked once. Just ignore the duplicate message.
Why not just use Claude Code's built-in LSP plugins?
The LSP plugins work the same, but they may not use your toolchain or your configuration. They are also limited to just type-checking. Checkmate provides a framework for customizations and extensions.
Why can't Checkmate apply fixes with "--fix"?
This would mess with Claude Code's internal state and also introduce unintended side effects. Sometimes, Claude Code may add code non-atomically, like adding a new import before adding the code that uses it. Auto-fixing would remove the import before Claude Code has the opportunity to add the new code.
Top comments (0)