How It Works

Claude Code Hooks

Claude Code supports hooks — shell commands that run automatically in response to events during a session. Watchdawg registers hooks during setup to capture telemetry without interfering with your workflow.

The following events are captured:

Event	What it captures
SessionStart	A new session began
SessionEnd	Session ended, including final token counts
UserPromptSubmit	A prompt was sent to Claude
PostToolUse	Claude used a tool (file edit, bash, etc.)
PostToolUseFailure	A tool execution failed
Stop	Claude stopped generating
SubagentStart	A sub-agent was spawned
SubagentStop	A sub-agent finished
Notification	A notification was triggered
PreCompact	Conversation was compacted

Data Flow

Claude Code hooks → CLI sidecar → Collector → Dashboard

Hooks fire — Claude Code triggers a hook command on each event
CLI sidecar processes — the watchdawg sidecar command (registered by setup) receives the event data via stdin, transforms it, and parses transcript files for token usage
Collector ingests — events are sent to the collector service, which batches and stores them
Dashboard displays — the web app queries the data and surfaces it as charts, tables, and session timelines

The sidecar runs as a short-lived process for each event. It never blocks Claude Code — hooks have a timeout (5 seconds for most events, 30 seconds for session end) and the sidecar always exits with code 0.

What Gets Collected

Token usage — input/output tokens per model, per session
Cost — computed from token counts and model pricing
Tool calls — which tools Claude used and how often
File changes — which files were read or modified
Session metadata — duration, timestamps, branch, commit
Prompts — the text of user prompts (opt-in, disabled by default)

Privacy

Prompt content logging is opt-in. During watchdawg setup, you choose whether to include prompt text in telemetry. If disabled, prompts are not sent to the collector — only metadata like token counts and tool usage is captured.

You can change this setting at any time by running watchdawg setup again.

Settings Scope

When you run watchdawg setup, you choose where hooks are registered:

Local — .claude/settings.local.json in your project. Only applies on your machine, not committed to version control.
Project — .claude/settings.json in your project. Shared with your team via version control. Everyone who clones the repo gets the hooks.
Global — ~/.claude/settings.json in your home directory. Applies to all projects on your machine.

If you use project scope, your teammates still need to run watchdawg login and watchdawg setup to authenticate and get their own ingest token. The hooks configuration is shared, but credentials are always local.