Professional hook management system for Claude Code - TypeScript-based validation, quality checks, and hook management across environments.

🎯 Essential Built-in Hooks - Pre-built validation and quality hooks ready to use
🔧 Hook Management Tool - Easy add/remove hooks across different Claude environments
📁 Multi-Environment Support - Manage hooks for local, global, project, and team settings
🛡️ Settings Validation - Automatic validation when loading/saving hook configurations
✅ CLI Validation Command - claude-hooks validate to check settings files
⚡ TypeScript-Powered - Full type safety with modern JavaScript features
🎮 Interactive CLI - claude-hooks command for all hook management needs

npm install -D claude-code-hooks-cli

npm install -g claude-code-hooks-cli
claude-hooks init

When you run claude-hooks init:

1. Choose setup mode:

How would you like to set up hooks?

❯ Quick setup (recommended defaults)
  Custom setup (choose your hooks)

2. Select where to save settings:

Where would you like to create the settings file?

❯ Project (.claude/settings.json) - Team hooks, committed to git
  Global (~/.claude/settings.json) - Your default hooks
  Local (.claude/settings.local.json) - Personal hooks, git ignored

That's it! Your hooks are now protecting your Claude Code sessions.

For custom hook configuration, use the interactive manager:

claude-hooks manage

Location Selection Screen:

Claude Hooks Manager

──────────────────────────────────────────────────
Hook Name                     Calls      Last Called
──────────────────────────────────────────────────
typescript-check              12         2 minutes ago
code-quality-validator        8          5 minutes ago
check-package-age            3          1 hour ago
──────────────────────────────────────────────────

↑/↓: Navigate  Enter: Select  Q/Esc: Exit

❯ Project (.claude/settings.json) (3 hooks) - Team hooks, committed to git
  Local (.claude/settings.local.json) (0 hooks) - Personal hooks, git ignored
  Global (~/.claude/settings.json) (0 hooks) - Your default hooks
  ──────────────
  📋 View recent logs
  📊 Tail logs (live)
  ──────────────
  ✕ Exit

Hook Selection Screen:

Hook Manager

↑/↓: Navigate  Enter: Toggle & Save  A: Select all  D: Deselect all  Q/Esc: Quit

❯◉ typescript-check                        (PreToolUse)
 ◉ code-quality-validator                  (PostToolUse)
 ◉ check-package-age                       (PreToolUse)
 ◯ lint-check                              (PreToolUse)
 ◯ test-check                              (PreToolUse)
 ◯ task-completion-notify                  (Stop)

──────────────────────────────────────────────────────────────────────────────

Description: TypeScript type checking before git commits

All hooks run directly from the npm package via TypeScript commands. Your .claude/settings.json will contain commands like:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "npx claude-code-hooks-cli exec stop-validation"
      }]
    }]
  }
}

• typescript-check - Validates TypeScript code for type errors
• lint-check - Runs ESLint/Prettier checks on your code
• test-check - Executes your test suite to ensure code quality
• code-quality-validator - Enforces clean code standards on file edits

• check-package-age - Prevents installation of outdated npm/yarn packages
• task-completion-notify - Notifies when tasks are completed

The hook manager can now automatically discover hooks defined in your project! Create a .claude/hooks.json file to share hook templates with your team:

{
  "project-lint": {
    "event": "PreToolUse",
    "matcher": "Bash",
    "pattern": "^git\\s+commit",
    "description": "Run project-specific linting rules",
    "command": "./scripts/lint.sh"
  },
  "security-scan": {
    "event": "PreToolUse",
    "matcher": "Bash",
    "pattern": "^npm\\s+(install|i)",
    "description": "Scan dependencies for vulnerabilities",
    "command": "./scripts/security-check.sh"
  }
}

These hooks will automatically appear in the hook manager with a [project] label!

Run claude-hooks list to see all available hooks.

Initialize Claude hooks - TypeScript-powered interactive setup.

Interactive mode (default):

1. First prompts for setup mode:

   • Quick setup - Installs recommended hooks (4 defaults)
   • Custom setup - Opens interactive manager to add/remove hooks

2. Then prompts for location (shows existing hook counts)

Direct mode with --level <level>:

• Goes straight to quick setup at specified location
• project - .claude/settings.json (recommended)
• local - .claude/settings.local.json
• global - ~/.claude/settings.json

