# @mohndoe/pi-atlas

<p align="center">
  <strong>See your AI usage and cost directly in Pi.</strong>
</p>
<p align="center">
  <img alt="NPM Downloads" src="https://img.shields.io/npm/dw/%40mohndoe%2Fpi-atlas?color=blue">
  <a href="https://www.npmjs.com/package/@mohndoe/pi-atlas"><img src="https://img.shields.io/npm/v/%40mohndoe%2Fpi-atlas?label=release" alt="Version"></a>
  <img src="https://img.shields.io/badge/coverage-97%25-green" alt="Coverage">
  <br/>
  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&colorA=222222&logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat&colorA=222222" alt="Bun">
  <a href="https://github.com/mohndoe/pi-atlas/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mohndoe/pi-atlas?style=flat&colorA=222222&colorB=58A6FF" alt="License"></a>
</p>

A [pi](https://pi.dev) extension that turns your session logs into an interactive dashboard — costs, languages, models, projects, tools, and token usage at a glance.

<p align="center">
 <img alt="pi-atlas screenshot" src="./media/screenshot.png" />
</p>

---

## Features

- **Multiple time ranges** — Today, Last 7 days, Last 30 days, or All time
- **Cost tracking** — per-model, per-project, based on real usage costs
- **Language breakdown** — lines written and edited
- **Model analytics** — provider-aware model cost, call count, works with local LLMs too
- **Project attribution** — cost and session count per project directory
- **Usage overview** — tool call frequency and token breakdown (input, output, cache read/write)
- **Cache** — SHA-256-gated persists day aggregates; near-instant open on next visits
- **Zero dependencies** — uses only the pi TUI and the [`@mohndoe/pi-tui-extras`](https://github.com/MohnDoe/pi-tui-extras) component library

## Dashboard

### Tabs

- **Overview** — Cards displaying total cost, sessions count, messages count, active days, average cost per day, total tokens. A bar chart displaying cost overtime. And top language, top model, and top project side by side.
- **Languages** — Languages ranked by line written.
- **Models** — Models ranked by cost. Shows providers, calls and cost per model.
- **Projects** — Projects ranked by cost. Shows session count and cost per project.
- **Skills** — Skills used ranked by cost. Estimation of what skill invocations cost.
- **Usage** — Token breakdown (Total, Input, Output, Cache Read, Cache Write) and table of tool usage.

All tabs displayed data correspond to the selected time range (press `r` to change it). Press left/right arrows to change tabs.

## Install

```bash
pi install npm:@mohndoe/pi-atlas
```

Then run `/reload` in pi (or restart pi). The `/atlas` command is now available.

## Usage

In the pi terminal, type `/atlas` to open the atlas dashboard. Session data is loaded from `~/.pi/agent/sessions/` -- on first load this may take a moment while JSONL files are parsed. Subsequent opens use a cached snapshot and load instantly.

## How it works

```
~/.pi/agent/sessions/*.jsonl
         │
         ▼ parseFile()        ◄── entry types handled
  ┌──────────────────┐
  │  DayAgg[]         │   per calendar day
  └────────┬─────────┘
           │
           ▼ summarize(days, range)
  ┌──────────────────┐
  │ StatsSummary × 4  │   1d, 7d, 30d, All pre-computed
  └────────┬─────────┘
           │
           ▼
  Tab receives StatsSummary  ──→  Component render
```

**Data sources** — pi stores every session as a `.jsonl` file in `~/.pi/agent/sessions/`. Pi Atlas parses entry types: session headers, user messages, assistant messages, tool results, model changes, thinking level changes, compactions, and branch summaries.

**Caching** — On first open, the sessions directory is scanned and all JSONL files are parsed into `DayAgg` objects. This aggregate is cached to disk alongside a SHA-256 signature of the directory (file paths, sizes, modification times). On subsequent opens, the cache is reused if the signature matches, making the dashboard appear instantly.

**Language detection** — Lines are counted by splitting written/edited content on `\n`. File extensions map to language names via a built-in mapping of 70+ extensions (TypeScript, Python, Rust, Go, etc.).

**Cost attribution** — Assistant message costs are attributed to all active projects in the session. See [ADR-0001](./docs/adr/0001-global-session-project-map.md) for details.

## Development

```bash
# Setup
git clone https://github.com/MohnDoe/pi-atlas.git
cd pi-atlas
bun install

# Type check
bun run typecheck

# Test
bun test

# Coverage
bun test --coverage
```

### Architecture decisions

See [docs/adr/](./docs/adr/) for recorded decisions:

- [ADR-0001: Global session-project map](./docs/adr/0001-global-session-project-map.md) — cost attribution model
- [ADR-0002: Pre-computed summaries](./docs/adr/0002-precomputed-summaries.md) — all four time ranges computed at open

A higher-level [ARCHITECTURE.md](./docs/ARCHITECTURE.md) covers module structure and component hierarchy.

## Data privacy

Pi Atlas reads session logs from `~/.pi/agent/sessions/`. All processing is done locally - no data ever leaves your machine. The cache file is written to `~/.pi/pi-atlas-cache.json` and contains aggregated statistics (costs and counts), not message content.

## License

[MIT](./LICENSE)