Claudehub Monitor

Disclaimer. This software is provided AS IS, without warranty of any kind, express or implied. Use it entirely at your own risk. The author accepts no liability for data loss, corruption, hardware damage, business interruption, quota or usage consumed, or any consequential damages. It runs an HTTP server on your network and, when Claude Code credentials are present, makes small API calls with them to read your usage; you are responsible for who can reach that server and for being authorised to use the account. It is not certified for regulated, forensic, safety-critical or high-assurance use. The LICENSE file is the governing text and prevails wherever this note and the licence differ.

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>",
  "client": "<launcher>",        // CLAUDE_CODE_ENTRYPOINT, e.g. "claude-vscode"; "" if unset
  "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)
• VS Code (W): N active session(s) (T total) and Claude Desktop: Running, both refreshed every 2 seconds (independent of the 5-minute quota refresh above, since this changes far more often than quota). Each row is hidden entirely when there is nothing to report.

If credentials are missing, the toast is skipped.

Where those numbers come from

The three session numbers are deliberately from two different sources, because neither alone is correct:

Claude Desktop: Running is also a local process scan. The native Claude Desktop app talks to Claude over MCP, not through Claude Code's hook system, so it can never report to this monitor over HTTP — the only way to know it is open is to look at the OS process list on the machine the monitor itself runs on. That also means it reports only on local Claude Desktop, never on a remote machine sending hook events here.

Both apps ship an executable named claude.exe, so they are told apart by executable path (the VS Code extension's bundled native-binary path versus the app's WindowsApps install), never by process name. All of these scans are Windows-only and fail closed: if a scan cannot run, the row is hidden rather than showing a misleading 0 or not running.

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/usage (for phones and widgets)

Returns the cached result of the usage toast's 5-minute probe, so polling it costs nothing. ?refresh=1 asks for a fresh probe; that is a real 1-token call against your quota, so at most one is started per minute and extra requests just get the cached reading.

{
  "service": "claudehub", "version": "0.4.0", "host": "DESKTOP-1",
  "instance_id": "454a1bd4...", "account": {"email": "you@example.com", "plan": "max", "org": ""},
  "fetched_at": 1792844418.9, "overall_status": "allowed", "error": "", "refreshing": false,
  "session": {"status": "allowed", "utilization": 0.20, "reset": 1792857000},
  "weekly":  {"status": "allowed", "utilization": 0.67, "reset": 1792904400}
}

utilization is a fraction (0.67 = 67%), reset is a Unix time in seconds. Before the first probe finishes, or on a PC with no Claude Code login, it answers 503 with an error string. If a later probe fails, the last good reading is kept and error says why.

instance_id is a UUID made once per PC (~/.claude/claudehub_instance_id), so a client that finds several monitors can tell them apart, and account lets it group PCs logged in to the same Claude account. No token is ever sent.

Discovery. pip install claudehub-monitor[discovery] adds zeroconf, and the monitor then advertises itself on the LAN as _claudehub._tcp (mDNS). A client can also find it by probing port 7070 for a /health answer with "service": "claudehub".

Locking it down. Set monitor.api_token in monitor_config.json to make /api/usage require an X-ClaudeHub-Token: <token> header. /health stays open for discovery but then leaves out the account. The rest of the dashboard API is unchanged and, like before, open to anything that can reach port 7070.

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,
                 "api_token": "" },
  "logging":   { "level": "INFO", "file": "", "max_bytes": 1048576, "backup_count": 5 },
  "sounds":    { "enabled": true },
  "notifications": { "enabled": false },
  "usage":     { "refresh_minutes": 5, "manual_refresh_min_seconds": 60 }
}

usage sets how often the quota probe runs. Every probe is a real 1-token API call on your subscription, so this is the one setting that costs something:

• refresh_minutes (default 5): how often the toast and /api/usage get a new reading. Clamped to 1 minute to 24 hours. 0 turns the timer off: one reading at start, then only when a client asks with ?refresh=1. Env var: CLAUDE_MONITOR_USAGE_MINUTES.
• manual_refresh_min_seconds (default 60): the shortest gap between probes a client can trigger with ?refresh=1. Clamped to 10 seconds to 1 hour.

Clients polling /api/usage without ?refresh=1 never cause a probe, however often they poll. /api/usage reports both values as refresh_seconds and manual_refresh_min_seconds.

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.