@mohndoe/pi-atlas 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +94 -20
- package/package.json +1 -1
- package/src/components/Dashboard.ts +2 -1
package/README.md
CHANGED
|
@@ -1,40 +1,114 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pi Atlas
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@mohndoe/pi-atlas)
|
|
4
|
+
[](./LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
A terminal UI extension for [pi](https://pi.dev) that turns your agent session logs into an interactive dashboard — costs, languages, models, projects, tools, and token usage at a glance.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Features
|
|
11
|
+
|
|
12
|
+
- **Cost tracking** — per-model, per-project, and daily spend with ASCII bar charts
|
|
13
|
+
- **Language breakdown** — lines written and edited, ranked with proportional bars
|
|
14
|
+
- **Model analytics** — provider-aware model cost, call count, and sortable table
|
|
15
|
+
- **Project attribution** — cost and session count per project directory
|
|
16
|
+
- **Tool usage** — call frequency and token breakdown (input, output, cache read/write)
|
|
17
|
+
- **Multiple time ranges** — Today, Last 7 days, Last 30 days, or All time
|
|
18
|
+
- **Cache** — SHA-256-gated persists day aggregates; near-instant open on repeat visits
|
|
19
|
+
- **Zero dependencies beyond pi** — uses only the pi TUI and the `pi-tui-extras` component library
|
|
20
|
+
|
|
21
|
+
## Dashboard
|
|
22
|
+
|
|
23
|
+
The dashboard opens as a centered overlay popup (50% width, max 80% height). Navigate with the keyboard:
|
|
24
|
+
|
|
25
|
+
| Key | Action |
|
|
26
|
+
| -------------- | ------------------------------------------------ |
|
|
27
|
+
| `←` `→` | Switch tabs |
|
|
28
|
+
| `r` | Cycle time range (Today → 7d → 30d → All) |
|
|
29
|
+
| `↑` `↓` | Scroll table rows (Models, Projects, Usage tabs) |
|
|
30
|
+
| `q` / `Escape` | Close dashboard |
|
|
31
|
+
|
|
32
|
+
### Tabs
|
|
33
|
+
|
|
34
|
+
- **Overview** — KPI cards (Total Cost, Sessions, Messages, Active Days, Avg/Day, Tokens) in a compact grid. Below: a daily spend bar chart auto-scaled to fill available height. Bottom row shows top language, top model, and top project side by side. On the 1d range, the bar chart switches to hourly spend.
|
|
35
|
+
- **Languages** — Table of all programming languages detected in session logs. Color-coded per-language palette.
|
|
36
|
+
- **Models** — Table of all models and providers used. Columns: Model, Provider, Calls, Cost. Color-coded per-provider palette.
|
|
37
|
+
- **Projects** — Projects ranked by cost. Shows session count and cost per project.
|
|
38
|
+
- **Usage** — Token breakdown (Total, Input, Output, Cache Read, Cache Write) and table of tool usage.
|
|
11
39
|
|
|
12
40
|
## Install
|
|
13
41
|
|
|
42
|
+
### Via pi
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pi install npm:@mohndoe/pi-atlas
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Then run `/reload` in pi (or restart pi). The `/atlas` command is now available.
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
## How it works
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
~/.pi/agent/sessions/*.jsonl
|
|
58
|
+
│
|
|
59
|
+
▼ parseFile() ◄── entry types handled
|
|
60
|
+
┌──────────────────┐
|
|
61
|
+
│ DayAgg[] │ per calendar day
|
|
62
|
+
└────────┬─────────┘
|
|
63
|
+
│
|
|
64
|
+
▼ summarize(days, range)
|
|
65
|
+
┌──────────────────┐
|
|
66
|
+
│ StatsSummary × 4 │ 1d, 7d, 30d, All pre-computed
|
|
67
|
+
└────────┬─────────┘
|
|
68
|
+
│
|
|
69
|
+
▼
|
|
70
|
+
Tab receives StatsSummary ──→ Component render
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**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.
|
|
74
|
+
|
|
75
|
+
**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.
|
|
76
|
+
|
|
77
|
+
**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.).
|
|
78
|
+
|
|
79
|
+
**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.
|
|
80
|
+
|
|
81
|
+
## Development
|
|
82
|
+
|
|
14
83
|
```bash
|
|
15
|
-
|
|
84
|
+
# Setup
|
|
85
|
+
git clone https://github.com/MohnDoe/pi-atlas.git
|
|
16
86
|
cd pi-atlas
|
|
17
87
|
bun install
|
|
18
|
-
ln -s "$(pwd)/src/index.ts" ~/.pi/agent/extensions/pi-atlas.ts
|
|
19
|
-
```
|
|
20
88
|
|
|
21
|
-
|
|
89
|
+
# Type check
|
|
90
|
+
bun run typecheck
|
|
22
91
|
|
|
23
|
-
|
|
92
|
+
# Test
|
|
93
|
+
bun test
|
|
24
94
|
|
|
25
|
-
|
|
26
|
-
|
|
95
|
+
# Coverage
|
|
96
|
+
bun test --coverage
|
|
97
|
+
```
|
|
27
98
|
|
|
28
|
-
|
|
99
|
+
### Architecture decisions
|
|
100
|
+
|
|
101
|
+
See [docs/adr/](./docs/adr/) for recorded decisions:
|
|
29
102
|
|
|
30
|
-
|
|
103
|
+
- [ADR-0001: Global session-project map](./docs/adr/0001-global-session-project-map.md) — cost attribution model
|
|
104
|
+
- [ADR-0002: Pre-computed summaries](./docs/adr/0002-precomputed-summaries.md) — all four time ranges computed at open
|
|
31
105
|
|
|
32
|
-
|
|
106
|
+
A higher-level [ARCHITECTURE.md](./docs/ARCHITECTURE.md) covers module structure and component hierarchy.
|
|
33
107
|
|
|
34
|
-
##
|
|
108
|
+
## Data privacy
|
|
35
109
|
|
|
36
|
-
|
|
110
|
+
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.
|
|
37
111
|
|
|
38
112
|
## License
|
|
39
113
|
|
|
40
|
-
[MIT](./LICENSE)
|
|
114
|
+
[MIT](./LICENSE)
|
package/package.json
CHANGED
|
@@ -9,6 +9,7 @@ import { Overview } from "../tabs/Overview";
|
|
|
9
9
|
import { Projects } from "../tabs/Projects";
|
|
10
10
|
import { Usage } from "../tabs/Usage";
|
|
11
11
|
import type { StatsSummary, TimeRange } from "../types";
|
|
12
|
+
import pkg from "../../package.json" with { type: "json" };
|
|
12
13
|
import { RangeSelector } from "./RangeSelector";
|
|
13
14
|
import { TabBar } from "./TabBar";
|
|
14
15
|
|
|
@@ -49,7 +50,7 @@ export class Dashboard extends BorderBox {
|
|
|
49
50
|
|
|
50
51
|
super({
|
|
51
52
|
titles: [
|
|
52
|
-
|
|
53
|
+
{ text: theme.bold("Pi Atlas") + theme.fg("dim", ` · v${pkg.version}`), align: "left" },
|
|
53
54
|
rangeLabelTitle,
|
|
54
55
|
],
|
|
55
56
|
footers,
|