Interactive hook manager - TypeScript-based configuration interface.

Same as running init and choosing "Custom setup". Use this when you want to skip the setup mode prompt.

Show all available hooks with descriptions (TypeScript compiled).

Display hook performance statistics and success rates.

View hook execution logs. Use --follow for live monitoring.

Validate hook settings files - Ensures configurations are properly structured.

Validates JSON syntax, hook structure, event names, tool matchers, and regex patterns.

# Validate all settings files
claude-hooks validate

# Validate specific file
claude-hooks validate claude/settings.json

# Show detailed validation information
claude-hooks validate -v

The validator checks:

• ✅ Valid JSON syntax and structure
• ✅ Correct event names (PreToolUse, PostToolUse, Stop)
• ✅ Valid tool matchers (Bash, Write, Edit, etc.)
• ✅ Proper regex pattern syntax
• ✅ Required fields and types
• ✅ Logging configuration (if present)

Execute a specific hook. This is used internally by Claude Code.

Note: All commands are also available with the full name claude-code-hooks-cli

• typescript-check - TypeScript type checking before git commits
• lint-check - Code linting (ESLint, etc.) before git commits
• test-check - Run test suite before various operations
• code-quality-validator - Enforces clean code standards after file edits
• check-package-age - Prevents installation of outdated npm/yarn packages
• task-completion-notify - System notifications when Claude finishes (Stop event)

You can discover project-specific hooks by creating .claude/hooks.json in your project.

• Project (.claude/settings.json) - Shared with your team, committed to git (recommended)
• Local (.claude/settings.local.json) - Personal settings, git ignored
• Global (~/.claude/settings.json) - Applies to all your projects

• 🔍 Hook Discovery System - Automatically finds project hooks in .claude/hooks.json
• 🏷️ Hook Source Labels - Visual indicators for built-in, project, and custom hooks
• 📂 Project Hook Templates - Share team-specific hooks via version control
• 🛡️ Template Validation - Automatic validation of discovered hook templates
• 🎯 Relative Path Support - Project hooks can use relative script paths

• 🎯 Simplified hook system - Consolidated to essential validation hooks
• 🛡️ Improved error handling - Better exit codes and error messages
• 📁 Common validation library - Shared functionality for consistency
• 🚀 Enhanced CLI commands - Better hook management experience
• 🧹 Removed deprecated hooks - Cleaner, more focused hook set
• ✅ Hook Settings Validation - Automatic validation prevents invalid configurations
• 📋 Validate Command - New claude-hooks validate command for checking settings

✅ TypeScript-powered - Full type safety and modern JavaScript features
✅ Always up-to-date - Just run npm update claude-code-hooks-cli
✅ No file management - Everything runs from node_modules
✅ Version locked - Consistent behavior via package.json
✅ Works everywhere - Compatible with npm, yarn, pnpm
✅ Interactive CLI - Modern command-line interface with prompts
✅ Project-local config - Uses claude/ directory (not ~/.claude)

• Hook Package Manager - Discover and import hooks from GitHub repositories
• Advanced Validation System - Comprehensive hook validation with security checks and auto-fix
• Task Completion Enforcement - Hooks that prevent Claude from exiting before completing all tasks
• Package Similarity Detection - Prevents installing duplicate packages by detecting similar existing dependencies
• Method Similarity Indexer - Prevents duplicate code by detecting similar methods across the repository
• Continuous UI Improvement - Automated UI enhancement using visual feedback and design analysis
• Prompt Optimization System - Continuous AI prompt refinement based on conversation metrics
• Shiny Windows Delight - Perpetual UI enhancement system for adding delightful micro-interactions

• Repo-Based Hook Discovery - Automatically find and catalog hooks in visited repositories
• Hook Marketplace - Community-driven hook sharing and rating system
• AI-Powered Hook Suggestions - Recommend hooks based on project analysis
• Multi-Armed Bandit Testing - A/B test different hook configurations automatically
• Visual Hook Designer - GUI for creating hooks without coding

See our ideas documentation for detailed specifications of upcoming features.

This project uses TypeScript. To develop:

npm install
npm run dev    # Watch mode
npm run build  # Compile TypeScript

Source files are in src/ and compiled to lib/.

Contributions are welcome! This is a TypeScript project with modern tooling.

MIT