hook-hero

Hook Hero

Structured telemetry for Claude Code. Captures every hook event across your sessions — tools, tokens, costs, git activity, subagents, and more — with msgpack compression, optional encryption, and a real-time terminal dashboard.

Install

Prerequisites: Node.js (v18+) and Claude Code.

git clone https://github.com/damahua/claude-code-hook-hero.git
cd claude-code-hook-hero
npm run setup

Telemetry starts flowing on your next Claude Code session and persists across all future sessions.

Uninstall

cd claude-code-hook-hero
npm run unsetup

This removes the plugin and stops all hook registration. Your existing telemetry data in ~/.claude/hook-hero/ is not deleted — remove it manually if you no longer need it:

rm -rf ~/.claude/hook-hero

What It Captures

Hook Hero registers 14 hooks that fire automatically during every session:

Hook	What it records
SessionStart	Channel (claude-code / claude-cli), project context, git branch, model
SessionEnd	Final session summary written to disk
UserPromptSubmit	Prompt count tracking
PreToolUse	Tool invocation intent
PostToolUse	Tool result, duration
PostToolUseFailure	Tool errors and failure counts
Stop	Token usage from transcript, cost calculation, git diff stats
SubagentStart	Subagent type and spawn tracking
SubagentStop	Subagent duration and completion
PreCompact / PostCompact	Context compaction events
WorktreeCreate / WorktreeRemove	Git worktree lifecycle
TaskCompleted	Task completion count

Data Storage

All telemetry is stored locally under ~/.claude/hook-hero/:

~/.claude/hook-hero/
├── sessions/{date}/{session_id}.json     # Session summaries (JSON, human-readable)
├── events/{date}/{session_id}.events     # Raw hook events (msgpack, compressed)
├── buffer/{session_id}.buf               # Live session state (msgpack)
├── debug/{date}/{session_id}.jsonl       # Debug entries (JSONL, human-readable)
├── config.json                           # User config overrides (optional)
└── .key                                  # Encryption key (auto-generated, chmod 600)

Events and buffers use MessagePack with dictionary compression by default (~47% smaller than JSON). Session summaries and debug logs stay as human-readable JSON/JSONL. Old JSON/JSONL files are auto-detected and readable regardless of current format setting.

Nothing leaves your machine. All data stays on local disk.

Session Summary Schema

Each completed session produces a JSON summary with the following structure:

{
  "schema_version": "1.0",
  "session_id": "abc123",
  "channel": "claude-code",           // or "claude-cli"
  "timing": {
    "start_time": "2026-03-20T10:00:00Z",
    "end_time": "2026-03-20T10:45:00Z",
    "duration_seconds": 2700
  },
  "context": {
    "project_path": "/Users/you/Work/my-project",
    "project_name": "my-project",
    "repo": "you/my-project",
    "git_branch": "feature/new-api",
    "model": "claude-opus-4-6"
  },
  "tools": {
    "total_calls": 47,
    "by_type": { "Read": 12, "Edit": 8, "Bash": 15, "Write": 5, "Grep": 7 },
    "failures": 1
  },
  "tokens": {
    "input": 125000,
    "output": 42000,
    "total": 167000,
    "cache_read": 95000,
    "cache_write": 30000,
    "estimated_cost_usd": 1.23
  },
  "git": {
    "commits_made": 3,
    "branches_touched": ["feature/new-api"],
    "files_changed": 8,
    "insertions": 245,
    "deletions": 67,
    "prs_created": 1
  },
  "prompts": { "count": 12 },
  "subagents": { "total_spawned": 2, "by_type": { "Explore": 1, "general-purpose": 1 }, "total_duration_ms": 45000 },
  "compactions": { "count": 1 },
  "worktrees": { "created": 0, "removed": 0 },
  "tasks": { "completed": 4 }
}

The full JSON Schema is available in config/schema.json.

Terminal Dashboard

Hook Hero includes a real-time terminal dashboard built with Ink.

Install the CLI

cd dashboard
npm install
npm link

This makes the hook-hero command available globally:

hook-hero live                        # Real-time monitoring
hook-hero history                     # Review today's sessions
hook-hero history --date 2026-03-19   # Review a specific date
hook-hero export --session <id>       # Export session as JSON

Export Command

Decrypt and export session data as readable JSON — useful for external analysis, piping to jq, or sharing session reports.

# List available sessions
hook-hero export --date 2026-03-20

# Export a specific session summary
hook-hero export --session 24768f42