# maciek-roboblog/claude-code-usage-monitor architecture

> Architecture diagram of the GitHub repository maciek-roboblog/claude-code-usage-monitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maciek-roboblog/claude-code-usage-monitor
- Repository: https://github.com/maciek-roboblog/claude-code-usage-monitor

## Overview

Claude Code Usage Monitor is a local usage-operations companion: CLI or statusline invocations collect Claude usage and optional official limits, build estimates and forecasts, then present or export a common snapshot. Its live workflow refreshes usage through the monitoring orchestrator and renders it in the terminal; one-shot and automation modes use the snapshot contract. The README also documents opt-in history and reports. Those capabilities are represented from documentation and paths; their internal wiring is not established by the sampled source.

Main entry points: [`src/claude_monitor/cli/main.py`](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/cli/main.py) (CLI entry), [`src/claude_monitor/data/analysis.py`](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/analysis.py) (Usage analysis), [`src/claude_monitor/monitoring/orchestrator.py`](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/orchestrator.py) (Monitor orchestrator), [`src/claude_monitor/output/snapshots.py`](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/snapshots.py) (Snapshot builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Invocation and monitoring"]
  node_cli["CLI entry<br/>[main.py]"]
  node_settings["CLI settings<br/>[settings.py]"]
  node_orchestrator["Monitor orchestrator<br/>[orchestrator.py]"]
  node_sessionmonitor["Session tracking<br/>[session_monitor.py]"]
  node_datamanager["Data manager<br/>[data_manager.py]"]
end

subgraph group_usage["Usage analysis"]
  node_reader["Usage reader<br/>[reader.py]"]
  node_analyzer["Session analyzer<br/>[analyzer.py]"]
  node_analysis["Usage analysis<br/>[analysis.py]"]
  node_aggregator["Usage aggregation<br/>[aggregator.py]"]
end

subgraph group_domain["Limits and snapshots"]
  node_plans["Plan limits<br/>[plans.py]"]
  node_calculations["Usage calculations<br/>[calculations.py]"]
  node_snapshots["Snapshot builder<br/>[snapshots.py]"]
  node_official["Official limits<br/>[official.py]"]
  node_apiusage["Experimental API limits<br/>[api_usage.py]"]
end

subgraph group_presentation["Presentation and persistence"]
  node_display["Live display control"]
  node_sessiondisplay["Session rendering<br/>[session_display.py]"]
  node_formatters["Output formatters<br/>[formatters.py]"]
  node_state["State export<br/>[state.py]"]
  node_warehouse[("Usage warehouse<br/>[warehouse.py]")]
  node_reports["History reports<br/>[reports.py]"]
end

node_user(("Monitor user"))
node_claude(("Claude Code"))
node_usagefiles["Claude usage files"]
node_officialinput["Statusline rate limits"]

node_user -->|"invokes"| node_cli
node_claude -.->|"runs hook"| node_cli
node_cli -->|"loads options"| node_settings
node_cli -->|"starts monitoring"| node_orchestrator
node_orchestrator -->|"fetches usage"| node_datamanager
node_datamanager -->|"analyzes usage"| node_analysis
node_analysis -->|"reads entries"| node_reader
node_analysis -->|"analyzes sessions"| node_analyzer
node_analysis -->|"aggregates usage"| node_aggregator
node_usagefiles -->|"provides entries"| node_reader
node_orchestrator -->|"updates sessions"| node_sessionmonitor
node_cli -->|"reads limits"| node_official
node_officialinput -->|"supplies limits"| node_official
node_cli -.->|"checks optionally"| node_apiusage
node_cli -->|"builds snapshot"| node_snapshots
node_snapshots -->|"gets plan limits"| node_plans
node_snapshots -->|"calculates pace"| node_calculations
node_cli -->|"runs live view"| node_display
node_display -->|"renders session"| node_sessiondisplay
node_cli -->|"formats output"| node_formatters
node_cli -->|"writes state"| node_state
node_analysis -.->|"persists optionally"| node_warehouse
node_warehouse -->|"provides history"| node_reports

click node_cli "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/cli/main.py"
click node_settings "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/settings.py"
click node_orchestrator "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/orchestrator.py"
click node_sessionmonitor "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/session_monitor.py"
click node_datamanager "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/data_manager.py"
click node_reader "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/reader.py"
click node_analyzer "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/analyzer.py"
click node_analysis "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/analysis.py"
click node_aggregator "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/aggregator.py"
click node_plans "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/plans.py"
click node_calculations "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/calculations.py"
click node_snapshots "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/snapshots.py"
click node_official "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/official.py"
click node_apiusage "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/api_usage.py"
click node_display "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/ui/display_controller.py"
click node_sessiondisplay "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/ui/session_display.py"
click node_formatters "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/formatters.py"
click node_state "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/state.py"
click node_warehouse "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/warehouse.py"
click node_reports "https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/reports.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_settings,node_orchestrator,node_sessionmonitor,node_datamanager,node_user toneBlue
class node_reader,node_analyzer,node_analysis,node_aggregator toneAmber
class node_plans,node_calculations,node_snapshots,node_official,node_apiusage toneMint
class node_display,node_sessiondisplay,node_formatters,node_state,node_warehouse,node_reports toneRose
class node_claude,node_usagefiles,node_officialinput toneIndigo
```

## Components

### Invocation and monitoring

- [CLI entry](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/cli/main.py): `src/claude_monitor/cli/main.py`
- [CLI settings](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/settings.py): `src/claude_monitor/core/settings.py`
- [Monitor orchestrator](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/orchestrator.py): `src/claude_monitor/monitoring/orchestrator.py`
- [Session tracking](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/session_monitor.py): `src/claude_monitor/monitoring/session_monitor.py`
- [Data manager](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/monitoring/data_manager.py): `src/claude_monitor/monitoring/data_manager.py`

### Usage analysis

- [Usage reader](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/reader.py): `src/claude_monitor/data/reader.py`
- [Session analyzer](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/analyzer.py): `src/claude_monitor/data/analyzer.py`
- [Usage analysis](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/analysis.py): `src/claude_monitor/data/analysis.py`
- [Usage aggregation](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/aggregator.py): `src/claude_monitor/data/aggregator.py`

### Limits and snapshots

- [Plan limits](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/plans.py): `src/claude_monitor/core/plans.py`
- [Usage calculations](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/core/calculations.py): `src/claude_monitor/core/calculations.py`
- [Snapshot builder](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/snapshots.py): `src/claude_monitor/output/snapshots.py`
- [Official limits](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/official.py): `src/claude_monitor/output/official.py`
- [Experimental API limits](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/api_usage.py): `src/claude_monitor/output/api_usage.py`

### Presentation and persistence

- [Live display control](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/ui/display_controller.py): `src/claude_monitor/ui/display_controller.py`
- [Session rendering](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/ui/session_display.py): `src/claude_monitor/ui/session_display.py`
- [Output formatters](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/formatters.py): `src/claude_monitor/output/formatters.py`
- [State export](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/output/state.py): `src/claude_monitor/output/state.py`
- [Usage warehouse](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/warehouse.py): `src/claude_monitor/data/warehouse.py`
- [History reports](https://github.com/maciek-roboblog/claude-code-usage-monitor/blob/main/src/claude_monitor/data/reports.py): `src/claude_monitor/data/reports.py`

### Other components

- **Monitor user**
- **Claude Code**
- **Claude usage files**
- **Statusline rate limits**

## Connections

- Monitor user → CLI entry: invokes
- Claude Code → CLI entry: runs hook
- CLI entry → CLI settings: loads options
- CLI entry → Monitor orchestrator: starts monitoring
- Monitor orchestrator → Data manager: fetches usage
- Data manager → Usage analysis: analyzes usage
- Usage analysis → Usage reader: reads entries
- Usage analysis → Session analyzer: analyzes sessions
- Usage analysis → Usage aggregation: aggregates usage
- Claude usage files → Usage reader: provides entries
- Monitor orchestrator → Session tracking: updates sessions
- CLI entry → Official limits: reads limits
- Statusline rate limits → Official limits: supplies limits
- CLI entry → Experimental API limits: checks optionally
- CLI entry → Snapshot builder: builds snapshot
- Snapshot builder → Plan limits: gets plan limits
- Snapshot builder → Usage calculations: calculates pace
- CLI entry → Live display control: runs live view
- Live display control → Session rendering: renders session
- CLI entry → Output formatters: formats output
- CLI entry → State export: writes state
- Usage analysis → Usage warehouse: persists optionally
- Usage warehouse → History reports: provides history