Claude Hooks Manager by Sem

📢 Important Notice for Existing Users

This project has been renamed from claude-code-hooks to claude-hooks-manager to 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-manager

The CLI command claude-hooks remains unchanged.

A comprehensive hook management system for Claude that enforces coding standards, maintains consistency, and automates workflow tasks across all projects.

🚀 Game-Changing Feature: Context Forge Integration

🌟 Never Lose Context Again During Multi-Hour Development Sessions!

🎉 First to Implement Anthropic's New PreCompact Hook!

We're excited to announce our groundbreaking integration with Context Forge - the industry-leading CLI tool for AI-ready project scaffolding. This integration is the first implementation of Anthropic's brand new PreCompact hook, announced in Claude Code v1.0.48, solving one of the biggest challenges in AI-assisted development: context loss during conversation compaction.

Why This is Revolutionary

Anthropic's PreCompact hook is a game-changing new feature that allows developers to:

• 🔍 Intercept compaction events before they happen
• 💾 Preserve critical context during the compaction process
• 🔄 Automatically restore state after compaction completes
• 🚀 Enable truly continuous workflows for the first time

We're among the first to leverage this powerful new capability from Anthropic, creating an integration that transforms how developers work with AI assistants.

What is Context Forge?

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:

• CLAUDE.md - Main context file with project rules and conventions
• Docs/ - Structured implementation plans and documentation
• PRPs/ - Product Requirement Prompts for detailed specifications
• Validation Systems - Built-in quality gates and checks

Install Context Forge:

npm install -g context-forge

Quick start a new project:

context-forge init

The Problem We Solve

During extended coding sessions, Claude Code's context window fills up and performs "compaction" to continue. This causes:

• 😰 Loss of project-specific rules and conventions
• 🔄 Forgotten implementation stages and progress
• 📋 Lost track of PRP guidelines and specifications
• 🐛 Forgotten bug tracking and known issues

The Solution: Automatic Context Recovery

Our Context Forge hooks provide automatic context recovery after compaction using Anthropic's latest hook capabilities:

1. PreCompact Hook (New in Claude Code v1.0.48) - Intercepts compaction before it happens
2. Smart Detection - Automatically identifies projects with CLAUDE.md, Docs/, and PRPs/
3. Context Restoration - Forces Claude to re-read critical project files after compaction
4. Progress Tracking - Maintains awareness of current implementation stage

Technical Note: The PreCompact hook is a brand new feature from Anthropic that was just released. It's the missing piece that finally makes multi-hour AI development sessions practical. By intercepting the compaction event before it happens, we can prepare instructions that ensure context is restored immediately after.

Benefits for Developers

• ✅ Multi-Hour Workflows - Work on complex projects for 8+ hours without context loss
• ✅ Consistent Quality - Maintain project standards throughout entire sessions
• ✅ Zero Manual Intervention - Automatic context refresh, no reminders needed
• ✅ PRP Compliance - Continuous adherence to Product Requirement Prompts
• ✅ Stage Awareness - Always knows which implementation phase you're in

Setup Context Forge Integration

# 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 →

🎯 The Perfect AI Development Workflow

Combine Context Forge and Claude Hooks Manager for the ultimate AI-assisted development experience:

1. Start with Context Forge

   npm install -g context-forge
   context-forge init

   • Creates AI-optimized project structure
   • Generates CLAUDE.md with project rules
   • Sets up implementation stages and PRPs

2. Install Claude Hooks Manager

   npm install -g claude-hooks-manager
   claude-hooks install

   • Enforces coding standards
   • Maintains consistency
   • Automates workflows

3. Enable Context Forge Integration

   cd hooks/context-forge
   ./install-context-forge-hooks.sh

   • Enables multi-hour workflows
   • Automatic context recovery
   • Maintains project awareness

4. Develop with Confidence

   • Work for 8+ hours without context loss
   • Automatic quality enforcement
   • Consistent code standards
   • PRP compliance throughout

This powerful combination transforms AI-assisted development from a novelty into a production-ready workflow that maintains quality and consistency across extended development sessions.

