Proctor
Learn from your AI —
don't rubber-stamp it.
Proctor quizzes you on your branch's changes before your AI assistant can push or merge — so you actually understand what shipped.
Free and open source (MIT). Works with Claude Code — CLI, desktop, web, and IDE — and GitHub Copilot in VS Code (agent mode).
AI writes faster than you can absorb.
It's easy to approve a diff you don't really understand — until it breaks in production and you can't explain it. Proctor makes understanding a required step, not an optional one, so you keep learning while you move fast.
A quiz stands between you and the push.
git push, or to merge into a protected branch like main or develop.On long-running branches, Proctor can also quiz you during development — every N commits or after a threshold of changed lines — so you learn as you go instead of facing one giant quiz at the end. Each quiz only covers changes since the last checkpoint.
What it gates #
Proctor blocks:
git push— always, except tag-only pushes (git push --tags), which point to existing commits rather than new code.- Merges and pulls into protected branches —
main,master,develop, andrelease/*by default (configurable). - Commits past a periodic threshold — only if you opt in with a commit interval or line-change limit.
It only gates operations inside your AI coding session — Claude Code or Copilot in VS Code (agent mode). Pushes and merges from a plain terminal, your IDE's git integration, or the GitHub UI are untouched — the point is to confirm you understand what the AI built, not to police every commit.
Track your progress #
Every quiz — pass, fail, or trivial skip — is logged locally to ~/.proctor/history.jsonl and persists across sessions. Run /proctor summary (optionally scoped to a branch) to see how you're doing:
/proctor summary
/proctor summary for feature/authThe summary shows:
- Overview — total quizzes, first-attempt pass rate, and a per-category breakdown (What / Why / Risk).
- Trouble spots — files and concepts you've missed repeatedly, with commit references so you can find the relevant code in your git history.
- Recent history — your last several quizzes with date, branch, operation, and outcome.
It all stays on your machine — nothing is uploaded.
Install #
The quickest way is npx — no clone, no global install, and it always pulls the latest version. Point it at a project, or use --global for every project:
# Claude Code
npx proctor-skill /path/to/your-project
npx proctor-skill --global
# Copilot in VS Code (agent mode) — add --copilot
npx proctor-skill --copilot /path/to/your-project
npx proctor-skill --copilot --globalIt copies the hook and skill files and wires up the config — into .claude/ for Claude Code, or .github/ for Copilot. To remove it, run npx proctor-skill uninstall /path/to/your-project (add --copilot for Copilot).
You can also add Proctor through the skills CLI:
npx skills add brandon-haugen/proctor-skillThat installs the /proctor skill only — not the hook that automatically blocks pushes and merges. To add the hook too, also run the installer:
npx proctor-skill /path/to/your-projectPrefer to clone? The GitHub repo has a git clone + install.sh option and the full details.
Configuration #
Everything is set through environment variables:
| Variable | Default | What it does |
|---|---|---|
PROCTOR_MODE | blocking | blocking = must pass the quiz; advisory = reminder only, doesn't block. |
PROCTOR_PROTECTED_BRANCHES | main,master,develop,release/* | Comma-separated branch patterns to gate from unreviewed merges. |
PROCTOR_COMMIT_INTERVAL | 0 (off) | Quiz every N commits on the branch. |
PROCTOR_CHANGE_THRESHOLD | 0 (off) | Quiz once N+ lines have changed since the last checkpoint. |
Checkpoints are content-based: passing a quiz records the commit plus a hash of the diff, and any real code change invalidates it — so you can't pass once and then push forever. Content-preserving rebases don't trigger a redundant quiz.
Actually understand your AI's code.
Proctor is free and open source. Grab it on GitHub and install in a minute.