Pre-flight & Post-flight Hooks

Pre-flight & Post-flight Hooks

Hooks allow you to integrate Claude Code deeply into your development workflow by executing scripts or commands at specific stages of the interaction lifecycle. By using hooks, you can enforce quality gates, automate repetitive tasks like formatting, and provide Claude with context-aware guidance before it even starts writing code.

Overview

Hooks are categorized into two types:

• Pre-flight Hooks: Executed before Claude processes a prompt or starts a task. Use these for environment checks, branch protection, or intelligent skill activation.
• Post-flight Hooks: Executed after Claude has performed an action or modified files. Use these for auto-formatting, running test suites, or updating documentation.

Configuration

Hooks are configured within your .claude/settings.json file. You can point to shell commands or specific script files (Node.js, Python, etc.) located in your .claude/hooks/ directory.

{
  "hooks": {
    "pre-flight": [
      ".claude/hooks/check-branch.sh",
      "node .claude/hooks/skill-eval.js"
    ],
    "post-flight": [
      "npm run lint:fix",
      "npm test -- --findRelatedTests {changedFiles}"
    ]
  }
}

Implementing Quality Gates

Quality gates ensure that Claude adheres to your project's standards. By failing a pre-flight hook (exiting with a non-zero code), you can prevent Claude from making changes that violate team policies.

Example: Branch Protection

Prevent Claude from making direct edits to the main or production branches:

#!/bin/bash
# .claude/hooks/check-branch.sh
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$CURRENT_BRANCH" == "main" ]; then
  echo "Error: Edits to the 'main' branch are restricted."
  exit 1
fi

Intelligent Skill Activation

The skill-eval.js engine (found in .claude/hooks/) is a specialized pre-flight hook designed to analyze the user's prompt and the current file context. It automatically suggests relevant "Skills" or "Agents" to Claude based on:

• Keywords: Triggers based on terms like "GraphQL", "UI", or "Testing".
• File Paths: Matches logic based on the directory Claude is currently working in (e.g., src/components).
• Regex Patterns: Identifies specific intents like "create a new component".

To enable this, register the evaluation engine in your settings:

{
  "hooks": {
    "pre-flight": ["node .claude/hooks/skill-eval.js"]
  }
}

Automated Post-flight Actions

Post-flight hooks are ideal for "cleaning up" after Claude has completed a task. This ensures that the generated code is immediately ready for a PR.

• Auto-Formatting: Run prettier or eslint --fix to ensure style consistency.
• Incremental Testing: Use tools like Jest's --findRelatedTests to run only the tests impacted by Claude's recent edits.
• Type Checking: Run tsc to verify that Claude's changes haven't introduced type regressions.

Environment Variables & Context

Hooks have access to environment variables provided by Claude Code, allowing you to build dynamic logic:

| Variable | Description | | :--- | :--- | | CLAUDE_CHANGED_FILES | A space-separated list of files modified during the current session. | | CLAUDE_PROMPT | The text of the user's original prompt (Pre-flight). | | CLAUDE_PROJECT_ROOT | The absolute path to the project root. |

Usage in a script:

// Accessing changed files in a post-flight Node.js hook
const changedFiles = process.env.CLAUDE_CHANGED_FILES;
if (changedFiles.includes('.tsx')) {
  console.log("React components changed. Triggering UI regression tests...");
}

Best Practices

1. Fail Gracefully: For non-critical hooks (like documentation sync), ensure the script exits with code 0 even on internal errors to avoid blocking Claude's workflow.
2. Performance: Keep hooks fast. Claude waits for pre-flight hooks to complete before responding.
3. Local vs. Global: Store project-specific hooks in .claude/hooks/ to ensure every team member using Claude Code benefits from the same automation.