# nazmussayad/mysubs architecture

> Architecture diagram of the GitHub repository nazmussayad/mysubs, 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/nazmussayad/mysubs
- Repository: https://github.com/nazmussayad/mysubs

## Overview

mysubs is a CLI that aggregates subscription usage across AI providers. The main flow loads account configuration, discovers local accounts, selects requested accounts, fetches or reuses usage, then renders terminal output or JSON. Provider-specific acquisition, secret handling, caching, and presentation are distinct stages. The README documents several provider integrations and behaviors beyond the sampled excerpts; those branches are represented at their documented module boundaries.

Main entry points: [`src/app.ts`](https://github.com/nazmussayad/mysubs/blob/main/src/app.ts) (Usage orchestration), [`src/providers/index.ts`](https://github.com/nazmussayad/mysubs/blob/main/src/providers/index.ts) (Provider registry), [`src/providers/copilot/index.ts`](https://github.com/nazmussayad/mysubs/blob/main/src/providers/copilot/index.ts) (Copilot integration), [`src/providers/codex/index.ts`](https://github.com/nazmussayad/mysubs/blob/main/src/providers/codex/index.ts) (Codex integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_cli["CLI commands<br/>[index.ts]"]
  node_app["Usage orchestration<br/>[app.ts]"]
end

subgraph group_settings["Config and secrets"]
  node_config["Config loading<br/>[config.ts]"]
  node_secret["Secret resolution<br/>[secret.ts]"]
  node_keyring["Keyring access<br/>[keyring.ts]"]
end

subgraph group_providers["Provider integrations"]
  node_registry["Provider registry<br/>[index.ts]"]
  node_codex["Codex integration<br/>[index.ts]"]
  node_claude["Claude integration<br/>[index.ts]"]
  node_antigravity["Antigravity integration<br/>[index.ts]"]
  node_copilot["Copilot integration<br/>[index.ts]"]
  node_openrouter["OpenRouter integration<br/>[index.ts]"]
  node_opencode["OpenCode integration<br/>[index.ts]"]
end

subgraph group_results["Usage results"]
  node_cache[("Usage cache<br/>[cache.ts]")]
  node_render["Usage renderer<br/>[render.ts]"]
end

node_user(("CLI user"))
node_localconfig["Local account files"]
node_providerapis["Provider APIs"]
node_agycli["Antigravity CLI"]
node_ghcli["GitHub CLI"]
node_keyringservice[("OS keyring")]
node_output["Terminal or JSON"]

node_user -->|"runs commands"| node_cli
node_cli -->|"runs usage"| node_app
node_cli -->|"manages secrets"| node_keyring
node_app -->|"loads settings"| node_config
node_config -->|"reads account settings"| node_localconfig
node_app -->|"selects handlers"| node_registry
node_registry -->|"registers handler"| node_codex
node_registry -->|"registers handler"| node_claude
node_registry -->|"registers handler"| node_antigravity
node_registry -->|"registers handler"| node_copilot
node_registry -->|"registers handler"| node_openrouter
node_registry -->|"registers handler"| node_opencode
node_app -->|"detects or fetches"| node_codex
node_app -->|"detects or fetches"| node_claude
node_app -->|"detects or fetches"| node_antigravity
node_app -->|"detects or fetches"| node_copilot
node_app -->|"detects or fetches"| node_openrouter
node_app -->|"detects or fetches"| node_opencode
node_app -->|"reads and writes"| node_cache
node_app -->|"renders results"| node_render
node_render -->|"formats output"| node_output
node_codex -->|"fetches usage"| node_providerapis
node_claude -->|"fetches usage"| node_providerapis
node_antigravity -->|"reads quota"| node_agycli
node_copilot -.->|"reads token"| node_ghcli
node_copilot -->|"fetches usage"| node_providerapis
node_openrouter -->|"fetches usage"| node_providerapis
node_opencode -->|"fetches usage"| node_providerapis
node_copilot -->|"resolves token"| node_secret
node_openrouter -->|"resolves API key"| node_secret
node_opencode -->|"resolves credentials"| node_secret
node_secret -->|"reads key"| node_keyring
node_keyring -->|"accesses secret"| node_keyringservice
node_codex -.->|"reads and updates auth"| node_localconfig

click node_cli "https://github.com/nazmussayad/mysubs/blob/main/src/index.ts"
click node_app "https://github.com/nazmussayad/mysubs/blob/main/src/app.ts"
click node_config "https://github.com/nazmussayad/mysubs/blob/main/src/core/config.ts"
click node_secret "https://github.com/nazmussayad/mysubs/blob/main/src/lib/secret.ts"
click node_keyring "https://github.com/nazmussayad/mysubs/blob/main/src/lib/keyring.ts"
click node_registry "https://github.com/nazmussayad/mysubs/blob/main/src/providers/index.ts"
click node_codex "https://github.com/nazmussayad/mysubs/blob/main/src/providers/codex/index.ts"
click node_claude "https://github.com/nazmussayad/mysubs/blob/main/src/providers/claude/index.ts"
click node_antigravity "https://github.com/nazmussayad/mysubs/blob/main/src/providers/antigravity/index.ts"
click node_copilot "https://github.com/nazmussayad/mysubs/blob/main/src/providers/copilot/index.ts"
click node_openrouter "https://github.com/nazmussayad/mysubs/blob/main/src/providers/openrouter/index.ts"
click node_opencode "https://github.com/nazmussayad/mysubs/blob/main/src/providers/opencode/index.ts"
click node_cache "https://github.com/nazmussayad/mysubs/blob/main/src/utils/cache.ts"
click node_render "https://github.com/nazmussayad/mysubs/blob/main/src/core/render.ts"

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_app,node_user toneBlue
class node_config,node_secret,node_keyring,node_keyringservice toneAmber
class node_registry,node_codex,node_claude,node_antigravity,node_copilot,node_openrouter,node_opencode,node_providerapis toneMint
class node_cache,node_render toneRose
class node_localconfig,node_agycli,node_ghcli,node_output toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/nazmussayad/mysubs/blob/main/src/index.ts): `src/index.ts`
- [Usage orchestration](https://github.com/nazmussayad/mysubs/blob/main/src/app.ts): `src/app.ts`

### Config and secrets

- [Config loading](https://github.com/nazmussayad/mysubs/blob/main/src/core/config.ts): `src/core/config.ts`
- [Secret resolution](https://github.com/nazmussayad/mysubs/blob/main/src/lib/secret.ts): `src/lib/secret.ts`
- [Keyring access](https://github.com/nazmussayad/mysubs/blob/main/src/lib/keyring.ts): `src/lib/keyring.ts`

### Provider integrations

- [Provider registry](https://github.com/nazmussayad/mysubs/blob/main/src/providers/index.ts): `src/providers/index.ts`
- [Codex integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/codex/index.ts): `src/providers/codex/index.ts`
- [Claude integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/claude/index.ts): `src/providers/claude/index.ts`
- [Antigravity integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/antigravity/index.ts): `src/providers/antigravity/index.ts`
- [Copilot integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/copilot/index.ts): `src/providers/copilot/index.ts`
- [OpenRouter integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/openrouter/index.ts): `src/providers/openrouter/index.ts`
- [OpenCode integration](https://github.com/nazmussayad/mysubs/blob/main/src/providers/opencode/index.ts): `src/providers/opencode/index.ts`

### Usage results

- [Usage cache](https://github.com/nazmussayad/mysubs/blob/main/src/utils/cache.ts): `src/utils/cache.ts`
- [Usage renderer](https://github.com/nazmussayad/mysubs/blob/main/src/core/render.ts): `src/core/render.ts`

### Other components

- **CLI user**
- **Local account files**
- **Provider APIs**
- **Antigravity CLI**
- **GitHub CLI**
- **OS keyring**
- **Terminal or JSON**

## Connections

- CLI user → CLI commands: runs commands
- CLI commands → Usage orchestration: runs usage
- CLI commands → Keyring access: manages secrets
- Usage orchestration → Config loading: loads settings
- Config loading → Local account files: reads account settings
- Usage orchestration → Provider registry: selects handlers
- Provider registry → Codex integration: registers handler
- Provider registry → Claude integration: registers handler
- Provider registry → Antigravity integration: registers handler
- Provider registry → Copilot integration: registers handler
- Provider registry → OpenRouter integration: registers handler
- Provider registry → OpenCode integration: registers handler
- Usage orchestration → Codex integration: detects or fetches
- Usage orchestration → Claude integration: detects or fetches
- Usage orchestration → Antigravity integration: detects or fetches
- Usage orchestration → Copilot integration: detects or fetches
- Usage orchestration → OpenRouter integration: detects or fetches
- Usage orchestration → OpenCode integration: detects or fetches
- Usage orchestration → Usage cache: reads and writes
- Usage orchestration → Usage renderer: renders results
- Usage renderer → Terminal or JSON: formats output
- Codex integration → Provider APIs: fetches usage
- Claude integration → Provider APIs: fetches usage
- Antigravity integration → Antigravity CLI: reads quota
- Copilot integration → GitHub CLI: reads token
- Copilot integration → Provider APIs: fetches usage
- OpenRouter integration → Provider APIs: fetches usage
- OpenCode integration → Provider APIs: fetches usage
- Copilot integration → Secret resolution: resolves token
- OpenRouter integration → Secret resolution: resolves API key
- OpenCode integration → Secret resolution: resolves credentials
- Secret resolution → Keyring access: reads key
- Keyring access → OS keyring: accesses secret
- Codex integration → Local account files: reads and updates auth