> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-Commit Hook

> Sync code knowledge into ModusBrain on every commit.

# 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:

| Code                | What it catches                                                       |
| ------------------- | --------------------------------------------------------------------- |
| `MISSING_OPEN`      | File doesn't start with `---`                                         |
| `MISSING_CLOSE`     | No closing `---` before first heading                                 |
| `YAML_PARSE`        | YAML failed to parse (syntax or structure)                            |
| `SLUG_MISMATCH`     | `slug:` in frontmatter doesn't match path-derived slug                |
| `NULL_BYTES`        | Binary corruption (`\x00`) anywhere in the content                    |
| `NESTED_QUOTES`     | `title: "outer "inner" outer"` shape that breaks YAML                 |
| `NON_STRING_FIELD`  | `title`/`type`/`slug` is an unquoted non-string scalar (`title: 123`) |
| `EMPTY_FRONTMATTER` | `---` ... `---` with nothing meaningful between                       |

## Install

For all registered sources that are git repos:

```bash theme={null}
modusbrain frontmatter install-hook
```

For one source:

```bash theme={null}
modusbrain frontmatter install-hook --source <id>
```

For force-overwrite of an existing pre-commit hook (writes a `.bak`):

```bash theme={null}
modusbrain frontmatter install-hook --force
```

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:

```bash theme={null}
git commit --no-verify
```

This skips ALL pre-commit hooks. Use sparingly — the next time the user
runs `modusbrain doctor`, the issues will surface.

## Uninstall

```bash theme={null}
modusbrain frontmatter install-hook --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

```
agent writes a page         git commit                 doctor scan
       ↓                          ↓                          ↓
[source content]   →  [pre-commit hook validates]   →  [frontmatter_integrity check]
       ↓                          ↓                          ↓
  raw file on disk       blocks malformed commits     surfaces existing issues
                                                             ↓
                                                  `modusbrain frontmatter validate
                                                   <source-path> --fix`
                                                   (writes .bak backups)
```

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.