hookwatch

claude-hookwatch

See what Claude did, debug your hooks, query your sessions — local observability for Claude Code with SQLite storage and a live web UI.

Quick Start

Get from zero to seeing events in under 2 minutes:

# 1. Clone and install
git clone https://github.com/PabloLION/claude-hookwatch.git
cd claude-hookwatch
bun install

# 2. Start Claude Code with hookwatch
claude --plugin-dir "$PWD"

# 3. Use Claude normally — every hook event is captured

# 4. Open the web UI to browse events
hookwatch ui

The web UI opens at http://localhost:6004 with a live-updating event timeline.

Demo

Demo coming soon — a short walkthrough showing hookwatch capturing events in real time.

Features

• Plugin install — hookwatch install registers the plugin, hookwatch uninstall removes it cleanly
• 18 hook events — PreToolUse, PostToolUse, SessionStart, Stop, and 14 more — every event Claude Code emits
• Web UI — real-time event timeline with session filter, event detail, and wrap viewer
• SQLite storage — bun:sqlite with WAL mode, fast queries, zero external deps
• Zod validation — all 18 stdin payloads validated at runtime
• Wrap mode — wrap any command to capture its stdin/stdout/stderr alongside the hook event
• SSE live updates — events appear in the UI as they happen, no polling
• Offline-first — localhost only, no network calls, no accounts, no config files required

Web UI

hookwatch serves a local web UI at http://localhost:6004:

• Real-time event timeline with SSE live updates
• Filter by session, event type, tool name, time range
• Event detail viewer with full stdin payload
• Wrap viewer for wrapped command I/O (solid badge = wrapped, outline = bare)

Install

hookwatch install

For local dev:

bun install && bun link

To uninstall:

hookwatch uninstall

Dev Commands

bun run dev      # start server with --watch (auto-reload on file changes)
bun run test     # run test suite (targets src/ and integration test files)
bun run lint     # lint and format check (Biome)

Storage

Events are stored in a SQLite database:

~/.local/share/hookwatch/hookwatch.db

The path respects $XDG_DATA_HOME if set: $XDG_DATA_HOME/hookwatch/hookwatch.db

Column	Type	Description
id	INTEGER PRIMARY KEY	Auto-incrementing event ID
timestamp	INTEGER NOT NULL	Epoch milliseconds (generated at write time)
event	TEXT NOT NULL	Hook event type (e.g. PreToolUse)
session_id	TEXT NOT NULL	From hook stdin
cwd	TEXT NOT NULL	Working directory at time of event
tool_name	TEXT	Tool name for tool events, NULL otherwise
session_name	TEXT	Human-readable session name
hook_duration_ms	INTEGER	hookwatch handler execution time in milliseconds
stdin	TEXT NOT NULL	Full event JSON from hook stdin
wrapped_command	TEXT	Command being wrapped, NULL for bare handler events
stdout	TEXT	Hook output JSON (bare) or captured child stdout (wrapped); NULL if no output
stderr	TEXT	Captured child stderr for wrapped events; NULL for bare events
exit_code	INTEGER NOT NULL DEFAULT 0	Exit code of the hook or wrapped child process
hookwatch_log	TEXT	Internal diagnostics with severity prefix: [error] or [warn]; NULL if no issues

The full stdin schema for all 18 event types is documented in ./docs/reference/hook-stdin-schema.md.

Hook Events

All 18 Claude Code hook event types are captured:

Event	Description
PreToolUse	Before a tool executes
PostToolUse	After a tool executes successfully
PostToolUseFailure	After a tool execution fails
UserPromptSubmit	When the user submits a prompt
Notification	System notifications
PermissionRequest	When a permission is requested
Stop	When the agent stops
SessionStart	Session begins
SessionEnd	Session ends
SubagentStart	Sub-agent spawned
SubagentStop	Sub-agent finished
PreCompact	Before context compaction
TeammateIdle	Teammate becomes idle
TaskCompleted	Task marked complete
ConfigChange	Configuration changed
WorktreeCreate	Git worktree created
WorktreeRemove	Git worktree removed
InstructionsLoaded	Instructions loaded (SDK-only — not in hooks reference docs)

17 events are documented in the hooks reference. InstructionsLoaded is the 18th — present in the Agent SDK types (@anthropic-ai/claude-agent-sdk) but not yet in the hooks reference.

Known Limitations

hookwatch is v0 software under active development. These are upstream behaviors, not hookwatch bugs.