# nimaansari/cli-usage architecture

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

- Interactive diagram: https://gitdiagram.com/nimaansari/cli-usage
- Repository: https://github.com/nimaansari/cli-usage

## Overview

cli-usage is a tray/menu-bar monitor for Claude Code, Codex CLI, and Gemini CLI. A user opens either frontend; it periodically or on demand calls the shared data layer, which detects installed tools, reads local auth/account details, and fetches and validates live usage from Claude and Codex endpoints. Gemini currently provides local credential detection only. The frontends turn returned rows into status icons and menus, and offer terminal shortcuts. The graph reflects README capabilities alongside sampled frontend/core behavior; unsampled core details are represented only where documented. Installer and setup machinery are omitted.

Main entry points: [`cli_usage_core.py`](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py) (Usage collection), [`cli_usage_gtk.py`](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_gtk.py) (GTK tray), [`cli_usage_xplat.py`](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_xplat.py) (Cross-platform tray)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Tray frontends"]
  node_gtk["GTK tray<br/>[cli_usage_gtk.py]"]
  node_xplat["Cross-platform tray<br/>[cli_usage_xplat.py]"]
end

subgraph group_core["Shared data layer"]
  node_fetch["Usage collection<br/>[cli_usage_core.py]"]
  node_detect["CLI detection<br/>[cli_usage_core.py]"]
  node_auth["Auth and account lookup<br/>[cli_usage_core.py]"]
  node_provider["Usage requests and validation<br/>[cli_usage_core.py]"]
  node_format["Usage rows and status<br/>[cli_usage_core.py]"]
end

subgraph group_providers["Provider services"]
  node_claude["Anthropic usage API"]
  node_codex["ChatGPT Codex usage API"]
end

subgraph group_local["Local environment"]
  node_credentials["CLI credential files"]
  node_executables["CLI executables"]
end

node_user(("User"))
node_terminal["System terminal"]

node_user -->|"opens or refreshes"| node_gtk
node_user -->|"opens or refreshes"| node_xplat
node_gtk -->|"requests data"| node_fetch
node_xplat -->|"requests data"| node_fetch
node_fetch -->|"checks tools"| node_detect
node_detect -->|"checks availability"| node_executables
node_fetch -->|"gets account state"| node_auth
node_auth -->|"reads local auth"| node_credentials
node_fetch -->|"gets live usage"| node_provider
node_provider -->|"requests usage"| node_claude
node_provider -->|"requests usage"| node_codex
node_provider -->|"validates response"| node_format
node_auth -->|"supplies account state"| node_format
node_format -->|"returns rows"| node_fetch
node_fetch -->|"returns tool data"| node_gtk
node_fetch -->|"returns tool data"| node_xplat
node_gtk -->|"launches CLI shortcut"| node_terminal
node_xplat -->|"launches CLI shortcut"| node_terminal

click node_gtk "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_gtk.py"
click node_xplat "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_xplat.py"
click node_fetch "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py"
click node_detect "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py"
click node_auth "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py"
click node_provider "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py"
click node_format "https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.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_gtk,node_xplat,node_user toneBlue
class node_fetch,node_detect,node_auth,node_provider,node_format toneAmber
class node_claude,node_codex toneMint
class node_credentials,node_executables toneRose
class node_terminal toneIndigo
```

## Components

### Tray frontends

- [GTK tray](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_gtk.py): `cli_usage_gtk.py`
- [Cross-platform tray](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_xplat.py): `cli_usage_xplat.py`

### Shared data layer

- [Usage collection](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py): `cli_usage_core.py`
- [CLI detection](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py): `cli_usage_core.py`
- [Auth and account lookup](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py): `cli_usage_core.py`
- [Usage requests and validation](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py): `cli_usage_core.py`
- [Usage rows and status](https://github.com/nimaansari/cli-usage/blob/main/cli_usage_core.py): `cli_usage_core.py`

### Provider services

- **Anthropic usage API**
- **ChatGPT Codex usage API**

### Local environment

- **CLI credential files**
- **CLI executables**

### Other components

- **User**
- **System terminal**

## Connections

- User → GTK tray: opens or refreshes
- User → Cross-platform tray: opens or refreshes
- GTK tray → Usage collection: requests data
- Cross-platform tray → Usage collection: requests data
- Usage collection → CLI detection: checks tools
- CLI detection → CLI executables: checks availability
- Usage collection → Auth and account lookup: gets account state
- Auth and account lookup → CLI credential files: reads local auth
- Usage collection → Usage requests and validation: gets live usage
- Usage requests and validation → Anthropic usage API: requests usage
- Usage requests and validation → ChatGPT Codex usage API: requests usage
- Usage requests and validation → Usage rows and status: validates response
- Auth and account lookup → Usage rows and status: supplies account state
- Usage rows and status → Usage collection: returns rows
- Usage collection → GTK tray: returns tool data
- Usage collection → Cross-platform tray: returns tool data
- GTK tray → System terminal: launches CLI shortcut
- Cross-platform tray → System terminal: launches CLI shortcut