claude-hooks/README.md

# Claude Hooks

Intelligent hooks system for Claude Code that provides command validation, session continuity, and learning capabilities using Claude Code's native hooks architecture.

## Quick Start

```bash
# Install globally via npm
npm install -g claude-hooks

# Initialize hooks
claude-hooks init

# Test installation
claude-hooks test

# Restart Claude Code to activate
```

## Features

🧠 **Shadow Learning** - Learns from command failures and suggests working alternatives  
📊 **Context Monitoring** - Automatically backs up work before context limits  
⚡ **Smart Validation** - Blocks dangerous commands with intelligent suggestions  
🔄 **Session Continuity** - Maintains history and state across Claude restarts

## Usage

After installation, Claude Hooks runs automatically:

- **Command Learning**: Try `pip install requests` → suggests `pip3 install requests`
- **Auto Backup**: Triggers before context limits or manually with `claude-hooks backup`
- **Status Check**: Run `claude-hooks status` to verify installation
- **Manual Test**: Use `claude-hooks test` to verify all components

## Commands

```bash
claude-hooks init          # Initialize after npm install
claude-hooks status        # Check installation status  
claude-hooks test          # Run test suite
claude-hooks backup        # Create manual backup
claude-hooks uninstall     # Remove hooks configuration
claude-hooks --help        # Show all commands
```

## How It Works

Claude Hooks uses Claude Code's native hook system with four key integration points:

- **UserPromptSubmit**: Monitors context usage and triggers backups
- **PreToolUse[Bash]**: Validates commands and suggests alternatives  
- **PostToolUse[*]**: Logs activity and learns from patterns
- **Stop**: Finalizes sessions and creates continuation docs

## Installation Methods

### NPM (Recommended)
```bash
npm install -g claude-hooks
claude-hooks init
```

### Git (Development)
```bash
git clone https://git.supported.systems/rsp2k/claude-hooks.git
cd claude-hooks && ./scripts/install.sh
```

## Documentation

- [Getting Started Tutorial](docs/tutorial/getting-started.md)
- [Architecture Explanation](docs/explanation/architecture.md)
- [How-to Guides](docs/how-to/)
- [Reference Documentation](docs/reference/)

## Requirements

- **Node.js** 16+ (only runtime required)
- **Claude Code** (hooks integrate with Claude's native system)

## License

MIT License - see [LICENSE](LICENSE) for details.

---

*Claude Code Hooks makes your AI assistant smarter by giving it memory, environmental awareness, and the ability to learn from experience.*