Running Charter in a pre-commit hook catches score regressions before they reach CI and before other team members have to deal with them. With --quiet, the hook is completely silent on a passing commit and only interrupts when there’s something to fix.
Exit code behavior
| Exit code | Meaning | Hook result |
|---|
0 | Score meets or exceeds threshold | Commit proceeds silently |
1 | Score below threshold | Commit blocked, summary printed |
--quiet mode is essential for hooks. On pass: completely silent. On fail: one summary line with the failing findings. Without --quiet, every commit prints the full scan output — which gets noisy fast.
Setup
hk (recommended)
husky
Plain shell
hk is a Git hook manager configured in hk.pkl and committed to the repo, so every contributor gets the same hooks automatically.Add a Charter hook to hk.pkl:hooks {
new Hook {
name = "charter"
run = "charter doctor --quiet --threshold 80"
}
}
hk install again after any changes to hk.pkl to update the installed hooks. If your repo uses husky, create or edit .husky/pre-commit:#!/bin/sh
charter doctor --quiet --threshold 80
chmod +x .husky/pre-commit
.husky/pre-commit to version control so all contributors share the same hook. No hook manager required. Create .git/hooks/pre-commit directly:#!/bin/sh
charter doctor --quiet --threshold 80
chmod +x .git/hooks/pre-commit
.git/hooks/ is not committed to version control. Plain shell hooks are local to your machine only. For team-wide enforcement, use hk or husky — both commit their configuration files to the repo.
Threshold guidance
Use the same threshold in your pre-commit hook as in CI. If they diverge, local commits can succeed but CI will fail — which creates friction and erodes trust in the hook.
# Matches a charter.yaml policy.threshold: 85
charter doctor --quiet --threshold 85
charter.yaml says, so hook and CI always agree automatically:
# Defers to policy.threshold or policy.profile in charter.yaml
charter doctor --quiet
charter.yaml has no policy section, Charter uses the built-in default of 80. 
