Hooks Reference

KMGraph registers shell scripts with Claude Code's hook system to automate knowledge capture across the session lifecycle. Hooks are configured in hooks/hooks.json and executed by the Claude Code harness — not by the agent.

Lifecycle Events

Event	When it fires	Matcher support
SessionStart	Once, when a Claude Code session begins	No
PreToolUse	Before each tool call	Yes — regex on tool name + input
PostToolUse	After each tool call completes	Yes — regex on tool name
Stop	When the agent stops or the session ends	No
Notification	On any Claude Code notification event	No

Hooks with a matcher field fire only when the tool name (and optionally the tool input JSON) matches the provided regex. An empty matcher string ("") matches every invocation of that event.

hooks.json Structure

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<regex or empty string>",
        "hooks": [
          {
            "type": "command",
            "comment": "<human-readable description>",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/<script>.sh",
            "timeout": <seconds>
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} is resolved by the Claude Code harness to the absolute path of the KMGraph plugin directory. All scripts receive tool input JSON on stdin for PreToolUse and PostToolUse events.

Scripts Invoked by Hooks

Script	Event	Matcher	Enabled by default	What it does
hooks-master.sh	SessionStart	(all)	Yes	Validates KG config and MCP server build; displays recent lessons (last 7 days) from active and personal KGs; checks MEMORY.md staleness and diffs since last session; auto-switches active KG if autoSwitch: true and CWD matches a different project
post-tool-lesson-check.sh	PostToolUse	Write|Edit	Yes	Scans tool input for lesson-worthy keywords (fix, solved, debug, pattern, etc.); suppresses on docs/, .git/, and .md-only writes; surfaces a prompt to run /kmgraph:capture-lesson
platform-file-change-check.sh	PostToolUse	Write|Edit	Yes	Detects writes to platform config files (CLAUDE.md, GEMINI.md, .cursorrules, copilot-instructions.md, etc.); prompts the user to consider syncing other platform files via /kmgraph:setup-platform
plan-mirror.sh	PostToolUse	Write	Yes	Detects writes to ~/.claude/plans/; copies the file to docs/plans/ in the active KG project root; exits silently if the target directory does not exist
pre-commit-knowledge-gate.sh	PreToolUse	Bash.*git commit	Yes	Intercepts plain git commit calls (skips --amend and --no-verify); checks staged files for lesson-worthy source types (src/, *.ts, *.py, *.sh, etc.); advisory prompt only — does not block the commit
session-end-prompt.sh	Stop	(all)	Yes	Checks for open plan tasks, draft/proposed ADRs, and recent lesson-worthy commits without a captured lesson; displays a summary prompt; uses a /tmp flag to suppress duplicate output within the same session
notification-dispatch.sh	Notification	(all)	No (opt-in)	Forwards the notification text to a configured webhookUrl in kg-config.json; exits silently if webhookUrl is absent; network failures never block the hook

Enabled vs Disabled by Default

All scripts are registered in hooks.json and active by default, with one exception:

Script	Default state	How to activate
notification-dispatch.sh	Disabled (no-op)	Add "webhookUrl": "https://..." to ~/.claude/kg-config.json

The other six scripts are always active once KMGraph is installed. Individual hooks can be removed from hooks.json to disable them permanently, or their timeout values can be adjusted to control how long each script may run before the harness terminates it.

Script Locations

All hook scripts reside in scripts/ relative to the plugin root. Additional scripts in that directory (fuzzy-search-archive.sh, install-vscode.sh, prepare-mcp.sh, validate-plugin.sh) are invoked by installer and CLI commands, not by the hook system.

Exit Code Conventions

Exit code	Meaning
0	Success or non-blocking warning (session continues normally)
1	Blocking error — used only by hooks-master.sh for unrecoverable config failures

PreToolUse hooks that exit 0 allow the tool call to proceed. A non-zero exit from a PreToolUse hook blocks the tool call; KMGraph's pre-commit-knowledge-gate.sh always exits 0 because it is advisory only.