📚 Documentation

🛠️ Guides

• Context Forge Integration Guide - Enable multi-hour workflows with automatic context recovery
• Developing Custom Hooks - Create your own hooks with examples and best practices
• Project-Aware Hooks - Configure hooks for multi-project environments

📖 Official Claude Resources

• Claude Hooks Documentation
• Claude Setup Guide
• Model Context Protocol (MCP)
• Claude SDK

Features

🔒 Quality Gates

• Pre-commit validation - Run tests, linting, and TypeScript checks before commits
• Commit message standards - Enforce conventional commits and block co-authored commits
• Code quality checks - Automatic validation of code style and patterns

🛡️ Safety & Consistency

• Database protection - Prevent unnecessary table creation, encourage extending existing schemas
• Duplicate prevention - Detect duplicate routes, components, and API endpoints
• Style enforcement - Ensure theme-aware CSS, ShadCN usage, and consistent styling
• API verification - Validate endpoint configuration, authentication, and naming conventions

🔄 Workflow Automation

• Dart integration - Enforce task hierarchy and documentation sync
• Command logging - Track all bash commands with timestamps
• Session reminders - End-of-session summaries and pending task reminders
• MCP tool suggestions - Recommend MCP tools when alternatives are available

🆕 New Advanced Hooks

• No mock code - Prevents placeholder data (Lorem ipsum, test users, static returns)
• Secret scanner - Detects API keys, passwords, tokens before they're committed
• Environment sync - Keeps .env and .env.example synchronized
• Gitignore enforcer - Prevents committing sensitive files and test scripts
• README validator - Reminds to update documentation when features change
• Timestamp validator - Ensures accurate dates in documentation and changelogs

Installation

Install from npm

# Install the package globally
npm install -g claude-hooks-manager

# Run the installation script to copy hooks to Claude directory
claude-hooks-install

Install from Source

# 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

Manual Installation

1. Create the hooks directory:

   mkdir -p ~/.claude/hooks

