How parthmashroo/claude-code-monitor works
1. Overall shape
- This repo is a very small, mostly self-contained desktop application: one main Python/Tkinter process in monitor.py, plus one optional Claude Code hook script in hooks/capture-session.py.
- There is no backend service, database, or local daemon. The widget process owns the whole runtime.
2. Primary runtime boundary: the desktop widget
- monitor.py creates a 30px-tall always-on-top floating window.
- The UI is intentionally minimal: it displays usage counters, rate-limit bars, and session stats, and supports only drag, right-click theme switching, and close.
- The app is meant to sit on the desktop above other apps, including VS Code.
3. Data source #1: Anthropic usage API
- The widget makes a real network call to api.anthropic.com/api/oauth/usage.
- This is the source of the 5h and 7d quota percentages and reset timestamps.
- The README makes clear this uses the user’s existing Claude Code OAuth session; no separate authentication flow or account setup is introduced by this repo.
4. Data source #2: local Claude project transcripts
- monitor.py scans ~/.claude/projects/**/*.jsonl for today’s token and cost totals.
- These files are local Claude Code project logs, aggregated across all projects and tabs.
- This is a pure read-only local filesystem boundary; the widget does not modify the project transcripts.
5. Data source #3: optional session hook output
- hooks/capture-session.py is an optional Claude Code “Stop” hook that receives JSON on stdin, including session_id and transcript_path.
- It parses the current session transcript and writes per-session stats to ~/.claude/widgets/claude-code-monitor/session_data.json.
- monitor.py reads that file to populate the sess column; without the hook, the widget still works, but session stats show --.
6. Persistence and local state
- The app persists user-specific state in ~/.claude/widgets/claude-code-monitor/.
- config.json stores widget position and theme.
- session_data.json stores hook-generated session totals.
- This separation keeps the live widget stateless except for reading/writing small local JSON files.
7. Refresh model
- The widget polls the Anthropic usage API every 60 seconds.
- It re-reads local token/session data every 5 seconds.
- The countdown timers are derived locally from stored reset timestamps and update more frequently than the API poll, so the display feels live without constant network traffic.
8. UI state and theming
- Theme selection is handled inside the widget process and persists across restarts.
- The right-click theme picker maps to 10 built-in themes, grouped into dark and light variants.
- Position is also persisted, so the widget resumes where the user left it.
9. OS integration boundary: startup registration
- On first run, monitor.py registers itself to auto-start at login.
- It uses platform-native mechanisms: Windows registry Run key, macOS LaunchAgent plist, or Linux autostart desktop entry.
- This is one of the few places where the app crosses from pure application logic into OS configuration.
10. Security and trust model
- The app’s trust boundary is intentionally narrow: local reads from Claude-owned files plus one outbound request to Anthropic for the user’s own usage stats.
- There is no telemetry, analytics pipeline, or third-party service in the architecture.
- That makes the repo essentially a local observability widget for Claude Code usage, with optional hook-based augmentation for session-level stats.
Main entry points: monitor.py Widget app · capture-session.py Hook parser
Components 17
Desktop widget
Main Python/Tkinter process that owns the UI, refresh loops, and app behavior.
- Widget app · Floating always-on-top desktop widget and process entrypoint.
monitor.py - Compact UI · Shows usage counters, quota bars, and session stats in a 30px desktop strip.
monitor.py - Refresh loops · Polls network and local state on different intervals to keep the display current.
monitor.py - Usage fetch · Calls Anthropic usage endpoint for 5h and 7d quota state and reset times.
monitor.py - Transcript scan · Scans Claude project JSONL logs to aggregate today’s tokens and cost totals.
monitor.py - Session stats · Displays per-session totals when hook-generated data is available; falls back to placeholders otherwise.
monitor.py - Theme state · Handles built-in theme selection and persists the chosen look across restarts.
monitor.py - Window state · Tracks widget position and drag behavior so the window reopens where the user left it.
monitor.py - Auto-start setup · Registers the widget to launch at login using the host platform’s native mechanism.
monitor.py - Stop hook · Optional Claude Code hook that receives session metadata and transcript paths on stdin.
hooks/capture-session.py - Hook parser · Extracts the current session’s token and cost totals from the provided transcript.
hooks/capture-session.py
Local state
Read-only Claude project logs plus small per-user JSON files under the widget data directory.
- Session writer · Writes per-session totals to the local widget data directory.
- Config file · Stores widget position and theme selection.
- Session file · Stores hook-generated session totals for the widget to read.
- Claude logs · Local Claude project JSONL transcripts aggregated across projects and tabs.
Outside systems
Anthropic API and OS startup mechanisms the app integrates with.
- Anthropic API · OAuth usage endpoint used for quota and reset information.
- OS startup · Windows Run key, macOS LaunchAgent, or Linux autostart entry.
Connections 17
- Widget app → Compact UI: renders · Creates the floating widget and updates the compact display.
- Widget app → Refresh loops: drives · Coordinates periodic refresh of network and local data.
- Refresh loops → Usage fetch: polls · Refreshes remote quota data on a slower interval.
- Refresh loops → Transcript scan: reads · Re-reads today’s local token and cost totals frequently.
- Usage fetch → Anthropic API: requests · Fetches the user’s Claude usage state from Anthropic.
- Transcript scan → Claude logs: scans · Aggregates values from local project transcript JSONL files.
- Widget app → Session stats: shows · Populates the session column from optional hook output.
- Stop hook → Hook parser: passes · Receives session metadata and transcript path from Claude Code.
- Hook parser → Session writer: writes · Persists parsed per-session totals for the widget.
- Session writer → Session file: stores · Writes session_data.json under the widget data directory.
- Widget app → Session file: reads · Loads hook-generated session data when available.
- Widget app → Theme state: updates · Handles right-click theme switching inside the widget process.
- Theme state → Config file: persists · Saves theme choice for restart reuse.
- Widget app → Window state: updates · Tracks drag position and window placement.
- Window state → Config file: persists · Saves widget position to local config.
- Widget app → Auto-start setup: registers · Installs login startup registration on first run.
- Auto-start setup → OS startup: uses · Delegates to the platform-native startup mechanism.