Real-time Hooks

Since v0.3.0, claude-telemetry syncs data the moment your Claude Code session ends — no more waiting for the 15-minute polling cycle.

How It Works

Claude Code supports lifecycle hooks that run shell commands on specific events. claude-telemetry uses two hooks:

• SessionEnd — fires when a Claude Code session ends normally
• Stop — fires when you manually stop Claude Code (2-minute debounce to avoid spam)

When either hook fires, it launches a sync process in the background using a detached process pattern. This means:

• The hook script returns in under 100ms — zero blocking of Claude Code
• The actual sync runs in a separate process
• Data appears in your dashboard within seconds of ending a session

Setup

cc-telemetry setup-hooks

This creates hook scripts and registers them in Claude Code's settings. You can also set up hooks as part of the unified setup wizard (cc-telemetry setup).

Coexistence with Polling

Hooks are the primary sync method, but the polling daemon is kept as a 60-minute backup. This handles edge cases where:

• A hook might not fire (e.g., VS Code extension behavior under investigation)
• The machine was offline when the session ended
• Claude Code was killed without triggering a Stop event

The daemon reconciles any missed sessions every hour.

Verifying Hooks

Run the doctor command to check that hooks are configured:

cc-telemetry doctor

Look for:

Hooks configured       ✓ SessionEnd + Stop
Hook sync active       ✓ 12 minutes ago

Architecture Credit

The detached process pattern was inspired by @mikeadolan's work on claude-brain. Special thanks for the architecture insights.

Technical Details

• Hook scripts are stored in ~/.claude-telemetry/hooks/
• They use nohup (Linux/macOS) or Start-Process -WindowStyle Hidden (Windows) for detachment
• Logs go to ~/.claude-telemetry/logs/hook-sync.log with rotation (10 MB max, 5 backups)
• The Stop hook has a 2-minute debounce to prevent rapid-fire syncs during interactive sessions