claude-hooks/docs/tutorial/getting-started.md

# Your First Hour with Claude Hooks

**Time required**: 30-45 minutes  
**What you'll gain**: Confidence using Claude with intelligent assistance

We're going to experience Claude Hooks by watching it learn from your commands and automatically protect your work. By the end, you'll have seen the system in action and feel comfortable relying on it.

## What We'll Do Together

We'll set up Claude Hooks, then deliberately make mistakes and watch the system learn and adapt. You'll see:
- A dangerous command get blocked automatically
- The system learn from a failed command and suggest alternatives  
- An automatic backup triggered before context gets full
- Your session seamlessly continue after Claude restarts

Let's begin.

## Step 1: Install Claude Hooks

First, we'll get Claude Hooks installed. Don't worry about understanding the configuration yet - we'll experience how it works first.

Open your terminal and navigate to where you downloaded claude-hooks:

```bash
cd claude-hooks
./scripts/install.sh
```

You should see output like this:
```
Claude Code Hooks Installation
==================================
Checking Python version... Python 3.11 found
✓ Python version is compatible
Installing Python dependencies... SUCCESS
```

**Notice** that the installer found your Python version and installed dependencies automatically.

The installer will ask if you want to automatically configure Claude Code. Say **yes** - we want to see this working right away:

```
Would you like to automatically add hooks to your Claude settings? (y/n): y
Updating Claude settings... SUCCESS
🎉 Hooks have been automatically configured!
```

You now have Claude Hooks installed and configured. We haven't learned how it works yet, but it's ready to assist you.

## Step 2: Restart Claude Code

Close Claude Code completely and start it again. This loads the hooks we just installed.

When Claude starts, the hooks are now silently running in the background. You won't see anything different yet - the magic happens when you start working.

## Step 3: Watch Command Validation in Action

Let's deliberately try a command that often fails to see the validation in action.

Start a new Claude conversation and try this:

> "Run `pip install requests` to add the requests library"

Watch what happens. You should see something like:

```
⚠️ Warning: pip commands often fail (confidence: 88%)
💡 Suggestion: Use "pip3 install requests"
```

**Notice** that Claude Hooks warned you about the command before it ran. The system doesn't have any learned patterns yet (it's brand new), but it has built-in knowledge about common failures.

Now try the suggested command:

> "Run `pip3 install requests`"

This time it should work without warnings. The system is learning that `pip3` succeeds where `pip` fails on your system.

## Step 4: Experience the Shadow Learner

Let's make another common mistake and watch the system learn from it.

Try this command:

> "Run `python --version` to check the Python version"

If you're on a system where `python` isn't available, you'll see it fail. Now try the same command again:

> "Run `python --version` again"

**Notice** what happens this time. The system should now warn you:

```
⛔ Blocked: python commands often fail (confidence: 95%)
💡 Suggestion: Use "python3 --version"
```

The shadow learner observed that `python` failed and is now protecting you from repeating the same mistake. This is intelligence building in real-time.

## Step 5: See Context Monitoring

Let's trigger the context monitoring system. The hooks track how much of Claude's conversation context you're using and automatically back up your work when it gets full.

Create several files to simulate a longer session:

> "Create a file called `test1.py` with a simple hello world script"

> "Now create `test2.py` with a different example"  

> "Create `test3.py` with some more code"

> "Show me the current git status"

As you work, you might see messages like:

```
Context usage: 23%
```

or 

```
Auto-backup created: activity_threshold (usage: 78%)
```

**Notice** how the system is quietly tracking your session and automatically creating backups. You don't have to think about it - your work is being preserved.

## Step 6: Experience Session Continuity

Now let's see session continuity in action. The system has been creating documentation about your session.

Run this command:

> "Show me the contents of LAST_SESSION.md"

You should see a file that looks like:

```markdown
# Last Claude Session Summary

**Session ID**: abc12345
**Duration**: 2024-01-15T14:30:00 → 2024-01-15T14:45:00

## Files Modified (3)
- test1.py
- test2.py  
- test3.py

## Tools Used (8 total)
- Write: 3 times
- Bash: 2 times
- Read: 3 times

## Recent Commands (5)
- `pip3 install requests` (2024-01-15T14:32:00)
- `python3 --version` (2024-01-15T14:35:00)
...
```

**This is your session history**. If Claude ever restarts or you lose context, you can reference this file to see exactly what you were working on.

## Step 7: Check What You've Accomplished

Let's see what the system has learned about your environment:

> "Run the command `claude-hooks status` to see session information"

You should see output showing:
- How many tools you've used
- Files you've modified  
- Current context usage
- Whether a backup is recommended

Now check the learned patterns:

> "Run `claude-hooks patterns` to see what the system has learned"

You should see entries like:

```
🖥️  Command Patterns:
  pip
    Confidence: 88%
    Evidence: 2 samples
    Success Rate: 0%
    
  python3  
    Confidence: 95%
    Evidence: 1 samples
    Success Rate: 100%
```

**This is the intelligence you've built**. The system now knows that on your machine, `pip` fails but `pip3` works, and `python3` works better than `python`.

## What You've Experienced

In the last 30 minutes, you've experienced all the core capabilities of Claude Hooks:

✅ **Command validation** - Dangerous commands blocked, alternatives suggested  
✅ **Shadow learning** - System learned from your failures and successes  
✅ **Context monitoring** - Automatic backups triggered by usage  
✅ **Session continuity** - Complete history preserved in LAST_SESSION.md

Most importantly, **none of this required you to configure anything or learn complex concepts**. The system worked intelligently in the background while you focused on your actual work.

## Next Steps

You now have Claude Hooks working and have experienced its core benefits. The system will continue learning from every command you run and every session you have.

When you're ready to go deeper:
- Read [How to restore from backups](../how-to/restore-backup.md) when you need to recover work
- Check [How to customize command patterns](../how-to/customize-patterns.md) to add your own validations
- Explore [Understanding the shadow learner](../explanation/shadow-learner.md) to understand how the intelligence works

**The most important thing**: Keep using Claude normally. Claude Hooks is now silently making your experience better, learning from every interaction, and protecting your work automatically.

You've gained a new superpower - Claude that gets smarter with every use.