Skip to main content
A small set of git hooks — installed by tiny-brain init, managed with tiny-brain hooks — is the enforcement layer of the whole system. Everything else (plans, phases, reviews, the dashboard) is built on what they record. They divide cleanly into a gate, which runs before a commit is accepted, and a recorder, which runs after.

​
The gate — pre-commit and commit-msg

Everything that can reject a commit happens here, while the commit can still be stopped:
  • Checks — typecheck and lint run on every commit; the test suite runs for implementation commits (feat:/fix:) and is skipped for test: commits, whose new tests are supposed to fail.
  • Commit type — the conventional prefix (test:, feat:, fix:, refactor:, spike:, chore:, untracked:).
  • Tracking headers — tracked types must carry PRD:/Feature:/Task: (or Fix:/Task:) headers, and each Task: value must resolve to a real task by exact description match.
  • Pipeline position — a refactor: commit is only accepted while a review is active for the task.
A commit that fails any of these is rejected — the message tells you which check failed. See Troubleshooting for the common rejections and their fixes.

​
post-commit — the recorder

Runs after an accepted commit lands, and does the bookkeeping you never do by hand — it runs no checks (it can’t; the commit is already final):
  • attributes the commit to its task (via the Task: headers) and records its role — RED, GREEN, or review-refactor,
  • advances the task’s derived phase,
  • kicks off the adversarial review after an implementation commit (in repos with the review gate enabled).

​
Working with the hooks

tiny-brain hooks status     # what's installed
tiny-brain hooks install    # (re)install; --force to overwrite custom hooks
tiny-brain hooks uninstall
One rule matters above all: never --no-verify. Bypassing the hooks doesn’t just skip a check — it punches a hole in the record every derived view depends on. If a hook is blocking you incorrectly, that’s a bug to fix (start with tiny-brain doctor), not a gate to jump.