# niccolo-sabato/claude-usage-widget architecture

> Architecture diagram of the GitHub repository niccolo-sabato/claude-usage-widget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niccolo-sabato/claude-usage-widget
- Repository: https://github.com/niccolo-sabato/claude-usage-widget

## Overview

Claude Usage Widget is a Windows desktop monitor for Claude.ai session, weekly, and model-specific limits; its central workflow is fetching account usage and presenting compact taskbar bars with reset information. The widget also supports saved accounts and Claude Code login switching. A companion browser extension retrieves and copies the Claude session key for setup. Widget internals are represented at the available source-path level because its implementation was not excerpted; README-documented capabilities are retained, while uncertain internal call paths are omitted.

Main entry points: [`src/widget.pyw`](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw) (Usage widget), [`extension/popup.js`](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/popup.js) (Key popup), [`extension/lib/cookieService.js`](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/lib/cookieService.js) (Cookie service), [`extension/background.js`](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/background.js) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop widget"]
  node_widget["Usage widget<br/>[widget.pyw]"]
  node_usage["Usage refresh<br/>[widget.pyw]"]
  node_bars["Usage bars<br/>[widget.pyw]"]
  node_preferences["Display preferences<br/>[widget.pyw]"]
  node_alerts["Threshold alerts<br/>[widget.pyw]"]
end

subgraph group_accounts["Account management"]
  node_account_ui["Account switching<br/>[widget.pyw]"]
  node_cc_cli["Claude Code CLI<br/>[cc_cli.py]"]
  node_cc_accounts["OAuth profiles<br/>[cc_accounts.py]"]
end

subgraph group_extension["Browser extension"]
  node_extension_ui["Key popup<br/>[popup.js]"]
  node_cookie_service["Cookie service<br/>[cookieService.js]"]
  node_worker["Background worker<br/>[background.js]"]
end

subgraph group_platform["Platform integration"]
  node_taskbar["Taskbar behavior<br/>[widget.pyw]"]
end

node_user(("User"))
node_claude{{"Claude.ai"}}
node_windows{{"Windows"}}
node_browser{{"Browser"}}

node_user -->|"views and configures"| node_widget
node_widget -->|"requests refresh"| node_usage
node_usage -->|"fetches usage"| node_claude
node_usage -->|"updates bars"| node_bars
node_widget -->|"configures display"| node_preferences
node_usage -->|"triggers thresholds"| node_alerts
node_widget -->|"positions widget"| node_taskbar
node_user -->|"switches account"| node_account_ui
node_account_ui -->|"switches Claude Code login"| node_cc_cli
node_cc_cli -->|"uses profile operations"| node_cc_accounts
node_cc_accounts -.->|"renews OAuth login"| node_claude
node_user -->|"opens popup"| node_extension_ui
node_extension_ui -->|"gets session key"| node_cookie_service
node_cookie_service -->|"reads cookie"| node_browser
node_browser -.->|"holds session"| node_claude
node_worker -->|"checks session"| node_cookie_service
node_worker -->|"sets badge and surface"| node_browser
node_extension_ui -->|"provides setup key"| node_widget
node_widget -->|"uses taskbar integration"| node_windows

click node_widget "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_usage "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_bars "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_preferences "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_alerts "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_taskbar "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_account_ui "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw"
click node_cc_cli "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/cc_cli.py"
click node_cc_accounts "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/cc_accounts.py"
click node_extension_ui "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/popup.js"
click node_cookie_service "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/lib/cookieService.js"
click node_worker "https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/background.js"

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_widget,node_usage,node_bars,node_preferences,node_alerts,node_user,node_browser toneBlue
class node_account_ui,node_cc_cli,node_cc_accounts toneAmber
class node_extension_ui,node_cookie_service,node_worker toneMint
class node_taskbar toneRose
class node_claude,node_windows toneIndigo
```

## Components

### Desktop widget

- [Usage widget](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`
- [Usage refresh](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`
- [Usage bars](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`
- [Display preferences](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`
- [Threshold alerts](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`

### Account management

- [Account switching](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`
- [Claude Code CLI](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/cc_cli.py): `src/cc_cli.py`
- [OAuth profiles](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/cc_accounts.py): `src/cc_accounts.py`

### Browser extension

- [Key popup](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/popup.js): `extension/popup.js`
- [Cookie service](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/lib/cookieService.js): `extension/lib/cookieService.js`
- [Background worker](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/extension/background.js): `extension/background.js`

### Platform integration

- [Taskbar behavior](https://github.com/niccolo-sabato/claude-usage-widget/blob/main/src/widget.pyw): `src/widget.pyw`

### Other components

- **User**
- **Claude.ai**
- **Windows**
- **Browser**

## Connections

- User → Usage widget: views and configures (evidence: `README.md`)
- Usage widget → Usage refresh: requests refresh (evidence: `README.md`)
- Usage refresh → Claude.ai: fetches usage (evidence: `README.md`)
- Usage refresh → Usage bars: updates bars (evidence: `README.md`)
- Usage widget → Display preferences: configures display (evidence: `README.md`)
- Usage refresh → Threshold alerts: triggers thresholds (evidence: `README.md`)
- Usage widget → Taskbar behavior: positions widget (evidence: `README.md`)
- User → Account switching: switches account (evidence: `README.md`)
- Account switching → Claude Code CLI: switches Claude Code login (evidence: `README.md`)
- Claude Code CLI → OAuth profiles: uses profile operations (evidence: `src/cc_cli.py`)
- OAuth profiles → Claude.ai: renews OAuth login
- User → Key popup: opens popup (evidence: `extension/popup.js`)
- Key popup → Cookie service: gets session key (evidence: `extension/popup.js`)
- Cookie service → Browser: reads cookie (evidence: `extension/lib/cookieService.js`)
- Browser → Claude.ai: holds session
- Background worker → Cookie service: checks session (evidence: `extension/background.js`)
- Background worker → Browser: sets badge and surface (evidence: `extension/background.js`)
- Key popup → Usage widget: provides setup key (evidence: `README.md`)
- Usage widget → Windows: uses taskbar integration (evidence: `README.md`)
