claude-hooks-manager
Advanced tools
A comprehensive hook management system for Claude that enforces coding standards, maintains consistency, and automates workflow tasks
📢 Important Notice for Existing Users
This project has been renamed from
claude-code-hookstoclaude-hooks-managerto better reflect its purpose as a management tool for Claude hooks.Migration Instructions:
# Uninstall old package npm uninstall -g claude-code-hooks # Install new package npm install -g claude-hooks-managerThe CLI command
claude-hooksremains unchanged.
A comprehensive hook management system for Claude that enforces coding standards, maintains consistency, and automates workflow tasks across all projects.
We're excited to announce our groundbreaking integration with Context Forge - the industry-leading CLI tool for AI-ready project scaffolding. This integration solves one of the biggest challenges in AI-assisted development: context loss during conversation compaction.
Context Forge is a powerful CLI tool that implements Andre Karpathy's context engineering principles to generate comprehensive documentation structures. It creates AI-optimized project scaffolds with:
Install Context Forge:
npm install -g context-forge
Quick start a new project:
context-forge init
During extended coding sessions, Claude Code's context window fills up and performs "compaction" to continue. This causes:
Our Context Forge hooks provide automatic context recovery after compaction:
# Install Context Forge hooks
cd hooks/context-forge
./install-context-forge-hooks.sh
# Or manually add to ~/.claude/settings.json
Learn more about Context Forge integration →
Combine Context Forge and Claude Hooks Manager for the ultimate AI-assisted development experience:
Start with Context Forge
npm install -g context-forge
context-forge init
Install Claude Hooks Manager
npm install -g claude-hooks-manager
claude-hooks install
Enable Context Forge Integration
cd hooks/context-forge
./install-context-forge-hooks.sh
Develop with Confidence
This powerful combination transforms AI-assisted development from a novelty into a production-ready workflow that maintains quality and consistency across extended development sessions.
# Install the package globally
npm install -g claude-hooks-manager
# Run the installation script to copy hooks to Claude directory
claude-hooks-install
# Clone the repository
git clone https://github.com/webdevtodayjason/claude-hooks.git
cd claude-hooks
# Run the install script
chmod +x install.sh
./install.sh
Create the hooks directory:
mkdir -p ~/.claude/hooks
Copy all Python hooks:
cp hooks/*.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.py
Update your Claude settings:
~/.claude/settings.json exists, merge the hooks configuration from settings.example.jsonsettings.example.json to ~/.claude/settings.jsonRestart Claude for the hooks to take effect
When installed via npm, you get access to the powerful claude-hooks CLI:
# Launch interactive menu (NEW!)
claude-hooks
# Install hooks to Claude directory
claude-hooks install
claude-hooks-install # Also available as separate command
# List all available hooks with descriptions
claude-hooks list
# Get detailed information about a specific hook
claude-hooks info <hook-name>
# Example: claude-hooks info secret-scanner
# Check installation status (NEW!)
claude-hooks status
# Run diagnostics to check setup (NEW!)
claude-hooks doctor
# Initialize hooks for current project (NEW!)
claude-hooks init
# Hook Management Commands (NEW!)
claude-hooks enable <hook-name> # Enable a disabled hook
claude-hooks disable <hook-name> # Disable a hook temporarily
claude-hooks create <hook-name> # Create a new custom hook
claude-hooks edit <hook-name> # Edit an existing hook
claude-hooks remove <hook-name> # Remove a hook permanently
claude-hooks config # Edit Claude Code settings
# Run the comprehensive test suite
claude-hooks test
# Show version information
claude-hooks --version
# Display help and usage information
claude-hooks --help
# Dart Integration Commands (NEW!)
claude-hooks dart init # Initialize Dart workspace configuration
claude-hooks dart edit # Edit existing .dart configuration
Running claude-hooks without any arguments launches an interactive menu:
$ claude-hooks
🪝 Claude Hooks Manager Interactive Menu
? What would you like to do? (Use arrow keys)
❯ 📦 Install hooks to Claude
📋 List all available hooks
🔍 Get info about a specific hook
✅ Check installation status
🧪 Run tests
🩺 Run diagnostics (doctor)
🚀 Initialize project hooks
──────────────
❌ Exit
# See what hooks are available
$ claude-hooks list
Available Claude Hooks:
pre-commit-validator.py Enforces coding standards before commits
validate-git-commit.py Validates commit message format
secret-scanner.py Detects and blocks secrets
no-mock-code.py Prevents placeholder/mock code
... and more
# Check if everything is set up correctly
$ claude-hooks doctor
🩺 Running Claude Hooks Manager Diagnostics...
✅ No issues found! Everything looks good.
# Check installation status
$ claude-hooks status
🔍 Checking Claude Hooks Manager Status...
✅ Hooks directory exists
17 hooks installed
✅ Settings file exists
# Get details about a specific hook
$ claude-hooks info secret-scanner
Hook: secret-scanner.py
Description: Detects and blocks secrets
Event: before_tool_call
Tools: Write, MultiEdit, Edit
# Run tests to ensure hooks are working
$ claude-hooks test
Running Claude Hooks Manager Tests...
==================================
✅ All hooks are executable
✅ All 17 hooks passed tests!
Claude Hooks Manager now includes seamless integration with Dart MCP for project management. This feature enables automatic task tracking and documentation synchronization.
Dart integration allows Claude to:
claude-hooks init
# When prompted, choose to set up Dart integration
claude-hooks dart init
This will:
.dart configuration file in your project rootThe .dart file stores your project's Dart workspace configuration:
{
"workspace": "MCP Forge",
"tasksFolder": "MCP Forge/Tasks",
"docsFolder": "MCP Forge/Docs",
"syncEnabled": true,
"syncRules": {
"include": ["README.md", "docs/**/*.md", "wiki/**/*.md"],
"exclude": [".github/**/*.md", "node_modules/**/*.md", "test/**/*.md"]
}
}
The claude-hooks dart init command can also generate a CLAUDE.md file that provides Claude with:
If you're not using Dart, you can:
"syncEnabled": false in your .dart file.dart file from your projectclaude-hooks disable sync-docs-to-dart and claude-hooks disable validate-dart-tasksync-docs-to-dart hook:
.dart configurationclaude-hooks dart initvalidate-dart-task hook:
See CLAUDE.md.template for a complete guide on customizing your project instructions. The template includes:
| Hook | Trigger | Purpose |
|---|---|---|
| Context Forge Hooks | ||
precompact-context-refresh.py | Before compaction | Detects Context Forge projects and prepares context recovery |
stop-context-refresh.py | After compaction | Enforces re-reading of CLAUDE.md, PRPs, and Implementation.md |
| Standard Hooks | ||
pre-commit-validator.py | Before git commit/push | Runs tests, linting, TypeScript checks |
validate-git-commit.py | Before git commit | Enforces commit message standards |
database-extension-check.py | When editing schemas | Prevents unnecessary table creation |
duplicate-detector.py | When creating files | Prevents duplicate code/routes |
style-consistency.py | When editing TSX/CSS | Enforces theme-aware styling |
api-endpoint-verifier.py | When editing API routes | Validates endpoint configuration |
api-docs-enforcer.py | Before commits & API edits | Enforces Swagger docs, Postman collections, API security |
no-mock-code.py | Before commits & file edits | Prevents placeholder/mock code in production |
secret-scanner.py | Before commits & file edits | Detects and prevents committing secrets |
env-sync-validator.py | When editing .env files | Keeps .env and .env.example in sync |
gitignore-enforcer.py | Before git add/commit | Ensures .gitignore exists and blocks forbidden files |
readme-update-validator.py | Before commits | Reminds to update README when features change |
validate-dart-task.py | Creating Dart tasks | Ensures proper task hierarchy |
sync-docs-to-dart.py | After creating .md files | Reminds to sync docs |
log-commands.py | Before bash commands | Logs all commands |
mcp-tool-enforcer.py | Various operations | Suggests MCP tool usage |
session-end-summary.py | Session end | Provides reminders |
Click on any hook below to see detailed information about what it does and how it helps your development workflow.
This groundbreaking hook enables multi-hour AI development sessions by solving the context loss problem:
When Claude Code's context window fills up (every ~2 hours), it performs compaction and forgets your project context. This hook ensures Claude automatically recovers all project-specific knowledge, enabling you to work for 8+ hours without interruption.
Context refresh required after compaction.
1. Re-read CLAUDE.md to restore project rules and conventions
2. Check Docs/Implementation.md - you are currently working on Stage 2
3. Review PRPs/base.md for implementation guidelines
4. Check Docs/Bug_tracking.md for known issues
Works in tandem with the PreCompact hook to restore context after compaction:
Eliminates the frustrating need to manually remind Claude about your project after each compaction. Your workflow continues seamlessly, maintaining quality and consistency throughout extended development sessions.
This hook specifically looks for Context Forge project structures and customizes the refresh instructions based on what files exist in your project, ensuring maximum context recovery with minimum overhead.
This hook acts as your personal quality assurance assistant. Before any code gets committed, it automatically:
Imagine pushing code only to find out later that tests are failing or there are linting errors. This hook prevents that embarrassment by catching issues before they reach the repository. It's like having a careful reviewer check your work every time.
🔍 Running pre-commit validation...
✅ Tests passed (42 tests, 0 failures)
✅ Linting passed (0 errors, 0 warnings)
✅ TypeScript check passed
✨ All checks passed! Ready to commit.
This hook ensures all commit messages follow a consistent format:
Good commit messages make project history readable and searchable. This hook ensures everyone on the team writes clear, consistent commit messages that explain what changed and why.
❌ Bad: "fix bug"
✅ Good: "Fix navigation menu overflow on mobile devices"
Prevents developers from creating unnecessary new database tables when they could extend existing ones:
Keeps your database clean and maintainable by preventing table sprawl. Instead of having users, user_profiles, user_settings, and user_preferences as separate tables, it encourages you to use a single users table with appropriate columns.
⚠️ Creating new table 'user_settings'
💡 Consider extending the existing 'users' table instead
You could add a 'settings' JSON column or related fields
Scans your codebase to prevent creating duplicate:
/api/users endpoints)Duplication leads to maintenance nightmares. This hook helps maintain the DRY (Don't Repeat Yourself) principle by alerting you when similar code already exists.
❌ Duplicate detected!
You're creating: components/UserCard.tsx
Already exists: components/user/UserCard.tsx
💡 Consider using the existing component or choosing a different name
Ensures consistent styling across your application:
Maintains a professional, consistent look across your entire application. No more random colors or inconsistent spacing that makes your app look unprofessional.
⚠️ Style issues found:
Line 23: Missing dark mode variant for bg-blue-500
Line 45: Use ShadCN Button component instead of <button>
Line 67: Hardcoded color #3B82F6 - use theme variables
Validates that all API endpoints follow best practices:
Prevents security vulnerabilities and ensures a consistent API experience for consumers. No more endpoints that work differently or have security holes.
❌ API endpoint issues:
/api/getUser - Should use REST convention: GET /api/users/:id
Missing authentication check
No input validation for user ID
Ensures every API endpoint is properly documented:
Good API documentation is crucial for team collaboration and API consumers. This hook ensures no endpoint goes undocumented, making your API easy to understand and use.
❌ API Documentation Required:
New endpoint: POST /api/users/bulk-import
Missing from swagger.json
No Postman collection entry
💡 Run 'npm run generate-api-docs' to auto-generate documentation
Prevents placeholder or mock code from entering production:
Ensures your production code uses real, dynamic data. No more embarrassing moments where "John Doe" appears in production or where a function always returns the same test data.
❌ Mock/Placeholder Code Detected!
Line 45: Found "Lorem ipsum" - Replace with real content
Line 67: Static user data - Implement database query
Line 89: TODO without implementation - Complete the function
Scans code for accidentally exposed secrets:
Prevents the #1 security mistake: committing secrets to version control. Once a secret is in Git history, it's compromised forever. This hook is your last line of defense.
🚨 CRITICAL: Attempting to commit secrets!
Line 23: API key detected: sk_test_abc...
Line 45: Hardcoded password found
❌ Commit blocked - remove secrets and use environment variables
Keeps your environment configuration files synchronized:
When team members pull your code, they need to know what environment variables to set. This hook ensures .env.example always reflects the current requirements.
❌ Environment sync issues:
New variable DATABASE_URL in .env
Missing from .env.example
💡 Add to .env.example:
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
Ensures .gitignore is properly configured:
Keeps your repository clean and secure. Prevents accidentally committing files that should never be in version control, like private keys, large binaries, or temporary files.
🚨 FORBIDDEN FILES detected:
• .env (environment file)
• private-key.pem (private key)
• test-script.sh (test script)
💡 Add these patterns to .gitignore:
.env
*.pem
*test-script*
Reminds you to update documentation when code changes:
Documentation often becomes outdated because developers forget to update it. This hook provides gentle reminders to keep your README current with your code.
📚 README Update Reminder:
🆕 New files detected:
• api/users/bulk-import.js (API endpoint)
• components/UserBulkUpload.tsx (Component)
💡 Consider updating these README sections:
• API Documentation
• Features
• Usage Examples
Ensures proper task management in Dart:
Keeps project management organized by ensuring all tasks are properly categorized and tracked within the correct project phase.
Tracks when markdown files are created and reminds to sync with Dart:
Ensures documentation stays synchronized across different systems, preventing information silos.
Logs all bash commands for audit and learning:
Creates an audit trail of all commands run, useful for debugging, learning patterns, and security auditing.
Suggests MCP tools when better alternatives exist:
Helps developers use the most efficient tools available, improving productivity and code quality.
Provides helpful reminders at session end:
Acts like a helpful assistant making sure you don't forget important tasks before ending your coding session.
Validates timestamps and dates in your documentation:
Prevents common date mistakes like using January dates in July, future dates in changelogs, or outdated timestamps. Ensures your documentation always has accurate temporal information.
Hooks are configured in ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [...],
"PostToolUse": [...],
"Stop": [...]
}
}
See settings.example.json for the complete configuration.
Some hooks now support project-specific configuration to avoid cross-project interference:
Create .claude/session-summary.json in your project:
{
"show_dart_reminders": true,
"show_git_reminders": true,
"custom_reminders": [
"Run tests before committing",
"Update documentation"
]
}
Create .claude/dart-config.json in your project:
{
"enable_doc_sync": true,
"default_docs_folder": "workspace/Docs",
"workspace": "your-workspace",
"dartboard": "workspace/Tasks"
}
See Project-Aware Hooks Documentation for detailed configuration options.
Edit ~/.claude/settings.json and remove or comment out the specific hook entry.
See our comprehensive Developing Custom Hooks Guide for detailed instructions.
Quick start:
~/.claude/hooks/chmod +x your-hook.pysettings.json0 - Success, continue normally2 - Blocking error, prevents tool execution~/.claude/settings.json is valid JSONIf you're seeing "No such file or directory" errors for disabled hooks:
Problem: When hooks are disabled using older versions, Claude still tries to execute them, causing errors.
Solution: Run the migration script to update disabled hooks to the new format:
node migrate-disabled-hooks.js
This converts disabled hooks to use stub files that exit cleanly, preventing errors while keeping hooks disabled.
How it works:
.disabled, the new system:
.py.original.py file that exits cleanlyecho '{"tool_name":"Bash","tool_input":{"command":"test"}}' | python3 ~/.claude/hooks/hook-name.py
~/.claude/bash-command-log.txt - All bash commands~/.claude/hooks/commands-YYYY-MM-DD.log - Daily command logs~/.claude/hooks/command-stats.json - Command frequency stats~/.claude/hooks/pending-dart-syncs.json - Pending doc syncsContributions are welcome! Please:
MIT License - see LICENSE file for details
Created for the Claude community to enhance productivity and maintain code quality.
Made with ❤️ by Sem
FAQs
A comprehensive hook management system for Claude that enforces coding standards, maintains consistency, and automates workflow tasks
The npm package claude-hooks-manager receives a total of 27 weekly downloads. As such, claude-hooks-manager popularity was classified as not popular.
We found that claude-hooks-manager demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PolinRider expands across npm, Packagist, Go modules, and Chrome extensions, using hidden loaders to target developer environments.
Security News
Open source attacks are accelerating as AI coding agents pull in dependencies faster, with less human review.
Research
/Security News
Malicious Chrome and Firefox extensions posed as free VPNs while stealing clipboard data through later extension updates.