{"_id":"@diegocon/claude-enhanced-hooks","name":"@diegocon/claude-enhanced-hooks","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@diegocon/claude-enhanced-hooks","version":"1.0.0","description":"Production-ready hook system for Claude Code that solves the PostToolUse empty payload issue with enhanced file detection, automatic backups, and comprehensive logging","main":"index.js","bin":{"claude-hooks-install":"bin/install.js","claude-hooks-test":"bin/test.js"},"scripts":{"install-hooks":"node bin/install.js","test-hooks":"node bin/test.js","test":"bash tests/test-installation.sh && bash tests/test-functionality.sh","postinstall":"node scripts/postinstall.js"},"keywords":["claude-code","claude","hooks","automation","backup","logging","posttooluse","cli","development","productivity","file-management","monitoring"],"author":{"name":"Diego Cavalari Consolini","email":"diegocavalariconsolini@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/claude-code/enhanced-hooks.git"},"bugs":{"url":"https://github.com/claude-code/enhanced-hooks/issues"},"homepage":"https://github.com/claude-code/enhanced-hooks#readme","engines":{"node":">=14.0.0"},"dependencies":{},"devDependencies":{},"peerDependencies":{},"optionalDependencies":{},"os":["darwin","linux","win32"],"cpu":["x64","arm64"],"preferGlobal":true,"publishConfig":{"access":"public"},"_id":"@diegocon/claude-enhanced-hooks@1.0.0","gitHead":"ba56063999833291f8a4dff9a11be0d425cd5878","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-qo1XyHBa1PuikZi+QQgFTfRpGtNnMdZbor3CYEefkDc9W8qOkF8f1vMkFunl0GJF9ExC6No2ANwMiYfrZm4hew==","shasum":"aa0b727433cef4e829461c0f45d9ea04f5200d29","tarball":"https://registry.npmjs.org/@diegocon/claude-enhanced-hooks/-/claude-enhanced-hooks-1.0.0.tgz","fileCount":19,"unpackedSize":65090,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDv24nBH/HdWHWbLBh5aYYVk+vszPsbO9NYEPa7gXEvzQIgJpaMyLrsboBYn1JcX2unLLTBBQGDLSlcZRd5aPfmuPQ="}]},"_npmUser":{"name":"diegocon","email":"diegocavalariconsolini@gmail.com"},"directories":{},"maintainers":[{"name":"diegocon","email":"diegocavalariconsolini@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-enhanced-hooks_1.0.0_1754607572661_0.21023384189584315"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-07T22:59:32.549Z","1.0.0":"2025-08-07T22:59:32.844Z","modified":"2025-08-07T22:59:33.160Z"},"maintainers":[{"name":"diegocon","email":"diegocavalariconsolini@gmail.com"}],"description":"Production-ready hook system for Claude Code that solves the PostToolUse empty payload issue with enhanced file detection, automatic backups, and comprehensive logging","homepage":"https://github.com/claude-code/enhanced-hooks#readme","keywords":["claude-code","claude","hooks","automation","backup","logging","posttooluse","cli","development","productivity","file-management","monitoring"],"repository":{"type":"git","url":"git+https://github.com/claude-code/enhanced-hooks.git"},"author":{"name":"Diego Cavalari Consolini","email":"diegocavalariconsolini@gmail.com"},"bugs":{"url":"https://github.com/claude-code/enhanced-hooks/issues"},"license":"MIT","readme":"# Claude Code Enhanced Hook System v1.0\n\nA comprehensive, production-ready hook system for Claude Code that solves the \"empty payload\" issue and provides enterprise-grade file backup, logging, and monitoring capabilities.\n\n## 🚀 Quick Start\n\n```bash\n# 1. Copy to your project\ncp -r claude-hook-system-v1.0/hooks .claude/\nchmod +x .claude/*.sh\n\n# 2. Install configuration\ncp claude-hook-system-v1.0/config/settings.template.json .claude/settings.local.json\n\n# 3. Create required directories  \nmkdir -p .claude/backups && touch .claude-state\n\n# 4. Test installation\n./claude-hook-system-v1.0/tests/test-installation.sh\n\n# 5. Restart Claude Code for hooks to take effect\n```\n\n## ✨ Features\n\n### ✅ **Enhanced PostToolUse Detection**\n- **Solves Empty Payload Issue**: Uses filesystem and process monitoring instead of relying on empty payloads\n- **File Change Detection**: Automatically detects which files were modified by Claude operations\n- **Command Detection**: Identifies executed commands through process monitoring\n- **Smart Filtering**: Excludes irrelevant files (git, backups, logs) and prioritizes project files\n\n### ✅ **Comprehensive Backup System**\n- **Automatic Backups**: Creates timestamped backups before Edit/Write/MultiEdit operations\n- **Multiple Extraction Methods**: 4 different methods to extract file paths from JSON payloads\n- **Robust Error Handling**: Continues operation even if backup fails\n- **Organized Storage**: Structured backup directory with timestamp naming\n\n### ✅ **Advanced Logging & Monitoring**\n- **Session Tracking**: Logs session start/end with timestamps\n- **Git Integration**: Shows git status changes on prompt submission\n- **Syntax Validation**: Automatic syntax checking for Python, JavaScript, JSON files\n- **Debug Logging**: Comprehensive debug information for troubleshooting\n\n### ✅ **Production Ready**\n- **Zero Data Loss**: Never blocks tool execution, even on errors\n- **Performance Optimized**: Lightweight detection with minimal overhead\n- **Cross-Platform**: Works on Linux, macOS, WSL environments\n- **Comprehensive Testing**: Full test suite with installation and functionality tests\n\n## 📁 Package Structure\n\n```\nclaude-hook-system-v1.0/\n├── hooks/                           # Core hook scripts\n│   ├── backup-hook.sh               # PreToolUse backup functionality\n│   ├── posttooluse-enhanced.sh      # Main PostToolUse hook with detection\n│   ├── posttooluse-file-detector.sh # File change detection\n│   └── posttooluse-command-detector.sh # Command detection\n├── config/\n│   └── settings.template.json       # Hook configuration template\n├── docs/\n│   └── INSTALLATION.md              # Detailed installation guide\n├── tests/\n│   ├── test-installation.sh         # Installation validation tests\n│   └── test-functionality.sh        # Functionality and integration tests\n├── examples/\n│   ├── basic-setup.sh              # Quick setup script\n│   └── advanced-config.json        # Advanced configuration examples\n└── README.md                       # This file\n```\n\n## 🎯 Problem Solved\n\n**Before**: PostToolUse hooks received empty payloads, making it impossible to know:\n- Which files were modified\n- What commands were executed\n- How to provide meaningful logging\n\n**After**: This system provides:\n- ✅ Actual filenames in MODIFIED log entries\n- ✅ Real command names in EXECUTED log entries  \n- ✅ Comprehensive activity tracking and debugging\n- ✅ Reliable file backup before any modifications\n\n## 🔧 Installation\n\n### Quick Installation\n```bash\n# Run the provided setup script\n./examples/basic-setup.sh\n```\n\n### Manual Installation\n```bash\n# 1. Create directory structure\nmkdir -p .claude/backups\ntouch .claude-state .claude/hook-debug.log\n\n# 2. Copy hook scripts\ncp hooks/*.sh .claude/\nchmod +x .claude/*.sh\n\n# 3. Configure hooks\ncp config/settings.template.json .claude/settings.local.json\n\n# 4. Test installation\n./tests/test-installation.sh\n\n# 5. Restart Claude Code\n```\n\n## 🧪 Testing\n\n### Installation Test\n```bash\n./tests/test-installation.sh\n# Tests prerequisites, file structure, permissions, and basic configuration\n```\n\n### Functionality Test  \n```bash\n./tests/test-functionality.sh\n# Tests file detection, command detection, backup creation, and syntax validation\n```\n\n### Manual Testing\n```bash\n# Test file backup\necho \"test content\" > test.txt\n# (Use Claude to edit this file - should create backup)\n\n# Check logs\ntail -10 .claude-state           # Activity log\ntail -10 .claude/hook-debug.log  # Debug information\nls .claude/backups/              # Created backups\n```\n\n## ⚙️ Configuration\n\n### Basic Configuration\nThe system works out-of-the-box with the template configuration. Key hooks:\n\n- **preToolUse**: Automatic file backup before edits\n- **postToolUse**: Enhanced logging with file/command detection\n- **userPromptSubmit**: Session and git status logging\n- **notification**: Event logging\n- **stop**: Session end tracking\n\n### Advanced Configuration\nSee `examples/advanced-config.json` for:\n- Project-specific backup rules\n- Custom validation hooks\n- Deployment automation\n- Test execution triggers\n\n### Customization\nEdit the hook scripts to add:\n- Additional file type validation\n- Custom logging formats\n- Project-specific automation\n- Integration with other tools\n\n## 📊 What You Get\n\n### Log Entries\n```bash\n# Before (empty payload issue)\n[2025-08-07_23:01:54] MODIFIED: unknown\n[2025-08-07_23:01:54] EXECUTED: unknown\n\n# After (with enhanced detection)  \n[2025-08-07_23:01:54] MODIFIED: ./src/main.py\n[2025-08-07_23:01:54] EXECUTED: python -m pytest tests/\n[2025-08-07_23:01:54] BACKUP: ./src/main.py -> .claude/backups/main.py.20250807_230154.backup\n```\n\n### File Structure After Use\n```\nyour-project/\n├── .claude/\n│   ├── settings.local.json\n│   ├── hook-debug.log\n│   ├── backups/\n│   │   ├── main.py.20250807_230154.backup\n│   │   ├── config.json.20250807_230342.backup\n│   │   └── ...\n│   └── *.sh (hook scripts)\n├── .claude-state                    # Main activity log\n└── (your project files)\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n**Hooks not working**\n1. Restart Claude Code (required after hook changes)\n2. Check permissions: `chmod +x .claude/*.sh`\n3. Verify configuration: `jq . .claude/settings.local.json`\n\n**Empty log entries** \n1. Check detection scripts are executable\n2. Test manually: `./.claude/posttooluse-file-detector.sh`\n3. Verify `find` and `ps` commands work\n\n**Missing backups**\n1. Check `.claude/hook-debug.log` for errors\n2. Verify backup directory exists: `ls -la .claude/backups/`\n3. Test backup hook: `echo '{\"file_path\": \"test.txt\"}' | ./.claude/backup-hook.sh`\n\n### Debug Mode\n```bash\n# Enable detailed logging\nexport CLAUDE_HOOK_DEBUG=1\n# Check debug output\ntail -f .claude/hook-debug.log\n```\n\n## 🆚 Version History\n\n- **v1.0** (2025-08-07): Initial release\n  - Enhanced PostToolUse detection system\n  - Comprehensive file backup functionality  \n  - Production-ready hook system\n  - Full test suite and documentation\n\n## 📄 License\n\nMIT License - Feel free to use in any project\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n1. Run the test suite: `./tests/test-installation.sh && ./tests/test-functionality.sh`\n2. Update documentation for any changes\n3. Follow the existing code style and error handling patterns\n\n## 💡 Use Cases\n\n- **Development Projects**: Automatic backup and activity logging\n- **Production Environments**: Change tracking and audit trails\n- **Team Collaboration**: Shared activity logs and file history\n- **CI/CD Integration**: Pre/post deployment hooks\n- **Learning/Training**: Understanding Claude's file modification patterns\n\n---\n\n**Ready to enhance your Claude Code workflow? Get started with the quick installation above! 🚀**","readmeFilename":"README.md","_rev":"1-a7a4aba5aeec007748de9de6121e4d6d"}