Docs

Hooks

Deterministic guardrails that fire regardless of what the AI decides to do.

Hooks are platform-triggered scripts that fire automatically on specific events. Unlike instructions in a rules file (which are advisory and ignorable), hooks run every time, guaranteed. The AI does not choose to run them. The platform runs them unconditionally.

This is the difference between a code style guide and a pre-commit hook. One is a suggestion. The other is enforcement.

The Four Hooks

Prime (prompt-submit)

Fires before every prompt. Injects git state, active issue, workflow position, and context graph output into the AI's context. The AI receives project context automatically before seeing the developer's message. No manual preamble needed.

Auto-approve

Fires before script execution. Approves FlyDocs skill scripts without manual confirmation. The AI runs transition.py or comment.py without the developer clicking "allow" each time. Scoped to skill script directories only. It does not auto-approve arbitrary commands.

Prefer-scripts

Fires before MCP tool calls. When both an MCP tool and a skill script can handle an operation, this hook nudges the AI toward the deterministic skill script. Reduces reliance on non-deterministic MCP calls and keeps context overhead low.

Post-edit

Fires after code changes. Auto-formats every file the AI modifies. The code is always formatted, every time, regardless of whether the AI remembered to format it. Changes are logged to an audit trail.

Hooks vs Rules vs Skills

Three layers serve three purposes:

Layer Nature When Used
Hooks Guaranteed, fires every time Things that must always happen (formatting, context injection, script approval)
Skills Methodological, structured guidance How to do things right (patterns, procedures, integrations)
Rules Advisory, AI should follow Preferences and conventions (naming, style, structure)

If something must happen every time without exception, it is a hook. If it is methodology the AI should follow with structured steps, it is a skill. If it is a preference or convention, it is a rule.

How Hooks Are Configured

Hooks are registered in the IDE's configuration file. For Claude Code, that is .claude/settings.json. Each hook specifies the event it triggers on, an optional matcher pattern, and the script it runs:

.claude/settings.json 
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prompt-submit.py",
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/auto-approve.py",
            "timeout": 5
          }
        ]
      },
      {
        "matcher": "mcp__linear.*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prefer-scripts.py",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/post-edit.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

The hook scripts themselves live in .flydocs/hooks/:

Directory Structure 
.flydocs/hooks/
├── prompt-submit.py     # Prime hook — context injection
├── auto-approve.py      # Auto-approve FlyDocs skill scripts
├── prefer-scripts.py    # Redirect MCP calls to skill scripts
└── post-edit.py         # Format code, log to audit trail

These scripts are installed by FlyDocs during setup. They are small, focused, and readable. You can inspect exactly what each hook does by reading the Python files directly.

Event Types

Event Platform Name When It Fires
UserPromptSubmit Before prompt processing Every time the developer sends a message
PreToolUse Before a tool is invoked Before Bash commands, MCP calls, or other tool use
PostToolUse After a tool completes After file edits, writes, or other tool actions

Matchers narrow which tool invocations trigger a hook. "Bash" matches Bash commands. "Edit|Write" matches file modifications. "mcp__linear.*" matches Linear MCP tool calls. An empty matcher matches everything.

The CI/CD Analogy

A CI pipeline runs tests whether or not the developer remembers to. It does not trust the developer to always run tests before pushing. It enforces the rule at the infrastructure level.

Hooks do the same thing for AI-assisted development. They do not trust the AI to always format code, always inject context, or always use the right scripts. They enforce it at the platform level. The AI cannot opt out.

Related Concepts