claude/claude-code-tracker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add comprehensive hook installation system and update documentation

Browse source 
Major Features Added:
• Automated hook installation scripts (install-hooks.sh and setup-hooks)
• User-scope installation with automatic domain configuration
• 7 pre-configured hook profiles for different user types
• Comprehensive documentation updates across all guides

Hook Installation System:
• ./setup-hooks - One-liner installation for most users
• ./install-hooks.sh - Full-featured installer with profile selection
• Automatic domain replacement using $DOMAIN environment variable
• Settings backup and verification capabilities
• Safe uninstallation with rollback support

Documentation Enhancements:
• Updated README.md with complete project overview and proper git repository URL
• Enhanced Getting Started guide with automated hook installation
• Improved Docker deployment guide with hook installation step
• Reorganized documentation index with better visual hierarchy
• Added repository URL: https://git.supported.systems/claude/claude-code-tracker.git

Technical Improvements:
• Rebuilt Docker containers with all latest changes
• Verified application health and functionality
• Updated all installation examples with correct repository URL
• Improved quick start workflow with 3-step visual process

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Ryan Malloy 2025-08-11 09:30:37 -06:00
parent 50c80596d0
commit 1e1d4a995d
8 changed files with 1038 additions and 129 deletions
Download patch file Download diff file Expand all files Collapse all files

194
HOOKS.md Normal file
View file

@ -0,0 +1,194 @@
# 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.