Claudehub Monitor

A desktop and LAN web dashboard that shows what Claude Code is doing in real time — across every repo and machine on your network.

claudehub-monitor is the central collector: Claude Code hooks POST lifecycle events to it over HTTP, and it surfaces them as an animated desktop card, system sounds, a scrolling history, a usage quota toast, and a live web page you can open from your phone.

  Claude Code (any repo / any machine)
        │  hook fires  →  claudehub-hooks  →  HTTP POST /event
        ▼
  claudehub-monitor  ──►  desktop flash card + toasts + sounds + history (SQLite)
        │
        └─►  web dashboard  ◄── browser on the LAN (SSE live updates)

Quick start

1. Start the monitor (once per machine):

pip install claudehub-monitor
claudehub          # short alias
claudehub-monitor  # full name (same command)

2. Wire hooks into each repo you use with Claude Code:

pip install claudehub-hooks
claudehub-hooks install
claudehub-hooks install --url http://192.168.1.50:7070/event   # remote monitor

3. Open Claude Code in that repo — events flow to the monitor automatically.

Test hook connectivity:

python .claude/hooks/claude_hook.py --test

Install

Monitor (claudehub-monitor):

pip install claudehub-monitor
claudehub          # short alias
claudehub-monitor  # full name (same command)

Hooks (claudehub-hooks — separate package, stdlib only):

pip install claudehub-hooks
claudehub-hooks install

Components

Hook events

claudehub-hooks install registers these Claude Code hooks:

Hook self-test (claude_hook.py --test) sends __test__ — shown on the card as a purple “Test” flash (not recorded in history).

Event payload (from hooks)

Hooks POST JSON to POST /event:

{
  "event": "PostToolUse",
  "datetime": "<ISO-8601 UTC>",
  "session_id": "<str>",
  "host": "<hostname>",
  "cwd": "<working dir>",
  "files": ["<path>"],           // PostToolUse
  "prompt": "<first 500 chars>", // UserPromptSubmit
  "tool_name": "<tool>",         // PostToolUse / Permission* / PreToolUse
  "command": "<cmd>",            // Permission* / PreToolUse
  "notification_type": "<type>", // Notification
  "error_type": "<type>",        // StopFailure
  "error_message": "<msg>"       // StopFailure
}

Status model

Each surfaced status maps to colour, icon, and animation on the desktop:

Read/Edit briefly flash, then the card returns to Thinking until the turn ends (Stop) — mirroring how Claude actually works. The desktop card shows the status name; the history table and web feed show the matching icon.

Usage toast

When Claude Code OAuth credentials exist (~/.claude/.credentials.json), a fixed top-right toast shows subscription quota:

• 5-hour session and 7-day weekly utilization (%)
• Reset times for each window
• Refreshed every 5 minutes (one minimal Haiku probe call per refresh)

If credentials are missing, the toast is skipped.

Run it

claudehub
claudehub-monitor
python -m claudehub

The app starts hidden in the system tray by default (the HTTP server and web dashboard run regardless). Double-click the tray icon to open the window; "Minimize to Tray" or closing the window hides it again; the tray menu's Quit exits. Only one instance runs per machine.

Web dashboard (view on the go)

With the monitor running, open from any device on the LAN:

http://<monitor-ip>:7070/

It shows a live grid of active sessions, the last prompt, and a recent-activity feed — pushed over Server-Sent Events (auto-reconnecting), with a JSON snapshot for the initial load.

Group by repo: check "Group by repo" in the header to re-arrange the session grid into one section per repository (derived from each hook's reported cwd), rather than one flat grid. Useful once several repos are reporting to the same monitor at once — a session with no cwd on record groups under "(unknown)" rather than being dropped.

History & search: the collapsed "History & search" panel below the recent- activity feed queries the full event history (not just the last few events), filterable by host, repo, event type, and date range. It only fetches once opened, so a normal dashboard view pays nothing for it.

Subagent count: when a session launches one or more subagents (Claude Code's Task tool), its card shows a small "+N agents running" badge for as long as any are still in flight. This is a count, not a breakdown — see "Subagent visibility" below for why the hook payload doesn't support more.

Open TCP 7070 on the monitor machine's firewall:

New-NetFirewallRule -DisplayName "Claude Monitor" -Direction Inbound `
  -Protocol TCP -LocalPort 7070 -Action Allow

HTTP API

GET /api/history query parameters

Queries the full events table directly, not the small capped in-memory feed /api/events reads from.

Response: {"events": [...], "total": <int>, "limit": <int>, "offset": <int>}.

Note: since/until filter on a column (received_at_iso) added in 0.2.0. Events recorded by an older version have it unset and are excluded from any date-filtered query rather than matching incorrectly — the older received_at column is local time-of-day only (no date), so it cannot support a range filter at all.

Configuration

Monitor (claudehub-monitor)

Copy monitor_config.json to ~/.claude/monitor_config.json, or set CLAUDE_MONITOR_CONFIG to point at a file:

{
  "transport": { "http": { "enabled": true, "url": "http://127.0.0.1:7070/event", "timeout_s": 2.0 } },
  "monitor":   { "http_host": "0.0.0.0", "http_port": 7070, "history_max": 50, "start_hidden": true },
  "logging":   { "level": "INFO", "file": "", "max_bytes": 1048576, "backup_count": 5 },
  "sounds":    { "enabled": true },
  "notifications": { "enabled": false }
}

notifications.enabled (default false) turns on Windows action-center notifications for Waiting and Error states, in addition to — not instead of — the existing sound and in-app toast. Uses the tray icon already created for the system-tray feature, so there's no extra dependency; it is a no-op if there's no system tray available.

Monitor env vars (override the file): CLAUDE_MONITOR_CONFIG, CLAUDE_MONITOR_PORT, CLAUDE_MONITOR_HOST, CLAUDE_MONITOR_SOUNDS, CLAUDE_MONITOR_NOTIFY, CLAUDE_MONITOR_LOG_LEVEL, CLAUDE_MONITOR_LOG_FILE.

Logs and the SQLite database default to ~/.claude/.

Hooks (claudehub-hooks)

Per-repo transport config lives at .claude/hooks/monitor_config.json (created by claudehub-hooks install). Point hooks at a monitor on another machine:

{
  "transport": {
    "http": { "url": "http://192.168.1.50:7070/event" }
  }
}

Hook env vars (override the file):

Subagent visibility

The card and dashboard show a count of subagents currently in flight under a session ("+2 agents running") — incremented on the PreToolUse for Claude Code's Task tool, decremented on the matching PostToolUse.

This is deliberately a count, not a per-subagent breakdown. A subagent's own inner tool calls (its own Reads, Edits, etc.) do not reach this monitor's hooks at all — only the outer call, the parent session invoking the Task tool, produces a PreToolUse/PostToolUse pair. Building true nested visibility (each subagent's own activity, individually) is not something the current Claude Code hook contract supports from the monitor side; it would need a change on that side, not here.

Multi-instance & reopen recovery

The monitor tracks status per session in SQLite, so:

• Several Claude instances (local or remote) can report at once — the card shows the latest, the history/web distinguish by host + session.
• If you close and reopen the monitor mid-turn, it restores the in-progress state from session_status; a 2-second watchdog idles a session that goes silent.

Requirements

• Python 3.11+ (monitor); Python 3.10+ (hooks)
• claudehub-monitor: PySide6 and anthropic (installed automatically)
• claudehub-hooks: stdlib only
• Windows for sounds (winsound); silently disabled elsewhere.