# ht2803-max/tokenmanager architecture

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

- Interactive diagram: https://gitdiagram.com/ht2803-max/tokenmanager
- Repository: https://github.com/ht2803-max/tokenmanager
- Video tour (about a minute): https://gitdiagram.com/ht2803-max/tokenmanager/video

## Overview

TokenManager is a local AI-agent usage tracker. Its main workflow discovers agent session files, incrementally parses and normalizes records into SQLite, then calculates costs and usage views for terminal, command-line, and static-HTML reports. Separate capabilities include optimization advice, budgets and subscription-window limits, tool analytics, live watching, and background alerts. The graph follows README descriptions and indexed source references; some internal call details are not shown in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`internal/cli/root.go`](https://github.com/ht2803-max/tokenmanager/blob/main/internal/cli/root.go) (CLI Commands), [`internal/collector/collector.go`](https://github.com/ht2803-max/tokenmanager/blob/main/internal/collector/collector.go) (Incremental Collector), [`internal/analytics/analytics.go`](https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/analytics.go) (Usage Analytics), [`internal/daemon/daemon.go`](https://github.com/ht2803-max/tokenmanager/blob/main/internal/daemon/daemon.go) (Background Daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_collector["Incremental Collector<br/>[collector.go]"]
  node_agents["Agent Discovery<br/>[agents.go]"]
  node_parsers["Agent Parsers<br/>[codex.go]"]
  node_model["Usage Records<br/>[model.go]"]
  node_storage[("SQLite Storage<br/>[storage.go]")]
end

subgraph group_analysis["Analysis"]
  node_analytics["Usage Analytics<br/>[analytics.go]"]
  node_blocks["Usage Windows<br/>[blocks.go]"]
  node_toolanalytics["Tool Analytics<br/>[tools.go]"]
  node_pricing["Cost Pricing<br/>[pricing.go]"]
  node_optimizer["Optimization Advice<br/>[optimizer.go]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Commands<br/>[root.go]"]
  node_reports["Reports and Export<br/>[reports.go]"]
  node_tui["Terminal Dashboard<br/>[tui.go]"]
  node_views["Dashboard Views<br/>[views.go]"]
  node_web["HTML Dashboard<br/>[generator.go]"]
end

subgraph group_operations["Budgets and Monitoring"]
  node_budget["Budget Tracking<br/>[budget.go]"]
  node_daemon["Background Daemon<br/>[daemon.go]"]
  node_config["Configuration<br/>[config.go]"]
end

node_user(("User"))
node_agentfiles["Agent Session Files"]
node_notify["Desktop Notifications"]

node_user -->|"runs commands"| node_cli
node_cli -->|"scans files"| node_collector
node_agentfiles -->|"provides usage files"| node_collector
node_collector -->|"discovers adapters"| node_agents
node_collector -->|"parses file data"| node_parsers
node_agents -->|"selects parser"| node_parsers
node_parsers -->|"produces records"| node_model
node_collector -->|"writes records"| node_storage
node_collector -->|"uses settings"| node_config
node_storage -->|"stores records"| node_model
node_analytics -->|"queries records"| node_storage
node_analytics -->|"prices usage"| node_pricing
node_pricing -->|"loads custom prices"| node_config
node_cli -->|"starts dashboard"| node_tui
node_tui -->|"watches and rescans"| node_collector
node_tui -->|"renders views"| node_views
node_cli -->|"runs report commands"| node_reports
node_reports -->|"aggregates usage"| node_analytics
node_cli -->|"exports dashboard"| node_web
node_web -->|"computes dashboard data"| node_analytics
node_web -->|"includes advice"| node_optimizer
node_analytics -.->|"calculates limits"| node_blocks
node_analytics -.->|"summarizes tool use"| node_toolanalytics
node_cli -->|"requests recommendations"| node_optimizer
node_optimizer -->|"analyzes records"| node_analytics
node_cli -->|"manages budgets"| node_budget
node_budget -->|"checks spending"| node_analytics
node_cli -->|"controls daemon"| node_daemon
node_daemon -->|"collects continuously"| node_collector
node_daemon -->|"checks alert thresholds"| node_budget
node_daemon -->|"sends alerts"| node_notify
node_daemon -->|"persists alert state"| node_storage

click node_cli "https://github.com/ht2803-max/tokenmanager/blob/main/internal/cli/root.go"
click node_reports "https://github.com/ht2803-max/tokenmanager/blob/main/internal/cli/reports.go"
click node_tui "https://github.com/ht2803-max/tokenmanager/blob/main/internal/tui/tui.go"
click node_views "https://github.com/ht2803-max/tokenmanager/blob/main/internal/tui/views.go"
click node_web "https://github.com/ht2803-max/tokenmanager/blob/main/internal/web/generator.go"
click node_collector "https://github.com/ht2803-max/tokenmanager/blob/main/internal/collector/collector.go"
click node_agents "https://github.com/ht2803-max/tokenmanager/blob/main/internal/agents/agents.go"
click node_parsers "https://github.com/ht2803-max/tokenmanager/blob/main/internal/parser/codex.go"
click node_model "https://github.com/ht2803-max/tokenmanager/blob/main/internal/model/model.go"
click node_storage "https://github.com/ht2803-max/tokenmanager/blob/main/internal/storage/storage.go"
click node_analytics "https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/analytics.go"
click node_blocks "https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/blocks.go"
click node_toolanalytics "https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/tools.go"
click node_pricing "https://github.com/ht2803-max/tokenmanager/blob/main/internal/pricing/pricing.go"
click node_optimizer "https://github.com/ht2803-max/tokenmanager/blob/main/internal/optimizer/optimizer.go"
click node_budget "https://github.com/ht2803-max/tokenmanager/blob/main/internal/budget/budget.go"
click node_daemon "https://github.com/ht2803-max/tokenmanager/blob/main/internal/daemon/daemon.go"
click node_config "https://github.com/ht2803-max/tokenmanager/blob/main/internal/config/config.go"

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_collector,node_agents,node_parsers,node_model,node_storage,node_user toneBlue
class node_analytics,node_blocks,node_toolanalytics,node_pricing,node_optimizer toneAmber
class node_cli,node_reports,node_tui,node_views,node_web toneMint
class node_budget,node_daemon,node_config toneRose
class node_agentfiles,node_notify toneIndigo
```

## Components

### Ingestion

- [Incremental Collector](https://github.com/ht2803-max/tokenmanager/blob/main/internal/collector/collector.go): `internal/collector/collector.go`
- [Agent Discovery](https://github.com/ht2803-max/tokenmanager/blob/main/internal/agents/agents.go): `internal/agents/agents.go`
- [Agent Parsers](https://github.com/ht2803-max/tokenmanager/blob/main/internal/parser/codex.go): `internal/parser/codex.go`
- [Usage Records](https://github.com/ht2803-max/tokenmanager/blob/main/internal/model/model.go): `internal/model/model.go`
- [SQLite Storage](https://github.com/ht2803-max/tokenmanager/blob/main/internal/storage/storage.go): `internal/storage/storage.go`

### Analysis

- [Usage Analytics](https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/analytics.go): `internal/analytics/analytics.go`
- [Usage Windows](https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/blocks.go): `internal/analytics/blocks.go`
- [Tool Analytics](https://github.com/ht2803-max/tokenmanager/blob/main/internal/analytics/tools.go): `internal/analytics/tools.go`
- [Cost Pricing](https://github.com/ht2803-max/tokenmanager/blob/main/internal/pricing/pricing.go): `internal/pricing/pricing.go`
- [Optimization Advice](https://github.com/ht2803-max/tokenmanager/blob/main/internal/optimizer/optimizer.go): `internal/optimizer/optimizer.go`

### User Interfaces

- [CLI Commands](https://github.com/ht2803-max/tokenmanager/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Reports and Export](https://github.com/ht2803-max/tokenmanager/blob/main/internal/cli/reports.go): `internal/cli/reports.go`
- [Terminal Dashboard](https://github.com/ht2803-max/tokenmanager/blob/main/internal/tui/tui.go): `internal/tui/tui.go`
- [Dashboard Views](https://github.com/ht2803-max/tokenmanager/blob/main/internal/tui/views.go): `internal/tui/views.go`
- [HTML Dashboard](https://github.com/ht2803-max/tokenmanager/blob/main/internal/web/generator.go): `internal/web/generator.go`

### Budgets and Monitoring

- [Budget Tracking](https://github.com/ht2803-max/tokenmanager/blob/main/internal/budget/budget.go): `internal/budget/budget.go`
- [Background Daemon](https://github.com/ht2803-max/tokenmanager/blob/main/internal/daemon/daemon.go): `internal/daemon/daemon.go`
- [Configuration](https://github.com/ht2803-max/tokenmanager/blob/main/internal/config/config.go): `internal/config/config.go`

### Other components

- **User**
- **Agent Session Files**
- **Desktop Notifications**

## Connections

- User → CLI Commands: runs commands
- CLI Commands → Incremental Collector: scans files (evidence: `internal/cli/root.go`)
- Agent Session Files → Incremental Collector: provides usage files (evidence: `README.md`)
- Incremental Collector → Agent Discovery: discovers adapters (evidence: `internal/collector/collector.go`)
- Incremental Collector → Agent Parsers: parses file data (evidence: `internal/collector/collector.go`)
- Agent Discovery → Agent Parsers: selects parser (evidence: `internal/agents/agents.go`)
- Agent Parsers → Usage Records: produces records (evidence: `internal/parser/codex.go`)
- Incremental Collector → SQLite Storage: writes records (evidence: `internal/collector/collector.go`)
- Incremental Collector → Configuration: uses settings (evidence: `internal/collector/collector.go`)
- SQLite Storage → Usage Records: stores records (evidence: `internal/storage/storage.go`)
- Usage Analytics → SQLite Storage: queries records (evidence: `internal/analytics/analytics.go`)
- Usage Analytics → Cost Pricing: prices usage (evidence: `internal/analytics/analytics.go`)
- Cost Pricing → Configuration: loads custom prices (evidence: `internal/pricing/pricing.go`)
- CLI Commands → Terminal Dashboard: starts dashboard (evidence: `internal/cli/root.go`)
- Terminal Dashboard → Incremental Collector: watches and rescans (evidence: `internal/tui/tui.go`)
- Terminal Dashboard → Dashboard Views: renders views (evidence: `internal/tui/tui.go`)
- CLI Commands → Reports and Export: runs report commands (evidence: `internal/cli/reports.go`)
- Reports and Export → Usage Analytics: aggregates usage (evidence: `internal/cli/reports.go`)
- CLI Commands → HTML Dashboard: exports dashboard
- HTML Dashboard → Usage Analytics: computes dashboard data (evidence: `internal/web/generator.go`)
- HTML Dashboard → Optimization Advice: includes advice (evidence: `internal/web/generator.go`)
- Usage Analytics → Usage Windows: calculates limits
- Usage Analytics → Tool Analytics: summarizes tool use
- CLI Commands → Optimization Advice: requests recommendations
- Optimization Advice → Usage Analytics: analyzes records (evidence: `internal/optimizer/optimizer.go`)
- CLI Commands → Budget Tracking: manages budgets
- Budget Tracking → Usage Analytics: checks spending (evidence: `internal/budget/budget.go`)
- CLI Commands → Background Daemon: controls daemon
- Background Daemon → Incremental Collector: collects continuously (evidence: `internal/daemon/daemon.go`)
- Background Daemon → Budget Tracking: checks alert thresholds (evidence: `internal/daemon/daemon.go`)
- Background Daemon → Desktop Notifications: sends alerts (evidence: `internal/daemon/daemon.go`)
- Background Daemon → SQLite Storage: persists alert state (evidence: `internal/daemon/daemon.go`)