Charter — AI-Agent Readiness Scanner

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

All hook runners respect non-zero exit codes to block commits. No additional configuration is needed.

--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"
  }
}

Then install:

hk install

Run 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

Make it executable:

chmod +x .husky/pre-commit

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

Make it executable:

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.

Set an explicit threshold to match your CI gate:

# Matches a charter.yaml policy.threshold: 85
charter doctor --quiet --threshold 85

Or defer to whatever charter.yaml says, so hook and CI always agree automatically:

# Defers to policy.threshold or policy.profile in charter.yaml
charter doctor --quiet

If charter.yaml has no policy section, Charter uses the built-in default of 80.

Next steps

Run Charter in GitHub Actions

Enforce the same gate on every pull request.

Policy Profiles

Set one threshold for hook and CI so they always agree.

charter.yaml Reference

Configure policy at the repo root.

charter doctor

The scan command the hook runs.

​Exit code behavior

​Setup

​Threshold guidance

​Next steps

Run Charter in GitHub Actions

Policy Profiles

charter.yaml Reference

charter doctor

Exit code behavior

Setup

Threshold guidance

Next steps