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:

# 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:

./setup-hooks

install-hooks.sh (Full control)

Comprehensive installation script with multiple options:

# 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

export DOMAIN=your-domain.com
./setup-hooks

Option 2: .env File

Create a .env file in the project directory:

echo "DOMAIN=your-domain.com" > .env
./setup-hooks

Option 3: Command Line

./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:

{
  "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:

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 for detailed instructions.

Uninstalling

To remove all hooks:

./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:

./install-hooks.sh -d new-domain.com comprehensive

Development Setup

For development with local servers:

./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.