# kkmaple/codex-usage-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/kkmaple/codex-usage-monitor
- Repository: https://github.com/kkmaple/codex-usage-monitor

## Overview

This is a Windows taskbar usage monitor for Codex, with optional Claude Code and Antigravity providers. The principal flow is credential discovery and provider polling, conversion into shared usage data, then display in a taskbar widget and tray icons; the app also provides settings, localization, diagnostics, and update handling. Provider polling and several UI call sites are only partially sampled, so some documented runtime links are dashed rather than asserted as verified calls.

Main entry points: [`src/window.rs`](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/window.rs) (Taskbar widget), [`src/poller.rs`](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/poller.rs) (Usage poller), [`src/main.rs`](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/main.rs) (Application entry), [`src/updater.rs`](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/updater.rs) (Update handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["Application entry<br/>[main.rs]"]
  node_usage["Usage data<br/>[models.rs]"]
end

subgraph group_providers["Usage providers"]
  node_poller["Usage poller<br/>[poller.rs]"]
  node_credentials["Provider credentials<br/>[poller.rs]"]
  node_claude{{"Anthropic endpoints"}}
  node_codex{{"ChatGPT endpoints"}}
  node_antigravity{{"Google endpoints"}}
end

subgraph group_presentation["Taskbar interface"]
  node_window["Taskbar widget<br/>[window.rs]"]
  node_interop["Windows interop<br/>[native_interop.rs]"]
  node_tray["Tray badges<br/>[tray_icon.rs]"]
  node_theme["Theme detection<br/>[theme.rs]"]
end

subgraph group_support["Settings and support"]
  node_localization["Localized strings"]
  node_settings[("Widget settings<br/>[window.rs]")]
  node_updater["Update handling<br/>[updater.rs]"]
  node_diagnostics["Diagnostic logging<br/>[diagnose.rs]"]
end

node_user(("Windows user"))
node_github{{"GitHub releases"}}
node_taskbar["Windows taskbar"]

node_user -->|"launches"| node_main
node_main -->|"starts"| node_window
node_main -->|"initializes"| node_diagnostics
node_main -->|"checks CLI mode"| node_updater
node_poller -->|"reads"| node_credentials
node_poller -->|"requests usage"| node_claude
node_poller -.->|"requests usage"| node_codex
node_poller -->|"requests quota"| node_antigravity
node_poller -->|"returns usage"| node_usage
node_window -.->|"refreshes periodically"| node_poller
node_window -->|"displays usage"| node_usage
node_window -->|"uses helpers"| node_interop
node_window -->|"embeds widget"| node_taskbar
node_window -.->|"manages tray icons"| node_tray
node_window -.->|"uses theme"| node_theme
node_window -->|"resolves language"| node_localization
node_window -->|"loads and saves"| node_settings
node_window -->|"checks updates"| node_updater
node_updater -->|"checks releases"| node_github
node_user -->|"configures display"| node_window

click node_main "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/main.rs"
click node_poller "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/poller.rs"
click node_credentials "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/poller.rs"
click node_usage "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/models.rs"
click node_window "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/window.rs"
click node_interop "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/native_interop.rs"
click node_tray "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/tray_icon.rs"
click node_theme "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/theme.rs"
click node_localization "https://github.com/kkmaple/codex-usage-monitor/tree/main/src/localization"
click node_settings "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/window.rs"
click node_updater "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/updater.rs"
click node_diagnostics "https://github.com/kkmaple/codex-usage-monitor/blob/main/src/diagnose.rs"

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_main,node_usage,node_user toneBlue
class node_poller,node_credentials,node_claude,node_codex,node_antigravity toneAmber
class node_window,node_interop,node_tray,node_theme toneMint
class node_localization,node_settings,node_updater,node_diagnostics,node_taskbar toneRose
class node_github toneIndigo
```

## Components

### Application runtime

- [Application entry](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/main.rs): `src/main.rs`
- [Usage data](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/models.rs): `src/models.rs`

### Usage providers

- [Usage poller](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/poller.rs): `src/poller.rs`
- [Provider credentials](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/poller.rs): `src/poller.rs`
- **Anthropic endpoints**
- **ChatGPT endpoints**
- **Google endpoints**

### Taskbar interface

- [Taskbar widget](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/window.rs): `src/window.rs`
- [Windows interop](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/native_interop.rs): `src/native_interop.rs`
- [Tray badges](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/tray_icon.rs): `src/tray_icon.rs`
- [Theme detection](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/theme.rs): `src/theme.rs`

### Settings and support

- [Localized strings](https://github.com/kkmaple/codex-usage-monitor/tree/main/src/localization): `src/localization`
- [Widget settings](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/window.rs): `src/window.rs`
- [Update handling](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/updater.rs): `src/updater.rs`
- [Diagnostic logging](https://github.com/kkmaple/codex-usage-monitor/blob/main/src/diagnose.rs): `src/diagnose.rs`

### Other components

- **Windows user**
- **GitHub releases**
- **Windows taskbar**

## Connections

- Windows user → Application entry: launches (evidence: `README.md`)
- Application entry → Taskbar widget: starts (evidence: `src/main.rs`)
- Application entry → Diagnostic logging: initializes (evidence: `src/main.rs`)
- Application entry → Update handling: checks CLI mode (evidence: `src/main.rs`)
- Usage poller → Provider credentials: reads (evidence: `src/poller.rs`)
- Usage poller → Anthropic endpoints: requests usage (evidence: `src/poller.rs`)
- Usage poller → ChatGPT endpoints: requests usage (evidence: `README.md`)
- Usage poller → Google endpoints: requests quota (evidence: `src/poller.rs`)
- Usage poller → Usage data: returns usage (evidence: `src/poller.rs`)
- Taskbar widget → Usage poller: refreshes periodically (evidence: `README.md`)
- Taskbar widget → Usage data: displays usage (evidence: `README.md`)
- Taskbar widget → Windows interop: uses helpers (evidence: `src/window.rs`)
- Taskbar widget → Windows taskbar: embeds widget (evidence: `README.md`)
- Taskbar widget → Tray badges: manages tray icons (evidence: `README.md`)
- Taskbar widget → Theme detection: uses theme (evidence: `src/window.rs`)
- Taskbar widget → Localized strings: resolves language (evidence: `src/window.rs`)
- Taskbar widget → Widget settings: loads and saves (evidence: `README.md`)
- Taskbar widget → Update handling: checks updates (evidence: `src/window.rs`)
- Update handling → GitHub releases: checks releases (evidence: `src/updater.rs`)
- Windows user → Taskbar widget: configures display (evidence: `README.md`)