# hskl18/token-bar architecture

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

- Interactive diagram: https://gitdiagram.com/hskl18/token-bar
- Repository: https://github.com/hskl18/token-bar
- Video tour (about a minute): https://gitdiagram.com/hskl18/token-bar/video

## Overview

Token Bar is a native macOS menu bar monitor that combines Claude and Codex quota readings with locally sampled token activity, then presents provider and combined-capacity views. The main runtime coordinator is TokenBarStore: it refreshes provider quotas and activity, computes priced summaries, and maintains last-known/stale behavior. The app layer starts refresh and responds to local-activity changes; the panel renders the store’s snapshot. Some modules are documented by the README but their call sites were not included in the sampled source, so uncertain wiring is omitted.

Main entry points: [`Sources/TokenBar/TokenBarStore.swift`](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarStore.swift) (Refresh coordinator), [`Sources/TokenBar/TokenBarApp.swift`](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarApp.swift) (Menu bar app), [`Sources/TokenBar/ClaudeClient.swift`](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeClient.swift) (Claude quota client), [`Sources/TokenBar/CodexAppServerClient.swift`](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexAppServerClient.swift) (Codex quota client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App coordination"]
  node_app_entry["Menu bar app<br/>[TokenBarApp.swift]"]
  node_store["Refresh coordinator"]
  node_watcher["Activity watcher"]
  node_usage_models["Usage models<br/>[UsageModels.swift]"]
  node_snapshot_store[("Saved usage state<br/>[StorageKeys.swift]")]
end

subgraph group_providers["Provider data"]
  node_claude_client["Claude quota client<br/>[ClaudeClient.swift]"]
  node_codex_client["Codex quota client"]
  node_runtime_locator["Runtime locator"]
end

subgraph group_activity["Local activity"]
  node_claude_sampler["Claude activity sampler"]
  node_claude_window["Claude quota sampler"]
  node_codex_sampler["Codex activity sampler"]
  node_codex_window["Codex window sampler"]
  node_transcript_parser["Transcript parser"]
end

subgraph group_presentation["Usage presentation"]
  node_panel["Usage panel"]
  node_price_catalog["Price catalog<br/>[PriceCatalog.swift]"]
  node_capacity_estimator["Weekly capacity"]
  node_image_usage["Image usage"]
end

node_user(("Mac user"))
node_claude_account(("Claude account"))
node_claude_usage_api["Claude usage API"]
node_codex_runtime["Codex runtime"]
node_pricing_sources["Pricing sources"]

node_user -->|"opens"| node_app_entry
node_app_entry -->|"starts refresh"| node_store
node_app_entry -->|"starts watching"| node_watcher
node_watcher -->|"signals activity"| node_app_entry
node_app_entry -->|"shows panel"| node_panel
node_panel -->|"reads snapshot"| node_store
node_store -->|"fetches quota"| node_claude_client
node_claude_client -->|"reads credential"| node_claude_account
node_claude_client -->|"requests usage"| node_claude_usage_api
node_store -->|"fetches quota"| node_codex_client
node_codex_client -->|"locates runtime"| node_runtime_locator
node_codex_client -->|"requests quota"| node_codex_runtime
node_store -->|"samples activity"| node_claude_sampler
node_store -->|"samples window"| node_claude_window
node_store -->|"samples activity"| node_codex_sampler
node_store -->|"samples window"| node_codex_window
node_codex_window -->|"parses records"| node_transcript_parser
node_store -->|"prices activity"| node_price_catalog
node_price_catalog -.->|"fetches prices"| node_pricing_sources
node_store -->|"estimates capacity"| node_capacity_estimator
node_store -->|"updates image usage"| node_image_usage
node_store -->|"builds snapshot"| node_usage_models
node_store -->|"persists state"| node_snapshot_store
node_store -->|"publishes snapshot"| node_panel

click node_app_entry "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarApp.swift"
click node_store "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarStore.swift"
click node_watcher "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/LocalActivityWatcher.swift"
click node_panel "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarPanel.swift"
click node_claude_client "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeClient.swift"
click node_codex_client "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexAppServerClient.swift"
click node_runtime_locator "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexRuntimeLocator.swift"
click node_claude_sampler "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeMixSampler.swift"
click node_claude_window "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeWindowSampler.swift"
click node_codex_sampler "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexMixSampler.swift"
click node_codex_window "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexWindowSampler.swift"
click node_transcript_parser "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexTranscriptParser.swift"
click node_usage_models "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/UsageModels.swift"
click node_price_catalog "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/PriceCatalog.swift"
click node_capacity_estimator "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/WeeklyCapacityEstimator.swift"
click node_image_usage "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ImageGenerationUsage.swift"
click node_snapshot_store "https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/StorageKeys.swift"

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_app_entry,node_store,node_watcher,node_usage_models,node_snapshot_store,node_user toneBlue
class node_claude_client,node_codex_client,node_runtime_locator toneAmber
class node_claude_sampler,node_claude_window,node_codex_sampler,node_codex_window,node_transcript_parser,node_claude_usage_api toneMint
class node_panel,node_price_catalog,node_capacity_estimator,node_image_usage toneRose
class node_claude_account,node_codex_runtime,node_pricing_sources toneIndigo
```

## Components

### App coordination

- [Menu bar app](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarApp.swift): `Sources/TokenBar/TokenBarApp.swift`
- [Refresh coordinator](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarStore.swift): `Sources/TokenBar/TokenBarStore.swift`
- [Activity watcher](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/LocalActivityWatcher.swift): `Sources/TokenBar/LocalActivityWatcher.swift`
- [Usage models](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/UsageModels.swift): `Sources/TokenBar/UsageModels.swift`
- [Saved usage state](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/StorageKeys.swift): `Sources/TokenBar/StorageKeys.swift`

### Provider data

- [Claude quota client](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeClient.swift): `Sources/TokenBar/ClaudeClient.swift`
- [Codex quota client](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexAppServerClient.swift): `Sources/TokenBar/CodexAppServerClient.swift`
- [Runtime locator](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexRuntimeLocator.swift): `Sources/TokenBar/CodexRuntimeLocator.swift`

### Local activity

- [Claude activity sampler](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeMixSampler.swift): `Sources/TokenBar/ClaudeMixSampler.swift`
- [Claude quota sampler](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ClaudeWindowSampler.swift): `Sources/TokenBar/ClaudeWindowSampler.swift`
- [Codex activity sampler](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexMixSampler.swift): `Sources/TokenBar/CodexMixSampler.swift`
- [Codex window sampler](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexWindowSampler.swift): `Sources/TokenBar/CodexWindowSampler.swift`
- [Transcript parser](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/CodexTranscriptParser.swift): `Sources/TokenBar/CodexTranscriptParser.swift`

### Usage presentation

- [Usage panel](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/TokenBarPanel.swift): `Sources/TokenBar/TokenBarPanel.swift`
- [Price catalog](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/PriceCatalog.swift): `Sources/TokenBar/PriceCatalog.swift`
- [Weekly capacity](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/WeeklyCapacityEstimator.swift): `Sources/TokenBar/WeeklyCapacityEstimator.swift`
- [Image usage](https://github.com/hskl18/token-bar/blob/main/Sources/TokenBar/ImageGenerationUsage.swift): `Sources/TokenBar/ImageGenerationUsage.swift`

### Other components

- **Mac user**
- **Claude account**
- **Claude usage API**
- **Codex runtime**
- **Pricing sources**

## Connections

- Mac user → Menu bar app: opens
- Menu bar app → Refresh coordinator: starts refresh
- Menu bar app → Activity watcher: starts watching
- Activity watcher → Menu bar app: signals activity
- Menu bar app → Usage panel: shows panel
- Usage panel → Refresh coordinator: reads snapshot
- Refresh coordinator → Claude quota client: fetches quota
- Claude quota client → Claude account: reads credential
- Claude quota client → Claude usage API: requests usage
- Refresh coordinator → Codex quota client: fetches quota
- Codex quota client → Runtime locator: locates runtime
- Codex quota client → Codex runtime: requests quota
- Refresh coordinator → Claude activity sampler: samples activity
- Refresh coordinator → Claude quota sampler: samples window
- Refresh coordinator → Codex activity sampler: samples activity
- Refresh coordinator → Codex window sampler: samples window
- Codex window sampler → Transcript parser: parses records
- Refresh coordinator → Price catalog: prices activity
- Price catalog → Pricing sources: fetches prices
- Refresh coordinator → Weekly capacity: estimates capacity
- Refresh coordinator → Image usage: updates image usage
- Refresh coordinator → Usage models: builds snapshot
- Refresh coordinator → Saved usage state: persists state
- Refresh coordinator → Usage panel: publishes snapshot