{% extends "base.html" %} {% block title %}{{ title }}{% endblock %} {% block content %}

Hook Setup Guide

Configure Claude Code hooks for automatic activity tracking

10 min read

What are Claude Code Hooks?

Claude Code hooks are callback mechanisms that allow external applications (like this tracker) to receive notifications about various events in your Claude Code sessions. They enable real-time tracking of your development activity without manual intervention.

Benefits: Hooks provide automatic, real-time data collection, ensuring you never miss tracking a session or conversation.

Available Hook Types

session_start

Triggered when a new Claude Code session begins

Required
session_end

Triggered when a Claude Code session ends

Required
conversation_update

Triggered when conversation messages are added

Recommended
file_modified

Triggered when files are created or modified

Optional
tool_call

Triggered when Claude Code tools are used

Recommended

Setup Instructions

1
Ensure Claude Code Tracker is Running

The tracker server must be running to receive hook notifications.

Start the server:
python main.py
Server runs on http://localhost:8000 by default
Keep the server running while using Claude Code to ensure hooks work properly.
2
Locate Claude Code Settings

Find your Claude Code configuration file to add hooks.

macOS
~/.config/claude/settings.json
Linux
~/.config/claude/settings.json
Windows
%APPDATA%\claude\settings.json
Note: If the file doesn't exist, create it with the hook configuration below.
3
Add Hook Configuration

Add the hook configuration to your Claude Code settings file.

Basic Configuration
{
  "hooks": {
    "session_start": "curl -X POST http://localhost:8000/api/sessions/start -H 'Content-Type: application/json' -d '{\"project_path\": \"$PWD\", \"start_time\": \"$TIMESTAMP\"}'",
    "session_end": "curl -X POST http://localhost:8000/api/sessions/end -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"end_time\": \"$TIMESTAMP\"}'",
    "conversation_update": "curl -X POST http://localhost:8000/api/conversations -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"content\": \"$CONTENT\"}'",
    "tool_call": "curl -X POST http://localhost:8000/api/tool-calls -H 'Content-Type: application/json' -d '{\"tool_name\": \"$TOOL_NAME\", \"parameters\": $TOOL_PARAMS, \"result_status\": \"$RESULT_STATUS\", \"execution_time_ms\": $EXECUTION_TIME}'"
  }
}
Advanced Configuration
{
  "hooks": {
    "session_start": "curl -X POST http://localhost:8000/api/sessions/start -H 'Content-Type: application/json' -d '{\"project_path\": \"$PWD\", \"start_time\": \"$TIMESTAMP\", \"user\": \"$USER\"}'",
    "session_end": "curl -X POST http://localhost:8000/api/sessions/end -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"end_time\": \"$TIMESTAMP\"}'",
    "conversation_update": "curl -X POST http://localhost:8000/api/conversations -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"content\": \"$CONTENT\", \"timestamp\": \"$TIMESTAMP\"}'",
    "file_modified": "curl -X POST http://localhost:8000/api/activities -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"file_path\": \"$FILE_PATH\", \"action\": \"$ACTION\", \"timestamp\": \"$TIMESTAMP\"}'",
    "tool_call": "curl -X POST http://localhost:8000/api/tool-calls -H 'Content-Type: application/json' -d '{\"tool_name\": \"$TOOL_NAME\", \"parameters\": $TOOL_PARAMS, \"result_status\": \"$RESULT_STATUS\", \"execution_time_ms\": $EXECUTION_TIME, \"timestamp\": \"$TIMESTAMP\"}'"
  },
  "hook_settings": {
    "timeout": 5,
    "retry_count": 3,
    "async": true
  }
}
If you're running the tracker on a different port, update the URLs accordingly.
Custom Port Configuration
{
  "hooks": {
    "session_start": "curl -X POST http://localhost:YOUR_PORT/api/sessions/start -H 'Content-Type: application/json' -d '{\"project_path\": \"$PWD\", \"start_time\": \"$TIMESTAMP\"}'",
    "session_end": "curl -X POST http://localhost:YOUR_PORT/api/sessions/end -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"end_time\": \"$TIMESTAMP\"}'",
    "conversation_update": "curl -X POST http://localhost:YOUR_PORT/api/conversations -H 'Content-Type: application/json' -d '{\"session_id\": \"$SESSION_ID\", \"content\": \"$CONTENT\"}'",
    "tool_call": "curl -X POST http://localhost:YOUR_PORT/api/tool-calls -H 'Content-Type: application/json' -d '{\"tool_name\": \"$TOOL_NAME\", \"parameters\": $TOOL_PARAMS, \"result_status\": \"$RESULT_STATUS\"}'"
  }
}
Replace YOUR_PORT with your actual port number

Available Variables

Claude Code provides these variables that you can use in your hook commands:

Session Variables
  • $SESSION_ID
    Unique session identifier
  • $TIMESTAMP
    Current timestamp (ISO format)
  • $PWD
    Current working directory
Context Variables
  • $USER
    Current system user
  • $CONTENT
    Conversation content
  • $FILE_PATH
    Modified file path
  • $TOOL_NAME
    Name of tool being called
  • $TOOL_PARAMS
    Tool parameters (JSON object)
  • $RESULT_STATUS
    Success/error status

Testing Your Hook Setup

Quick Test: Start a new Claude Code session after setting up hooks. You should see new data appearing in the tracker dashboard.
Manual Testing

You can test individual hooks manually to ensure they work:

Test session start hook:
curl -X POST http://localhost:8000/api/sessions/start -H 'Content-Type: application/json' -d '{"project_path": "/path/to/project", "start_time": "2024-01-01T12:00:00"}'
Check server logs:
tail -f logs/tracker.log
Troubleshooting

  • Check that curl is installed on your system
  • Verify the tracker server is running
  • Test the hook URL manually in a browser or with curl
  • Check Claude Code logs for hook execution errors

  • Check the tracker server logs for incoming requests
  • Verify the JSON payload format matches API expectations
  • Ensure the database is writable
  • Try refreshing the dashboard after a few minutes
Quick Reference
Default Server URL
http://localhost:8000
Settings File Location
macOS/Linux:
~/.config/claude/settings.json
Windows:
%APPDATA%\claude\settings.json
Contents
Need Help?

Still having trouble with hooks?

Check FAQ API Reference
{% endblock %}