Skip to main content

​
Pre-commit hook for brain repos (v0.22.4+)

modusbrain frontmatter install-hook installs a git pre-commit hook in your brain source’s repo that runs modusbrain frontmatter validate against staged .md and .mdx files. Malformed frontmatter blocks the commit. Bypass with git commit --no-verify.

​
What the hook catches

The same eight validation classes the frontmatter-guard skill and modusbrain doctor’s frontmatter_integrity subcheck report:

​
Install

For all registered sources that are git repos:
For one source:
For force-overwrite of an existing pre-commit hook (writes a .bak):
The hook lands at <source>/.githooks/pre-commit. If core.hooksPath is unset, the install also runs git config core.hooksPath .githooks so the hook is picked up without manual git config.

​
Bypass

Standard git escape hatch:
This skips ALL pre-commit hooks. Use sparingly — the next time the user runs modusbrain doctor, the issues will surface.

​
Uninstall

If a .bak was saved during install, it’s restored as the active hook. Otherwise the hook is removed cleanly.

​
Behavior on machines without modusbrain installed

The hook script checks for modusbrain on $PATH. When missing, it prints a one-line warning to stderr and exits 0 — commits aren’t blocked just because a developer hasn’t installed modusbrain locally. Once modusbrain is installed, the hook resumes blocking malformed pages.

​
For downstream agent forks

If your OpenClaw wraps modusbrain in a host repo that’s not the brain repo itself, you may want a separate hook strategy:
  • Brain repo IS the host repo (modusbrain skills + brain pages in one repo): install via modusbrain frontmatter install-hook as above.
  • Brain repo is a separate registered source (e.g. ~/brain registered as a source, host repo is ~/agent-fork): install in the brain repo only; agent-fork code doesn’t need this hook.
  • Brain repo is auto-generated (e.g. by a sync daemon writing to a bucket): skip the hook entirely; gate at the writer instead via import { writeBrainPage } from 'modusbrain/brain-writer' (planned in a later release; currently the CLI is the surface).

​
How it fits into the broader frontmatter pipeline

The hook is the write-time gate; doctor is the audit gate; the CLI is the fix tool. They share parseMarkdown(..., {validate:true}) as the single source of truth for what counts as malformed.