Add project-checks hook

[jackyraimond]

Adds a PostToolUse hook that runs the formatter or linter a project already defines on the file Claude just edited, and hands failures back so they get fixed in the same turn instead of surfacing at commit time.

Opt-in per project

This hook does nothing until a project opts in, by having a .claude/project-checks.json — an empty {} is enough.

That gate is the main design decision here, and it is worth explaining. The hook executes commands defined by the repository it is looking at: npm run format runs whatever that project's package.json says it should. In a repo you wrote, that is exactly the point. In a repo you cloned to take a look at, it is somebody else's code running with your shell and your credentials, triggered by nothing more than Claude touching a file.

CONTRIBUTING.md rules out "anything downloaded or executed at runtime", and an always-on version of this hook would sit uncomfortably close to that line. Opt-in resolves it: opening an unfamiliar repository does nothing at all, and enabling it in your own is one command. Detection still does the work, so you grant permission once rather than writing commands.

What it runs

Source	Looks for	Runs
composer.json	cs-fix, csfix, ecs, php-cs-fixer, format, lint:fix, fix	composer run <script> -- <file>
package.json	format, fmt, lint:fix, lint-fix, prettier, lint	npm run <script> -- <file>
.pre-commit-config.yaml	exists	pre-commit run --files <file>
nothing		exits silently

One file, never the whole repo. Formatting everything because one line changed produces a diff nobody can review, which is why most format-on-write hooks end up removed.

Makefile auto-detection removed

The original detected fmt / format / lint-fix targets in a Makefile and ran make <target> — with no file argument. That runs over the entire repository, which is the exact outcome the "one file, never the whole repo" promise rules out. Worse, on a repo with pre-existing lint failures it would hand Claude errors about code it never touched, and Claude would try to fix them.

Makefile projects now set command explicitly:

{ "command": "make fmt-file FILE={file}" }

Other change

Invalid JSON in .claude/project-checks.json is now reported (exit 1, non-blocking) instead of being silently treated as absent. Someone wrote that file on purpose; silence would just be confusing.

Testing

./scripts/validate.sh and ./scripts/pr-policy.sh pass.

12 scenarios against fixture projects with stubbed composer / npm / pre-commit binaries, all passing:

Scenario	Expected	Result
Opted-in PHP project	composer run cs-fix -- src.php	✅
Same project, no config file	nothing	✅
enabled: false	nothing	✅
Invalid JSON config	error message, exit 1	✅
Opted-in JS project	npm run format -- app.ts	✅
Makefile with an fmt target	nothing (no auto-detect)	✅
command override	wins over detection	✅
Markdown file	skipped	✅
File that no longer exists	skipped	✅
Tool exits non-zero	exit 2, output on stderr	✅
Tool binary not installed	silent, exit 0	✅
Malformed hook payload	exit 0	✅

Review notes

The thing to weigh is the exit-2 path: a failing formatter sends its output back to Claude, which will act on it. That is the feature, but it means a project whose lint script reports pre-existing problems will send Claude chasing them. Scoping to a single file keeps that mostly contained, and dropping make removes the case where it was guaranteed not to be.

No network, no writes outside what the project's own tool does, and the only subprocess is the detected command itself, with a 60-second default timeout.

🤖 Generated with Claude Code