Hooks
Event-triggered automation that activates a specific agent on a lifecycle event (session start, file save, pre-commit, pre-push, post-merge, CI failure). Hook definitions live in the canonical hooks/ content (bundled npm package) and are emitted into each supported adapter's native hook system during hatch3r sync.
Hooks are non-interactive: the configured agent runs with its standard tool allowlist and writes back into the editor's hook output channel. Disable a hook per-project by setting enabled: false in .hatch3r/hooks/{id}.customize.yaml.
Hook Reference
| Hook | Event | Agent invoked | Purpose |
|---|---|---|---|
| session-start | New coding session opens | learnings-loader | Index .hatch3r/learnings/, surface up to 5 relevant entries scoped to recently changed files; silent when nothing matches. |
| file-save | TS/JS/TSX/JSX file saved (configurable globs) | context-rules | Match the saved path against the canonical rules/ content (always-apply plus glob-scoped) and emit non-blocking inline suggestions for violations; 2 s debounce. |
| pre-commit | Before commit, on staged TS/JS files | lint-fixer | Run the project linter and formatter on staged files, auto-fix what is fixable, re-stage the fixes, report unfixable violations with file and line. |
| pre-push | Before push, on outgoing commits | security | Scan the outgoing diff for high-entropy strings and known secret patterns (API keys, tokens, private keys, .env, *.pem); block the push on detection. |
| post-merge | After a merge completes | ci-watcher | Poll the CI pipeline for the merge SHA with exponential backoff (30 s -- 5 min, 15 min timeout) and report failures with a root-cause summary. |
| ci-failure | CI workflow run reports failure | ci-watcher | Fetch the failed run logs, classify the failure (build, test, lint, type, dependency, infra, timeout, permission), produce a root-cause hypothesis with a suggested fix. |
| review-loop-cap | Reviewer about to spawn another fixer iteration | reviewer | Block fixer-spawn past the configured review-loop iteration ceiling via a .review-loop.json checkpoint, preventing unbounded review-fix cycles. |
Configuration
Hook frontmatter exposes per-hook knobs. Common fields:
globs-- restrict which files trigger the hook (file-save,pre-commit).debounceMs-- collapse rapid events (file-save, default 2000).timeoutMinutes-- cap the agent's wall time (post-merge, default 15).blockOnWarnings-- escalate warnings to blocking (pre-commit, defaultfalse).autoRetryFlaky-- single retry on infrastructure failures (ci-failure).scanFullHistory-- audit full history instead of outgoing diff (pre-push).
Override defaults per-project in .hatch3r/hooks/{id}.customize.yaml. See Customization.
Adapter Support
Not every coding tool exposes a hook/event API. Of the 3 supported adapters, two emit hook files today:
| Adapter | Hook output |
|---|---|
| cursor | .cursor/hooks/* |
| claude | .claude/settings.json hook entries |
GitHub Copilot has no PreToolUse or pre-edit hook surface (hooks: false in ADAPTER_CAPABILITIES), so the Copilot adapter emits no hook files. Track the full picture in the Adapter Capability Matrix.
Canonical Location
Hook definitions live in the canonical hooks/hatch3r-{event}.md content (bundled npm package) with YAML frontmatter declaring id, type: hook, event, agent, and description:
---
id: pre-commit-lint-fixer
type: hook
event: pre-commit
agent: lint-fixer
description: Auto-fix lint and formatting issues before commit
globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
---
The body documents the agent's expected behavior, output format, and configuration knobs. hatch3r sync translates each file into the target adapter's native hook format and wraps it in a managed block so user edits outside the block are preserved.