Claude Hooks

Claude Hooks is an event-driven automation system built into Claude Code that executes shell scripts in response to specific events during development workflows. Unlike Skills which provide suggestions, Hooks provide enforcement - they're actual executable scripts that can validate, block, inject context, or trigger actions based on what's happening in your coding session.

Hooks transform Claude Code from an AI assistant into a programmable development environment where you define rules, standards, and integrations that automatically execute without relying on the LLM's understanding.

Key Features

1. Five Hook Event Types

Claude Code supports hooks for different lifecycle events: UserPromptSubmit (when prompts are sent), PreToolUse (before tool execution), PostToolUse (after tool execution), Stop (before session ends), and SubagentStop (when subagents complete). Each event provides specific context and control points.

2. Exit Code Control Mechanism

Hooks communicate through exit codes with special meanings: exit 0 continues normally, exit 1 warns but allows continuation, and exit 2 blocks and forces Claude to fix issues. This creates a "suggest + enforce" system where hooks can actually prevent bad code from being written or committed.

3. Real Shell Script Execution

Hooks are actual bash/shell scripts that run with your system permissions, not dependent on LLM interpretation. Run linters, tests, deployments, API calls, database queries, or any command-line tool as part of your AI-assisted workflow.

4. Bidirectional Communication

Hook scripts can send messages back to Claude through stdout/stderr, injecting context, validation results, or instructions directly into the conversation. Claude treats hook feedback as user input, creating a feedback loop.

5. Plugin-Based Distribution

Hooks are packaged and shared as part of Plugins alongside Skills and MCP servers. Install entire workflow packages with /plugin install to get pre-configured validation, testing, and deployment automation.

6. Environment and Context Access

Hooks receive environment variables, tool parameters, file paths, and session context. Access current git branch, changed files, tool names, arguments, and more to make intelligent decisions.

Use Cases

Who Should Use Claude Hooks?

• DevOps Engineers: Automate deployment validation, infrastructure checks, and environment setup
• Quality Assurance Teams: Enforce testing requirements, code coverage thresholds, and lint standards
• Security Teams: Scan for vulnerabilities, validate permissions, prevent secret commits
• Development Teams: Standardize commit messages, PR requirements, and code review processes
• Enterprise Organizations: Enforce compliance policies, audit trails, and governance rules

Problems It Solves

1. Manual Quality Gates: Eliminate forgetting to run tests or linters - hooks enforce them automatically before commits or session ends
2. Context Loss: Inject current git status, environment info, or project-specific details into every Claude interaction
3. Security Risks: Prevent accidental commits of secrets, access to sensitive files, or destructive operations
4. Integration Gaps: Bridge Claude Code with your existing tools - Slack, JIRA, monitoring systems, CI/CD pipelines
5. Team Standards Enforcement: Ensure everyone follows the same coding standards, commit conventions, and workflows

Hook Event Types and Examples

UserPromptSubmit Hook

Triggers: When the user submits a prompt to Claude

Common Uses:

• Inject git status and current branch information
• Add project-specific context or conventions
• Log user requests for analytics
• Security screening of user input

Example:

#!/bin/bash
# hooks/user-prompt-submit.sh

BRANCH=$(git branch --show-current)
echo "📍 Current branch: $BRANCH"

if [[ -n $(git status --porcelain) ]]; then
  echo "📝 You have uncommitted changes"
fi

exit 0

PreToolUse Hook

Triggers: Before any Claude Code tool executes (Read, Write, Edit, Bash, etc.)

Common Uses:

• Validate file permissions before reads/writes
• Block access to sensitive files or directories
• Rate limit expensive operations
• Log tool usage patterns

Example:

#!/bin/bash
# hooks/pre-tool-use.sh

if [[ "$TOOL_NAME" == "Read" ]] && [[ "$FILE_PATH" =~ \.env|credentials|secret ]]; then
  echo "⚠️ Blocked: Attempted to read sensitive file $FILE_PATH"
  exit 2  # Block execution
fi

exit 0

PostToolUse Hook

Triggers: After a tool call completes successfully

Common Uses:

• Validate tool outputs
• Send notifications for specific actions
• Collect metrics and analytics
• Trigger follow-up automation

Example:

#!/bin/bash
# hooks/post-tool-use.sh

if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$COMMAND" =~ deploy ]]; then
  curl -X POST $SLACK_WEBHOOK \
    -d '{"text":"🚀 Deployment triggered by Claude Code"}'
fi

exit 0

Stop Hook

Triggers: Before Claude Code prepares to exit or complete a session

Common Uses:

• Run final quality checks (lint, tests, type checking)
• Ensure all changes are committed
• Cleanup temporary files
• Generate session reports

Example:

#!/bin/bash
# hooks/stop-hook.sh

echo "🔍 Running final quality checks..."

