How It Works

Claude Code Hooks

Claude Code supports hooks — shell commands that run automatically in response to events during a session. neun 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 neun-cli 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 neun-cli 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 neun-cli setup again.

Settings Scope

When you run neun-cli 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 neun-cli login and neun-cli setup to authenticate and get their own ingest token. The hooks configuration is shared, but credentials are always local.