Claude Code Enhanced Hook System v1.0

A comprehensive, production-ready hook system for Claude Code that solves the "empty payload" issue and provides enterprise-grade file backup, logging, and monitoring capabilities.

🚀 Quick Start

# 1. Copy to your project
cp -r claude-hook-system-v1.0/hooks .claude/
chmod +x .claude/*.sh

# 2. Install configuration
cp claude-hook-system-v1.0/config/settings.template.json .claude/settings.local.json

# 3. Create required directories  
mkdir -p .claude/backups && touch .claude-state

# 4. Test installation
./claude-hook-system-v1.0/tests/test-installation.sh

# 5. Restart Claude Code for hooks to take effect

✨ Features

✅ Enhanced PostToolUse Detection

• Solves Empty Payload Issue: Uses filesystem and process monitoring instead of relying on empty payloads
• File Change Detection: Automatically detects which files were modified by Claude operations
• Command Detection: Identifies executed commands through process monitoring
• Smart Filtering: Excludes irrelevant files (git, backups, logs) and prioritizes project files

✅ Comprehensive Backup System

• Automatic Backups: Creates timestamped backups before Edit/Write/MultiEdit operations
• Multiple Extraction Methods: 4 different methods to extract file paths from JSON payloads
• Robust Error Handling: Continues operation even if backup fails
• Organized Storage: Structured backup directory with timestamp naming

✅ Advanced Logging & Monitoring

• Session Tracking: Logs session start/end with timestamps
• Git Integration: Shows git status changes on prompt submission
• Syntax Validation: Automatic syntax checking for Python, JavaScript, JSON files
• Debug Logging: Comprehensive debug information for troubleshooting

✅ Production Ready

• Zero Data Loss: Never blocks tool execution, even on errors
• Performance Optimized: Lightweight detection with minimal overhead
• Cross-Platform: Works on Linux, macOS, WSL environments
• Comprehensive Testing: Full test suite with installation and functionality tests

📁 Package Structure

claude-hook-system-v1.0/
├── hooks/                           # Core hook scripts
│   ├── backup-hook.sh               # PreToolUse backup functionality
│   ├── posttooluse-enhanced.sh      # Main PostToolUse hook with detection
│   ├── posttooluse-file-detector.sh # File change detection
│   └── posttooluse-command-detector.sh # Command detection
├── config/
│   └── settings.template.json       # Hook configuration template
├── docs/
│   └── INSTALLATION.md              # Detailed installation guide
├── tests/
│   ├── test-installation.sh         # Installation validation tests
│   └── test-functionality.sh        # Functionality and integration tests
├── examples/
│   ├── basic-setup.sh              # Quick setup script
│   └── advanced-config.json        # Advanced configuration examples
└── README.md                       # This file

🎯 Problem Solved

Before: PostToolUse hooks received empty payloads, making it impossible to know:

• Which files were modified
• What commands were executed
• How to provide meaningful logging

After: This system provides:

• ✅ Actual filenames in MODIFIED log entries
• ✅ Real command names in EXECUTED log entries
• ✅ Comprehensive activity tracking and debugging
• ✅ Reliable file backup before any modifications

🔧 Installation

Quick Installation

# Run the provided setup script
./examples/basic-setup.sh

Manual Installation

# 1. Create directory structure
mkdir -p .claude/backups
touch .claude-state .claude/hook-debug.log

# 2. Copy hook scripts
cp hooks/*.sh .claude/
chmod +x .claude/*.sh

# 3. Configure hooks
cp config/settings.template.json .claude/settings.local.json

# 4. Test installation
./tests/test-installation.sh

# 5. Restart Claude Code

🧪 Testing

Installation Test

./tests/test-installation.sh
# Tests prerequisites, file structure, permissions, and basic configuration

Functionality Test

./tests/test-functionality.sh
# Tests file detection, command detection, backup creation, and syntax validation

Manual Testing

# Test file backup
echo "test content" > test.txt
# (Use Claude to edit this file - should create backup)

# Check logs
tail -10 .claude-state           # Activity log
tail -10 .claude/hook-debug.log  # Debug information
ls .claude/backups/              # Created backups

⚙️ Configuration

Basic Configuration

The system works out-of-the-box with the template configuration. Key hooks:

• preToolUse: Automatic file backup before edits
• postToolUse: Enhanced logging with file/command detection
• userPromptSubmit: Session and git status logging
• notification: Event logging
• stop: Session end tracking

Advanced Configuration

See examples/advanced-config.json for:

• Project-specific backup rules
• Custom validation hooks
• Deployment automation
• Test execution triggers

Customization

Edit the hook scripts to add:

• Additional file type validation
• Custom logging formats
• Project-specific automation
• Integration with other tools

📊 What You Get

Log Entries

# Before (empty payload issue)
[2025-08-07_23:01:54] MODIFIED: unknown
[2025-08-07_23:01:54] EXECUTED: unknown

# After (with enhanced detection)  
[2025-08-07_23:01:54] MODIFIED: ./src/main.py
[2025-08-07_23:01:54] EXECUTED: python -m pytest tests/
[2025-08-07_23:01:54] BACKUP: ./src/main.py -> .claude/backups/main.py.20250807_230154.backup

File Structure After Use

your-project/
├── .claude/
│   ├── settings.local.json
│   ├── hook-debug.log
│   ├── backups/
│   │   ├── main.py.20250807_230154.backup
│   │   ├── config.json.20250807_230342.backup
│   │   └── ...
│   └── *.sh (hook scripts)
├── .claude-state                    # Main activity log
└── (your project files)

🔍 Troubleshooting

Common Issues

Hooks not working

1. Restart Claude Code (required after hook changes)
2. Check permissions: chmod +x .claude/*.sh
3. Verify configuration: jq . .claude/settings.local.json

Empty log entries

1. Check detection scripts are executable
2. Test manually: ./.claude/posttooluse-file-detector.sh
3. Verify find and ps commands work

Missing backups

1. Check .claude/hook-debug.log for errors
2. Verify backup directory exists: ls -la .claude/backups/
3. Test backup hook: echo '{"file_path": "test.txt"}' | ./.claude/backup-hook.sh

Debug Mode

# Enable detailed logging
export CLAUDE_HOOK_DEBUG=1
# Check debug output
tail -f .claude/hook-debug.log

🆚 Version History

• v1.0 (2025-08-07): Initial release
  • Enhanced PostToolUse detection system
  • Comprehensive file backup functionality
  • Production-ready hook system
  • Full test suite and documentation

📄 License

MIT License - Feel free to use in any project

🤝 Contributing

Contributions welcome! Please:

1. Run the test suite: ./tests/test-installation.sh && ./tests/test-functionality.sh
2. Update documentation for any changes
3. Follow the existing code style and error handling patterns

💡 Use Cases

• Development Projects: Automatic backup and activity logging
• Production Environments: Change tracking and audit trails
• Team Collaboration: Shared activity logs and file history
• CI/CD Integration: Pre/post deployment hooks
• Learning/Training: Understanding Claude's file modification patterns

Ready to enhance your Claude Code workflow? Get started with the quick installation above! 🚀