Architecture

llm-usage-metrics is organized around a small report-command architecture:

1. report definitions describe command identity, shared option profile, and examples
2. builders parse and normalize local usage data
3. feature aggregators reshape that data into report-specific totals or series
4. renderers emit terminal, JSON, Markdown, or share artifacts
5. a shared report runtime handles output-format resolution, diagnostics, and stdout/stderr behavior

Report definitions and runtime

• src/cli/report-definitions Canonical metadata for daily, weekly, monthly, efficiency, optimize, and trends
• src/cli/report-runtime Shared prepare/run lifecycle for format validation, share handling, terminal overflow warnings, and stdout emission

This same metadata is reused for:

• Commander command registration
• generated CLI docs
• root help examples

That keeps command/docs drift low without duplicating option descriptions outside Commander help.

Report flows

Usage

buildUsageData(...) parses source events, applies pricing, aggregates by period/source/model, then renderUsageReport(...) formats the report.

Efficiency

buildEfficiencyData(...) reuses usage parsing, attributes events to a repository root, joins them with local Git outcomes, then renderEfficiencyReport(...) formats the result.

Optimize

buildOptimizeData(...) reuses usage parsing and pricing, aggregates baseline token totals, computes candidate-model counterfactual costs, then renderOptimizeReport(...) formats the result.

Trends

buildTrendsData(...) reuses usage parsing, loads pricing only for cost mode, aggregates to daily totals, projects those totals into daily trend series, then renderTrendsReport(...) formats terminal charts or JSON.

Aggregation and rendering details

• aggregateUsage(...) supports an includeModelBreakdown profile Usage keeps per-model breakdowns; efficiency, optimize, and trends skip them.
• render/unicode-table.ts is driven by explicit row metadata (periodKey, rowKind) This keeps sorting and separators deterministic without coupling the generic table renderer to usage-row domain types.

Module boundaries

• src/cli: command creation, report builders, diagnostics emission
• src/cli/report-definitions: command metadata and shared option profiles
• src/cli/report-runtime: shared report lifecycle
• src/sources: adapter discovery and parsing
• src/domain: canonical normalized contracts
• src/pricing: LiteLLM pricing loader/cache/cost engine
• src/aggregate: period/source usage aggregation
• src/efficiency: repo attribution and Git outcome joins
• src/optimize: counterfactual pricing aggregation
• src/trends: daily trend-series aggregation
• src/render: output formatters

Invariants

• deterministic ordering for periods, sources, candidates, and models
• diagnostics on stderr, report body on stdout
• JSON/Markdown stay data-only on stdout
• provider identifiers are normalized at the domain boundary
• incomplete pricing remains explicit in output (~, warnings, or incomplete flags)