claude-code-tracker/HOOKS.md

# Claude Code Tracker - Hook Installation Guide

This document explains how to set up Claude Code hooks for automatic tracking of your development activity.

## Quick Start

For most users, the automatic installation is the easiest approach:

```bash
# Set your domain
export DOMAIN=your-domain.com

# Run the installer (installs comprehensive profile)
./setup-hooks
```

## Installation Scripts

### `setup-hooks` (Recommended for beginners)
Simple wrapper that installs the comprehensive hook profile:
```bash
./setup-hooks
```

### `install-hooks.sh` (Full control)
Comprehensive installation script with multiple options:

```bash
# Show help
./install-hooks.sh --help

# List available profiles
./install-hooks.sh --list

# Install specific profile
./install-hooks.sh basic
./install-hooks.sh comprehensive
./install-hooks.sh developer

# Install with custom domain
./install-hooks.sh -d your-domain.com comprehensive

# Verify installation
./install-hooks.sh --verify

# Remove all hooks
./install-hooks.sh --uninstall
```

## Available Hook Profiles

| Profile | Description | Hook Count | Best For |
|---------|-------------|------------|----------|
| `basic` | Essential hooks only | 5 | New users, minimal tracking |
| `essential` | Core development tracking | 8 | Most users |
| `comprehensive` | All available hooks | 39+ | Complete tracking, recommended |
| `developer` | Active development focused | 15 | Professional developers |
| `power_user` | Advanced features | 20 | Power users, detailed analytics |
| `research` | Research and analytics | 25 | Research, data analysis |
| `team` | Team collaboration | 18 | Team environments |

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `DOMAIN` | Your Claude Code Tracker domain | `claude.example.com` |

You can set the domain in several ways:

### Option 1: Environment Variable
```bash
export DOMAIN=your-domain.com
./setup-hooks
```

### Option 2: .env File
Create a `.env` file in the project directory:
```bash
echo "DOMAIN=your-domain.com" > .env
./setup-hooks
```

### Option 3: Command Line
```bash
./install-hooks.sh -d your-domain.com comprehensive
```

## How It Works

The installation script:

1. **Validates requirements** - Checks for Claude Code and domain configuration
2. **Backs up existing settings** - Preserves your current Claude Code configuration
3. **Updates hook URLs** - Replaces placeholders with your actual domain
4. **Merges configurations** - Combines hooks with existing settings
5. **Installs to user scope** - Places configuration in `~/.config/claude-code/settings.json`
6. **Verifies installation** - Checks that hooks were installed correctly

## File Locations

| File | Purpose |
|------|---------|
| `~/.config/claude-code/settings.json` | Main Claude Code settings with hooks |
| `~/.config/claude-code/settings.json.backup.*` | Backup of previous settings |

## Hook Examples

After installation, your `settings.json` will contain hooks like:

```json
{
  "hooks": {
    "session_start": "curl -X POST https://your-domain.com/api/sessions/start -H \"Content-Type: application/json\" -d '{\"project_path\": \"$PWD\", \"start_time\": \"$TIMESTAMP\"}'",
    "session_end": "curl -X POST https://your-domain.com/api/sessions/end -H \"Content-Type: application/json\" -d '{\"session_id\": \"$SESSION_ID\", \"end_time\": \"$TIMESTAMP\"}'",
    "conversation_update": "curl -X POST https://your-domain.com/api/conversations -H \"Content-Type: application/json\" -d '{\"session_id\": \"$SESSION_ID\", \"content\": \"$CONTENT\"}'"
  }
}
```

## Troubleshooting

### "Claude Code is not installed"
Install Claude Code first: https://claude.ai/code

### "DOMAIN environment variable is not set"
Set your domain:
```bash
export DOMAIN=your-domain.com
```

### "Hook profile file not found"
Make sure you're running the script from the project directory where the `claude-hooks-*.json` files are located.

### "Settings file contains invalid JSON"
Your existing Claude Code settings may be corrupted. Check `~/.config/claude-code/settings.json` or restore from a backup.

### Hooks not triggering
1. Verify installation: `./install-hooks.sh --verify`
2. Check that your tracker server is running
3. Test connectivity: `curl https://your-domain.com/health`
4. Check Claude Code logs for hook execution errors

## Manual Installation

If you prefer to install hooks manually, see the [Hook Setup Guide](https://your-domain.com/dashboard/docs/hook-setup) for detailed instructions.

## Uninstalling

To remove all hooks:

```bash
./install-hooks.sh --uninstall
```

This will:
- Backup your current settings
- Remove the `hooks` section from your Claude Code settings
- Preserve all other configuration options

## Advanced Usage

### Custom Hook Profiles
You can create custom hook profiles by:
1. Copying an existing `claude-hooks-*.json` file
2. Modifying the hooks as needed
3. Running the installer with your custom profile name

### Multiple Domains
To switch domains, simply run the installer with a new domain:
```bash
./install-hooks.sh -d new-domain.com comprehensive
```

### Development Setup
For development with local servers:
```bash
./install-hooks.sh -d localhost:8000 developer
```

## Security Notes

- Hooks are installed in user scope only (no system-wide changes)
- All communication uses HTTPS (except localhost)
- No sensitive data is transmitted in hook payloads
- Settings backups are created automatically
- Uninstallation is safe and reversible

## Support

- **Documentation**: https://your-domain.com/dashboard/docs
- **Hook Reference**: https://your-domain.com/dashboard/docs/hook-reference  
- **API Docs**: https://your-domain.com/docs

For issues with the installation script, check the troubleshooting section above or review the detailed documentation.