if ! npm run lint; then
  echo "❌ Lint failed. Please fix before exiting."
  exit 2  # Force Claude to fix issues
fi

if ! npm test; then
  echo "❌ Tests failed. Please fix before exiting."
  exit 2
fi

echo "✅ All checks passed!"
exit 0

SubagentStop Hook

Triggers: When a subagent completes its delegated task

Common Uses:

• Review subagent work quality
• Aggregate results from multiple subagents
• Validate delegated task completion
• Log subagent performance

Integration with Claude Code Ecosystem

Skills + Hooks = Complete Workflow Automation:

• Skills provide knowledge and suggestions (What & How to do)
• Hooks enforce rules and standards (Must & Must Not do)
• Together they create "suggest + enforce" system

Plugin Packaging:

• Hooks are distributed as part of Plugins
• Plugins bundle: Skills + Hooks + MCP servers + Commands
• Install complete workflows: /plugin install @team/code-standards

MCP Integration:

• Hooks can validate MCP tool calls
• PreToolUse/PostToolUse intercept external tool operations
• Ensure third-party integrations follow your policies

Layered Architecture:

Advantages & Unique Selling Points

Compared to Competitors:

1. True Enforcement vs Suggestions: Unlike Cursor/Copilot which only suggest, hooks actually prevent bad actions through exit codes
2. Real Code Execution: Hooks are actual shell scripts, not LLM-dependent configurations that might be ignored
3. Lifecycle Coverage: Hooks at every stage from prompt to tool execution to session end
4. Open Distribution: No approval process - create and share plugins freely unlike vendor marketplaces
5. Standards-Based: MCP protocol enables interoperability across tools and platforms

What Makes It Stand Out:

• Programmable quality gates that AI cannot bypass
• Complete control over AI behavior through executable scripts
• Integration with any command-line tool or API
• Community-driven plugin ecosystem with 500+ plugins
• No vendor lock-in - scripts are yours forever

Best Practices

1. Clear Exit Codes: Use exit 0 for success, exit 1 for warnings, exit 2 to force fixes - be intentional about control flow
2. Descriptive Messages: Echo clear messages explaining what hooks are doing and why they're blocking
3. Idempotent Scripts: Ensure hooks can run multiple times safely without side effects
4. Error Handling: Include try-catch, validate inputs, handle edge cases gracefully
5. Security First: Never hardcode secrets, validate all inputs, use minimal permissions
6. Modular Design: Create focused hooks for specific purposes rather than monolithic scripts
7. Test Thoroughly: Test hooks with various scenarios before deploying to team

Frequently Asked Questions

What permissions do hooks have?

Hooks run with your user's shell permissions. They can access files, run commands, and make network requests just like any script you'd run manually.

Can hooks access sensitive data?

Yes, which is why you should review hook scripts before installing plugins. Only use hooks from trusted sources or write your own.

What happens if a hook fails?

Depends on the exit code: exit 1 logs a warning but continues, exit 2 blocks the action and forces Claude to fix the issue before proceeding.

Can I disable hooks temporarily?

Yes, you can disable specific hooks or entire plugins through Claude Code settings without uninstalling them.

Do hooks work offline?

Yes, hooks are local shell scripts that execute regardless of internet connectivity. Only external API calls in hooks require network access.

How do I debug hook scripts?

Hook stdout/stderr appears in Claude's conversation. Add echo statements for debugging, or run hooks manually from command line to test.

Real-World Examples

Quality Gate Enforcement

Sionic AI runs 1000+ ML experiments daily. Their Stop hooks validate GPU configurations, framework parameters, and prevent known failure paths before launching expensive training runs.

Security Scanning

PreToolUse hooks scan for hardcoded secrets, API keys, or credentials before allowing file writes or commits, preventing accidental exposure.

Team Workflow Standardization

PostToolUse hooks enforce commit message conventions, run automated code formatting, and trigger CI/CD pipelines ensuring consistency across the team.

Integration Automation

Hooks send Slack notifications when deployments occur, update JIRA tickets when code is committed, and log metrics to monitoring systems automatically.

Alternatives

If Claude Hooks isn't the right fit, consider:

• GitHub Actions: Better for cloud-based CI/CD but not integrated with local AI workflow
• Git Hooks: Similar concept but only for git events, not AI tool interactions
• Make/Task Runners: Good for manual workflows but lack AI integration and event triggers
• Cursor Rules: Configuration-based but lacks enforcement power and executable scripts

Conclusion

Claude Hooks represents a fundamental shift in how developers work with AI assistants. By providing executable, enforceable rules rather than just suggestions, hooks ensure your AI collaborates within your team's standards and integrates seamlessly with existing tools and workflows.

Whether enforcing code quality, preventing security issues, automating deployments, or integrating with your infrastructure, hooks give you programmable control over every aspect of your AI-assisted development workflow without relying on the LLM to understand and follow your rules.