2. Copy all Python hooks:

   cp hooks/*.py ~/.claude/hooks/
   chmod +x ~/.claude/hooks/*.py

3. Update your Claude settings:

   • If ~/.claude/settings.json exists, merge the hooks configuration from settings.example.json
   • If not, copy settings.example.json to ~/.claude/settings.json

4. Restart Claude for the hooks to take effect

CLI Usage

When installed via npm, you get access to the powerful claude-hooks CLI:

Available Commands

# 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

Interactive Menu (NEW!)

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

Examples

# 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!

🎯 Dart Integration

Claude Hooks Manager now includes seamless integration with Dart MCP for project management. This feature enables automatic task tracking and documentation synchronization.

What is Dart Integration?

Dart integration allows Claude to:

• Automatically suggest creating tasks in your Dart workspace
• Sync documentation between your local project and Dart
• Validate task creation with project-specific rules
• Generate CLAUDE.md files with workspace configuration

Setting Up Dart Integration

Method 1: During Project Init

claude-hooks init
# When prompted, choose to set up Dart integration

Method 2: Direct Dart Setup

claude-hooks dart init

This will:

1. Create a .dart configuration file in your project root
2. Configure your Dart workspace, tasks folder, and docs folder
3. Optionally create a CLAUDE.md file with project instructions

The .dart Configuration File

The .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"]
  }
}

CLAUDE.md - Project Instructions

The claude-hooks dart init command can also generate a CLAUDE.md file that provides Claude with:

• Project-specific instructions
• Dart workspace configuration
• Task management rules
• Git workflow guidelines
• Development best practices

Disabling Dart Features

If you're not using Dart, you can:

1. Skip during setup: Choose "No" when asked about Dart integration
2. Disable sync: Set "syncEnabled": false in your .dart file
3. Remove configuration: Delete the .dart file from your project
4. Disable hooks: Run claude-hooks disable sync-docs-to-dart and claude-hooks disable validate-dart-task

How It Works

1. sync-docs-to-dart hook:

   • Triggers when you create/edit markdown files
   • Checks for .dart configuration
   • If no config exists, prompts you to run claude-hooks dart init
   • If configured, suggests syncing to your Dart docs folder

2. validate-dart-task hook:

   • Triggers when creating Dart tasks
   • Suggests using your project's configured dartboard
   • Validates task priorities and statuses

Customizing CLAUDE.md

See CLAUDE.md.template for a complete guide on customizing your project instructions. The template includes:

• Variable references
• Common customizations
• Best practices
• Example configurations

Hooks Overview

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

📋 Detailed Hook Documentation

Click on any hook below to see detailed information about what it does and how it helps your development workflow.

🚀 precompact-context-refresh.py - First Implementation of Anthropic's PreCompact Hook

What it does:

This groundbreaking hook is the first implementation of Anthropic's new PreCompact hook event (released in Claude Code v1.0.48), enabling multi-hour AI development sessions:

• 🎯 Uses Anthropic's PreCompact event to intercept before compaction occurs
• 🔍 Detects Context Forge projects (CLAUDE.md, Docs/, PRPs/)
• 📊 Tracks current implementation stage from transcript
• 💾 Creates marker for post-compaction recovery
• 📝 Prepares detailed refresh instructions

Why it's revolutionary:

Before Anthropic released the PreCompact hook, there was no way to prepare for compaction events. Now, for the first time, we can:

• Intercept compaction before it happens (impossible before v1.0.48)
• Preserve critical state information during the compaction process
• Ensure immediate context recovery after compaction completes

This is a game-changer for AI-assisted development, finally making 8+ hour coding sessions practical and productive.

Technical implementation:

# This hook receives the new PreCompact event from Claude Code
# Event data includes: session_id, transcript_path, trigger, custom_instructions
def main():
    input_data = json.load(sys.stdin)  # PreCompact event from Anthropic
    # ... detect Context Forge project and prepare recovery

🔄 stop-context-refresh.py - Automatic Context Restoration

What it does:

Works in tandem with the PreCompact hook to restore context after compaction:

• ✅ Detects when compaction has occurred
• 📚 Forces Claude to re-read all critical project files
• 🎯 Maintains awareness of current implementation stage
• 💡 Provides specific instructions based on project structure

Why it's helpful:

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.

Integration with Context Forge:

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.

🔍 pre-commit-validator.py - Your Safety Net Before Commits

What it does:

This hook acts as your personal quality assurance assistant. Before any code gets committed, it automatically:

• ✅ Runs your test suite to catch broken functionality
• ✅ Executes linting tools to ensure code style consistency
• ✅ Performs TypeScript type checking to prevent type errors
• ✅ Validates that your code meets project standards

Why it's helpful:

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.

Example output:

🔍 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.

✏️ validate-git-commit.py - Commit Message Police

What it does:

This hook ensures all commit messages follow a consistent format:

• 📏 Enforces minimum message length (10+ characters)
• 🔤 Requires capitalized first letter
• 🚫 Blocks co-authored commits (no auto-generated attributions)
• 📝 Ensures conventional commit format when configured

Why it's helpful:

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.

Example:

❌ Bad: "fix bug"
✅ Good: "Fix navigation menu overflow on mobile devices"

🗄️ database-extension-check.py - Database Schema Guardian

What it does:

Prevents developers from creating unnecessary new database tables when they could extend existing ones:

• 🔍 Detects when you're creating new migration files
• 💡 Suggests existing tables that might be extended instead
• 📊 Encourages proper database normalization
• 🚫 Blocks creation of duplicate or redundant tables

Why it's helpful:

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.

Example:

⚠️  Creating new table 'user_settings'
💡 Consider extending the existing 'users' table instead
   You could add a 'settings' JSON column or related fields

🔁 duplicate-detector.py - Code Duplication Police

What it does:

Scans your codebase to prevent creating duplicate:

• 🛣️ API routes (e.g., two /api/users endpoints)
• 🧩 React/Vue components with the same name
• 📦 Utility functions that already exist
• 📄 Similar file names that might cause confusion

Why it's helpful:

Duplication leads to maintenance nightmares. This hook helps maintain the DRY (Don't Repeat Yourself) principle by alerting you when similar code already exists.

Example:

❌ Duplicate detected!
   You're creating: components/UserCard.tsx
   Already exists: components/user/UserCard.tsx
💡 Consider using the existing component or choosing a different name

🎨 style-consistency.py - Style & Theme Enforcer

What it does:

Ensures consistent styling across your application:

• 🌓 Enforces dark mode support (checks for dark: variants)
• 🎨 Prevents hardcoded colors (use theme variables instead)
• 🧩 Suggests ShadCN UI components over raw HTML elements
• 📏 Validates spacing uses consistent scale (2, 4, 6, 8, etc.)

Why it's helpful:

Maintains a professional, consistent look across your entire application. No more random colors or inconsistent spacing that makes your app look unprofessional.

Example:

⚠️  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

🌐 api-endpoint-verifier.py - API Standards Enforcer

What it does:

Validates that all API endpoints follow best practices:

• 🔐 Ensures authentication is implemented
• 📝 Checks for proper input validation
• 🏷️ Enforces consistent naming conventions
• ⚡ Validates error handling is in place

Why it's helpful:

Prevents security vulnerabilities and ensures a consistent API experience for consumers. No more endpoints that work differently or have security holes.

Example:

❌ API endpoint issues:
   /api/getUser - Should use REST convention: GET /api/users/:id
   Missing authentication check
   No input validation for user ID

📚 api-docs-enforcer.py - API Documentation Guardian

What it does:

Ensures every API endpoint is properly documented:

• 📋 Requires Swagger/OpenAPI documentation for all endpoints
• 📮 Enforces Postman collection updates
• 🔐 Validates security documentation for internal APIs
• 🔗 Ensures documentation links between Swagger and Postman

Why it's helpful:

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.

Example:

❌ 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

🚫 no-mock-code.py - Real Code Enforcer

What it does:

Prevents placeholder or mock code from entering production:

• 📝 Detects Lorem ipsum text
• 👤 Flags test users (John Doe, test@example.com)
• 🔄 Identifies functions that always return the same value
• 📌 Catches TODO comments without implementation
• 💾 Finds hardcoded test data

Why it's helpful:

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.

Example:

❌ 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

🔒 secret-scanner.py - Security Guardian

What it does:

Scans code for accidentally exposed secrets:

• 🔑 Detects API keys and tokens
• 🔐 Finds passwords and credentials
• 📧 Identifies private keys and certificates
• 🚨 Checks .gitignore includes sensitive files

Why it's helpful:

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.

Example:

🚨 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

🔄 env-sync-validator.py - Environment Config Keeper

What it does:

Keeps your environment configuration files synchronized:

• 📋 Ensures .env.example is updated when .env changes
• 💡 Suggests safe placeholder values for examples
• 🚫 Prevents real secrets in .env.example
• 📝 Validates all team members know required variables

Why it's helpful:

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.

Example:

❌ 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

🚮 gitignore-enforcer.py - Repository Cleanliness Guard

What it does:

Ensures .gitignore is properly configured:

• 📁 Verifies .gitignore exists
• 🚫 Blocks commits of sensitive files (.env, *.key, *.pem)
• 🧪 Prevents test scripts and temporary files
• 💾 Stops large files and backups from being committed

Why it's helpful:

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.

Example:

🚨 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*

📝 readme-update-validator.py - Documentation Reminder

What it does:

Reminds you to update documentation when code changes:

• 🆕 Detects new features and APIs
• 📚 Suggests README sections to update
• 🔧 Identifies configuration changes
• 📦 Notices new dependencies

Why it's helpful:

Documentation often becomes outdated because developers forget to update it. This hook provides gentle reminders to keep your README current with your code.

Example:

📚 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

✅ validate-dart-task.py - Task Hierarchy Enforcer

What it does:

Ensures proper task management in Dart:

• 📊 Requires all tasks have a Phase parent
• 🏷️ Validates task categorization
• 🔗 Maintains project hierarchy
• 📝 Enforces task metadata

Why it's helpful:

Keeps project management organized by ensuring all tasks are properly categorized and tracked within the correct project phase.

📄 sync-docs-to-dart.py - Documentation Sync Reminder

What it does:

Tracks when markdown files are created and reminds to sync with Dart:

• 📝 Detects new .md file creation
• 🔄 Tracks pending syncs
• 📊 Maintains documentation consistency
• 💾 Stores sync status

Why it's helpful:

Ensures documentation stays synchronized across different systems, preventing information silos.

📊 log-commands.py - Command Historian

What it does:

Logs all bash commands for audit and learning:

• 🕒 Timestamps every command
• 📁 Organizes logs by date
• 📈 Tracks command frequency
• 🔍 Enables command history search

Why it's helpful:

Creates an audit trail of all commands run, useful for debugging, learning patterns, and security auditing.

🛠️ mcp-tool-enforcer.py - Tool Usage Optimizer

What it does:

Suggests MCP tools when better alternatives exist:

• 🔄 Detects suboptimal tool usage
• 💡 Recommends MCP alternatives
• ⚡ Improves workflow efficiency
• 🎯 Promotes best practices

Why it's helpful:

Helps developers use the most efficient tools available, improving productivity and code quality.

👋 session-end-summary.py - Session Wrap-up Assistant

What it does:

Provides helpful reminders at session end:

• 💾 Reminds about uncommitted changes
• 📋 Lists pending tasks
• 🔧 Shows workflow reminders
• ✅ Ensures nothing is forgotten

Why it's helpful:

Acts like a helpful assistant making sure you don't forget important tasks before ending your coding session.

⏰ timestamp-validator.py - Date and Time Accuracy

What it does:

Validates timestamps and dates in your documentation:

• 📅 Checks dates in CHANGELOG entries
• ⚠️ Warns about future dates or dates from wrong months
• 🕐 Provides current timestamp in multiple formats
• 🔍 Detects hardcoded dates that might be incorrect
• 📝 Validates dates in commits and documentation

Why it's helpful:

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.

Configuration

Global Hook Configuration

Hooks are configured in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  }
}

See settings.example.json for the complete configuration.

Project-Specific Configuration

Some hooks now support project-specific configuration to avoid cross-project interference:

Session End Summary Hook

Create .claude/session-summary.json in your project:

{
  "show_dart_reminders": true,
  "show_git_reminders": true,
  "custom_reminders": [
    "Run tests before committing",
    "Update documentation"
  ]
}

Documentation Sync Hook

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.

Customization

Disable a Hook

Edit ~/.claude/settings.json and remove or comment out the specific hook entry.

Add Custom Hooks

See our comprehensive Developing Custom Hooks Guide for detailed instructions.

Quick start:

1. Create a Python script in ~/.claude/hooks/
2. Make it executable: chmod +x your-hook.py
3. Add it to the appropriate section in settings.json

Hook Exit Codes

• 0 - Success, continue normally
• 2 - Blocking error, prevents tool execution
• Other - Non-blocking error, shows message but continues

Best Practices

1. Performance - Keep hooks fast to avoid slowing down Claude
2. Error Handling - Always handle exceptions gracefully
3. Clear Messages - Provide actionable feedback
4. Non-Blocking - Use warnings for suggestions, only block on critical issues

Troubleshooting

Hooks Not Running

1. Restart Claude after installation
2. Check ~/.claude/settings.json is valid JSON
3. Verify hook files are executable

Disabled Hook Errors

If 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:

• Instead of renaming hooks to .disabled, the new system:
  • Moves the original hook to .py.original
  • Creates a stub .py file that exits cleanly
  • Claude can still find and execute the hook, but it does nothing

Testing Hooks

echo '{"tool_name":"Bash","tool_input":{"command":"test"}}' | python3 ~/.claude/hooks/hook-name.py

Log Files

• ~/.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 syncs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new hooks
4. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

Created for the Claude community to enhance productivity and maintain code quality.

Resources

• Developing Custom Hooks Guide - Complete tutorial for creating your own hooks
• Claude Documentation
• Hooks Documentation
• MCP Tools

---

Made with ❤️ by Sem

---

Star History