# nazmussayad/mytokens architecture

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

## Overview

mytokens is a CLI for collecting coding-agent token usage, estimating costs, and presenting reports. The main workflow parses local histories from multiple tools, normalizes usage records, enriches them with model pricing, then renders selectable terminal views. A parallel export workflow produces overview reports as SVG/PNG and can display or copy images. The README describes OpenCode and OpenRouter, while sampled current source shows many parsers and a models.dev pricing fetch; unsampled parser and export internals are represented only where the tree or excerpts support them.

Main entry points: [`src/export/index.ts`](https://github.com/nazmussayad/mytokens/blob/main/src/export/index.ts) (Export workflow), [`src/parsers`](https://github.com/nazmussayad/mytokens/tree/main/src/parsers) (Agent parsers), [`src/app.ts`](https://github.com/nazmussayad/mytokens/blob/main/src/app.ts) (Dashboard runner), [`src/index.ts`](https://github.com/nazmussayad/mytokens/blob/main/src/index.ts) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI entrypoints"]
  node_entry["CLI entry<br/>[index.ts]"]
  node_app["Dashboard runner<br/>[app.ts]"]
  node_exportcli["Export commands<br/>[cli.ts]"]
  node_cachecli["Cache commands<br/>[cache-cli.ts]"]
end

subgraph group_ingestion["Usage ingestion"]
  node_sources["Agent parsers"]
  node_parserhelpers["Parsing helpers<br/>[parser.ts]"]
  node_parsecache["Parse cache<br/>[parse-cache.ts]"]
  node_usage["Normalized usage<br/>[types.ts]"]
end

subgraph group_reporting["Analysis and display"]
  node_screenmap["Screen selection<br/>[screen.ts]"]
  node_screens["Usage screens"]
  node_renderer["Terminal renderer<br/>[render-screen.ts]"]
  node_pricing["Price detection<br/>[price-detector.ts]"]
  node_pricefetch["Pricing fetch"]
  node_modelgroups["Model grouping<br/>[model-groups.ts]"]
end

subgraph group_export["Report export"]
  node_exporter["Export workflow<br/>[index.ts]"]
  node_overview["Overview aggregation<br/>[overview.ts]"]
  node_svg["SVG rendering<br/>[overview-svg.ts]"]
  node_image["Image output<br/>[image.ts]"]
  node_clipboard["Clipboard image<br/>[clipboard.ts]"]
  node_terminalimage["Terminal image<br/>[terminal-image.ts]"]
end

node_user(("CLI user"))
node_history["Local usage histories"]
node_opendb[("OpenCode SQLite")]
node_stdout(("Terminal output"))
node_modelservice(("models.dev"))
node_fileoutput["Report file"]

node_user -->|"runs"| node_entry
node_entry -->|"runs dashboard"| node_app
node_entry -->|"attaches commands"| node_exportcli
node_entry -->|"attaches commands"| node_cachecli
node_app -->|"invokes parsers"| node_sources
node_sources -->|"reads histories"| node_history
node_sources -->|"reads OpenCode DB"| node_opendb
node_sources -->|"normalizes records"| node_parserhelpers
node_sources -->|"uses file cache"| node_parsecache
node_sources -->|"returns records"| node_usage
node_app -->|"selects screen"| node_screenmap
node_app -->|"constructs screen"| node_screens
node_app -->|"flushes cache"| node_parsecache
node_screens -->|"extends renderer"| node_renderer
node_renderer -->|"aggregates records"| node_usage
node_renderer -->|"loads groups"| node_modelgroups
node_renderer -->|"prints views"| node_stdout
node_screens -->|"estimates costs"| node_pricing
node_pricing -->|"loads price data"| node_pricefetch
node_pricefetch -->|"fetches catalog"| node_modelservice
node_exportcli -->|"invokes reports"| node_exporter
node_exporter -->|"loads usage"| node_sources
node_exporter -->|"flushes cache"| node_parsecache
node_exporter -->|"computes overview"| node_overview
node_exporter -->|"renders overview"| node_svg
node_exporter -->|"converts PNG"| node_image
node_exporter -->|"writes report"| node_fileoutput
node_exporter -->|"displays image"| node_terminalimage
node_exporter -->|"copies image"| node_clipboard
node_cachecli -->|"manages cache"| node_parsecache

click node_entry "https://github.com/nazmussayad/mytokens/blob/main/src/index.ts"
click node_app "https://github.com/nazmussayad/mytokens/blob/main/src/app.ts"
click node_exportcli "https://github.com/nazmussayad/mytokens/blob/main/src/export/cli.ts"
click node_cachecli "https://github.com/nazmussayad/mytokens/blob/main/src/cache-cli.ts"
click node_sources "https://github.com/nazmussayad/mytokens/tree/main/src/parsers"
click node_parserhelpers "https://github.com/nazmussayad/mytokens/blob/main/src/helpers/parser.ts"
click node_parsecache "https://github.com/nazmussayad/mytokens/blob/main/src/helpers/parse-cache.ts"
click node_usage "https://github.com/nazmussayad/mytokens/blob/main/src/core/types.ts"
click node_screenmap "https://github.com/nazmussayad/mytokens/blob/main/src/constants/screen.ts"
click node_screens "https://github.com/nazmussayad/mytokens/tree/main/src/screens"
click node_renderer "https://github.com/nazmussayad/mytokens/blob/main/src/render/render-screen.ts"
click node_pricing "https://github.com/nazmussayad/mytokens/blob/main/src/core/price-detector.ts"
click node_pricefetch "https://github.com/nazmussayad/mytokens/blob/main/src/core/fetch-models-dot-dev.ts"
click node_modelgroups "https://github.com/nazmussayad/mytokens/blob/main/src/helpers/model-groups.ts"
click node_exporter "https://github.com/nazmussayad/mytokens/blob/main/src/export/index.ts"
click node_overview "https://github.com/nazmussayad/mytokens/blob/main/src/export/overview.ts"
click node_svg "https://github.com/nazmussayad/mytokens/blob/main/src/export/overview-svg.ts"
click node_image "https://github.com/nazmussayad/mytokens/blob/main/src/export/image.ts"
click node_clipboard "https://github.com/nazmussayad/mytokens/blob/main/src/export/clipboard.ts"
click node_terminalimage "https://github.com/nazmussayad/mytokens/blob/main/src/export/terminal-image.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_entry,node_app,node_exportcli,node_cachecli,node_user toneBlue
class node_sources,node_parserhelpers,node_parsecache,node_usage,node_opendb toneAmber
class node_screenmap,node_screens,node_renderer,node_pricing,node_pricefetch,node_modelgroups toneMint
class node_exporter,node_overview,node_svg,node_image,node_clipboard,node_terminalimage toneRose
class node_history,node_stdout,node_modelservice,node_fileoutput toneIndigo
```

## Components

### CLI entrypoints

- [CLI entry](https://github.com/nazmussayad/mytokens/blob/main/src/index.ts): `src/index.ts`
- [Dashboard runner](https://github.com/nazmussayad/mytokens/blob/main/src/app.ts): `src/app.ts`
- [Export commands](https://github.com/nazmussayad/mytokens/blob/main/src/export/cli.ts): `src/export/cli.ts`
- [Cache commands](https://github.com/nazmussayad/mytokens/blob/main/src/cache-cli.ts): `src/cache-cli.ts`

### Usage ingestion

- [Agent parsers](https://github.com/nazmussayad/mytokens/tree/main/src/parsers): `src/parsers`
- [Parsing helpers](https://github.com/nazmussayad/mytokens/blob/main/src/helpers/parser.ts): `src/helpers/parser.ts`
- [Parse cache](https://github.com/nazmussayad/mytokens/blob/main/src/helpers/parse-cache.ts): `src/helpers/parse-cache.ts`
- [Normalized usage](https://github.com/nazmussayad/mytokens/blob/main/src/core/types.ts): `src/core/types.ts`

### Analysis and display

- [Screen selection](https://github.com/nazmussayad/mytokens/blob/main/src/constants/screen.ts): `src/constants/screen.ts`
- [Usage screens](https://github.com/nazmussayad/mytokens/tree/main/src/screens): `src/screens`
- [Terminal renderer](https://github.com/nazmussayad/mytokens/blob/main/src/render/render-screen.ts): `src/render/render-screen.ts`
- [Price detection](https://github.com/nazmussayad/mytokens/blob/main/src/core/price-detector.ts): `src/core/price-detector.ts`
- [Pricing fetch](https://github.com/nazmussayad/mytokens/blob/main/src/core/fetch-models-dot-dev.ts): `src/core/fetch-models-dot-dev.ts`
- [Model grouping](https://github.com/nazmussayad/mytokens/blob/main/src/helpers/model-groups.ts): `src/helpers/model-groups.ts`

### Report export

- [Export workflow](https://github.com/nazmussayad/mytokens/blob/main/src/export/index.ts): `src/export/index.ts`
- [Overview aggregation](https://github.com/nazmussayad/mytokens/blob/main/src/export/overview.ts): `src/export/overview.ts`
- [SVG rendering](https://github.com/nazmussayad/mytokens/blob/main/src/export/overview-svg.ts): `src/export/overview-svg.ts`
- [Image output](https://github.com/nazmussayad/mytokens/blob/main/src/export/image.ts): `src/export/image.ts`
- [Clipboard image](https://github.com/nazmussayad/mytokens/blob/main/src/export/clipboard.ts): `src/export/clipboard.ts`
- [Terminal image](https://github.com/nazmussayad/mytokens/blob/main/src/export/terminal-image.ts): `src/export/terminal-image.ts`

### Other components

- **CLI user**
- **Local usage histories**
- **OpenCode SQLite**
- **Terminal output**
- **models.dev**
- **Report file**

## Connections

- CLI user → CLI entry: runs
- CLI entry → Dashboard runner: runs dashboard
- CLI entry → Export commands: attaches commands
- CLI entry → Cache commands: attaches commands
- Dashboard runner → Agent parsers: invokes parsers
- Agent parsers → Local usage histories: reads histories
- Agent parsers → OpenCode SQLite: reads OpenCode DB
- Agent parsers → Parsing helpers: normalizes records
- Agent parsers → Parse cache: uses file cache
- Agent parsers → Normalized usage: returns records
- Dashboard runner → Screen selection: selects screen
- Dashboard runner → Usage screens: constructs screen
- Dashboard runner → Parse cache: flushes cache
- Usage screens → Terminal renderer: extends renderer
- Terminal renderer → Normalized usage: aggregates records
- Terminal renderer → Model grouping: loads groups
- Terminal renderer → Terminal output: prints views
- Usage screens → Price detection: estimates costs
- Price detection → Pricing fetch: loads price data
- Pricing fetch → models.dev: fetches catalog
- Export commands → Export workflow: invokes reports
- Export workflow → Agent parsers: loads usage
- Export workflow → Parse cache: flushes cache
- Export workflow → Overview aggregation: computes overview
- Export workflow → SVG rendering: renders overview
- Export workflow → Image output: converts PNG
- Export workflow → Report file: writes report
- Export workflow → Terminal image: displays image
- Export workflow → Clipboard image: copies image
- Cache commands → Parse cache: manages cache