# sumit1612/pi-usage architecture

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

- Interactive diagram: https://gitdiagram.com/sumit1612/pi-usage
- Repository: https://github.com/sumit1612/pi-usage

## Overview

pi-usage turns local pi session logs into token, context, and cost analytics through a shared aggregation engine, surfaced in a standalone CLI and pi’s interactive /usage dashboard. The README documents views, filters, exports, budget checks, and live refresh; sampled source confirms the extension’s call into the core and the core’s session-processing behavior. The CLI implementation was not sampled, so its documented relationship to the core is cited to the README. Formatting is shown as a distinct runtime capability; its caller was not verified.

Main entry points: [`lib/core.js`](https://github.com/sumit1612/pi-usage/blob/main/lib/core.js) (Usage aggregation), [`bin/pi-usage`](https://github.com/sumit1612/pi-usage/blob/main/bin/pi-usage) (CLI analytics), [`extensions/usage.ts`](https://github.com/sumit1612/pi-usage/blob/main/extensions/usage.ts) (Usage dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Local Inputs"]
  node_session_logs[("Session logs")]
end

subgraph group_engine["Usage Engine"]
  node_aggregator["Usage aggregation<br/>[core.js]"]
end

subgraph group_surfaces["User Interfaces"]
  node_cli["CLI analytics"]
  node_dashboard["Usage dashboard<br/>[usage.ts]"]
end

subgraph group_formatting["Terminal Formatting"]
  node_cli_formatting["CLI formatting<br/>[presentation.js]"]
end

node_user(("Pi user"))
node_cli_user(("CLI user"))
node_pi_host["Pi agent"]

node_cli_user -->|"runs commands"| node_cli
node_user -->|"uses"| node_pi_host
node_pi_host -->|"opens /usage"| node_dashboard
node_session_logs -->|"reads logs"| node_aggregator
node_dashboard -->|"loads aggregates"| node_aggregator
node_cli -->|"uses shared engine"| node_aggregator

click node_aggregator "https://github.com/sumit1612/pi-usage/blob/main/lib/core.js"
click node_cli "https://github.com/sumit1612/pi-usage/blob/main/bin/pi-usage"
click node_dashboard "https://github.com/sumit1612/pi-usage/blob/main/extensions/usage.ts"
click node_cli_formatting "https://github.com/sumit1612/pi-usage/blob/main/lib/presentation.js"

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_session_logs,node_user,node_cli_user toneBlue
class node_aggregator toneAmber
class node_cli,node_dashboard toneMint
class node_cli_formatting toneRose
class node_pi_host toneIndigo
```

## Components

### Local Inputs

- **Session logs**

### Usage Engine

- [Usage aggregation](https://github.com/sumit1612/pi-usage/blob/main/lib/core.js): `lib/core.js`

### User Interfaces

- [CLI analytics](https://github.com/sumit1612/pi-usage/blob/main/bin/pi-usage): `bin/pi-usage`
- [Usage dashboard](https://github.com/sumit1612/pi-usage/blob/main/extensions/usage.ts): `extensions/usage.ts`

### Terminal Formatting

- [CLI formatting](https://github.com/sumit1612/pi-usage/blob/main/lib/presentation.js): `lib/presentation.js`

### Other components

- **Pi user**
- **CLI user**
- **Pi agent**

## Connections

- CLI user → CLI analytics: runs commands (evidence: `README.md`)
- Pi user → Pi agent: uses (evidence: `README.md`)
- Pi agent → Usage dashboard: opens /usage (evidence: `README.md`)
- Session logs → Usage aggregation: reads logs (evidence: `README.md`)
- Usage dashboard → Usage aggregation: loads aggregates (evidence: `extensions/usage.ts`)
- CLI analytics → Usage aggregation: uses shared engine (evidence: `README.md`)
