pi-tokenburn 0.1.0 → 0.3.0

package/README.md

@@ -9,6 +9,8 @@ Totals match the `tokenburn` CLI exactly.
 ## Features
 
 - **Status bar:** `🔥 1.20M ($52.79) [today]`, turns red with `OVER BUDGET` past your limit.
+- **Report chart:** `/tokenburn` shows the summary plus a vertical column chart (y-axis, budget line, current period marked, over-budget columns in red, peak/avg footer). Daily (14 days), weekly (8 weeks) or monthly (6 months).
+- **Views:** `/tokenburn day|week|month|year|all`. Status bar period: `/tokenburn status <window>` or `/tokenburn cycle`.
 - **Window panel (optional):** Today / Week / Month / Total below the editor, with in/out tokens and cost.
 - **Budgets** per day, week and month, in tokens and/or dollars.
 - **Fast:** per-file cache keyed on mtime+size. First scan of ~400 MB of sessions takes under a second; refreshes after that take milliseconds. Refresh never blocks the agent loop.
@@ -25,13 +27,37 @@ pi install git:github.com/sorinirimies/pi-tokenburn
 
 | Command | What it does |
 |---|---|
-| `/tokenburn` | Print the Today / Week / Month / All-time report |
+| `/tokenburn` · `day` · `today` | Report + **daily** chart (last 14 days) |
+| `/tokenburn week` | Report + **weekly** chart (last 8 weeks) |
+| `/tokenburn month` | Report + **monthly** chart (last 6 months) |
+| `/tokenburn year` | Report + **yearly** chart (last 5 years) |
+| `/tokenburn all` | Report + whole history (monthly columns up to 18 months, yearly beyond) |
+| `/tokenburn report <view>` · `chart <view>` | Same as above, explicit form |
+| `/tokenburn status <today\|week\|month\|year\|total>` | Set the status-bar period |
+| `/tokenburn cycle` | Rotate the status-bar period: today → week → month → year → total |
 | `/tokenburn window` | Toggle the panel below the editor |
-| `/tokenburn status <today\|week\|month\|total>` | Period shown in the status bar |
 | `/tokenburn budget <day\|week\|month> <tokens>` | Token budget, e.g. `budget day 5000000` |
 | `/tokenburn budget <day\|week\|month> $<cost>` | Dollar budget, e.g. `budget week $50` |
 | `/tokenburn cache` | Toggle counting cache read/write tokens |
 
+Tab-completion works for all of the above. Unknown input prints usage instead of failing.
+
+Chart example (`/tokenburn`, with a 600M day budget):
+
+```
+Daily tokens · last 14 days  ┄ budget 600.00M
+   1.13B │         ██
+         │         ██
+         │┄┄┄┄┄┄┄┄┄██┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄██┄▆▆┄┄┄┄┄┄┄┄┄┄
+ 565.16M │         ██                ██ ██ ▇▇
+         │      ▅▅ ██    ▂▂ ██    ▁▁ ██ ██ ██ ▄▄ ▇▇
+         └──────────────────────────────────────────
+          26 27 28 29 30 01 02 03 04 05 06 07 08 09
+          Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr
+                                                 ▲
+Σ 3.83B ($1264.30) · avg 273.80M/day · peak 1.13B (09-29 Tue)
+```
+
 Weeks start on Monday, in local time.
 
 ## Config
@@ -41,6 +67,7 @@ Weeks start on Monday, in local time.
 ```json
 {
   "includeCache": true,
+  "chartColor": true,
   "showStatus": true,
   "showWidget": false,
   "statusWindow": "today",
@@ -50,14 +77,37 @@ Weeks start on Monday, in local time.
 
 - `includeCache` (default `true`): count cache read/write tokens in totals, like the `tokenburn` CLI. Cache reads dominate (often 95%+ of tokens) but are billed far cheaper; set `false` to budget on input + output only.
 
+- `chartColor` (default `true`): color the chart using your pi theme (current period green, over-budget red, budget line yellow). Set `false` for plain text.
+
 Environment overrides for the session directory: `TOKENBURN_PI_SESSIONS`, `PI_CODING_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR`.
 
-## Develop
+## Development
 
 ```bash
-bun test
+bun install
+just check          # typecheck + tests + pack check + nushell tests (what CI runs)
+just test           # bun test only
 ```
 
+CI scripts are [nushell](https://www.nushell.sh) (`scripts/`), the same ones locally and in GitHub / Gitea Actions.
+`just --list` shows every task.
+
+## Releases (automatic)
+
+| Workflow | When | What |
+|---|---|---|
+| **CI** | push / PR | quality gate on Linux; tests on macOS, Windows and extreme time zones |
+| **Nightly Dependency Update** | every night (GitHub 02:00 UTC, Gitea 02:30) | `bun update` within ranges, verify on all platforms, commit `chore(deps)`; then **publish a patch** when a *runtime* dependency was upgraded or `feat`/`fix`/`perf` commits are waiting since the last tag |
+| **Release** | tag `vX.Y.Z` | validates the tag against `package.json`, runs the gate, `npm publish` (idempotent), creates the release |
+
+Dev-tooling-only bumps are committed but never released on their own. A downgrade blocks the whole update.
+
+Manual release: `just bump patch` (or `minor` / `major` / `X.Y.Z`), then `just release-push`.
+
+**Secrets** (repo settings): `NPM_TOKEN` — npm *granular access token* with publish rights and "bypass 2FA" (required for CI publishing). Optional: `GH_PAT` (lets a tag push trigger the release itself), `GITEA_TOKEN` (Gitea).
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org); the changelog is generated by git-cliff.
+
 ## Scope
 
 Pi sessions only. For Zed, Claude Code, Codex, Gemini and more, use the Rust [tokenburn](https://github.com/sorinirimies/tokenburn).

package/extensions/tokenburn.ts

@@ -44,15 +44,21 @@ export interface TokenBurnReport {
 	today: PeriodStats;
 	week: PeriodStats;
 	month: PeriodStats;
+	year: PeriodStats;
 	total: PeriodStats;
 }
 
+export const STATUS_WINDOWS = ["today", "week", "month", "year", "total"] as const;
+export type Window = (typeof STATUS_WINDOWS)[number];
+
 export interface TokenBurnConfig {
 	/** Count cache read/write tokens in totals (matches the tokenburn CLI). */
 	includeCache: boolean;
+	/** Color the report chart (set false if your terminal garbles ANSI in notifications). */
+	chartColor: boolean;
 	showStatus: boolean;
 	showWidget: boolean;
-	statusWindow: "today" | "week" | "month" | "total";
+	statusWindow: Window;
 	budgets: {
 		dayTokens?: number;
 		weekTokens?: number;
@@ -65,6 +71,7 @@ export interface TokenBurnConfig {
 
 const DEFAULT_CONFIG: TokenBurnConfig = {
 	includeCache: true,
+	chartColor: true,
 	showStatus: true,
 	showWidget: false,
 	statusWindow: "today",
@@ -89,18 +96,24 @@ export async function loadConfig(): Promise<TokenBurnConfig> {
 		const parsed = JSON.parse(raw);
 		return {
 			includeCache: typeof parsed.includeCache === "boolean" ? parsed.includeCache : DEFAULT_CONFIG.includeCache,
+			chartColor: typeof parsed.chartColor === "boolean" ? parsed.chartColor : DEFAULT_CONFIG.chartColor,
 			showStatus: typeof parsed.showStatus === "boolean" ? parsed.showStatus : DEFAULT_CONFIG.showStatus,
 			showWidget: typeof parsed.showWidget === "boolean" ? parsed.showWidget : DEFAULT_CONFIG.showWidget,
-			statusWindow: ["today", "week", "month", "total"].includes(parsed.statusWindow)
+			statusWindow: (STATUS_WINDOWS as readonly string[]).includes(parsed.statusWindow)
 				? parsed.statusWindow
 				: DEFAULT_CONFIG.statusWindow,
-			budgets: typeof parsed.budgets === "object" && parsed.budgets !== null ? parsed.budgets : {},
+			budgets: typeof parsed.budgets === "object" && parsed.budgets !== null ? { ...parsed.budgets } : {},
 		};
 	} catch {
-		return { ...DEFAULT_CONFIG };
+		return freshConfig();
 	}
 }
 
+/** A config that shares no mutable state with DEFAULT_CONFIG. */
+export function freshConfig(): TokenBurnConfig {
+	return { ...DEFAULT_CONFIG, budgets: {} };
+}
+
 export async function saveConfig(cfg: TokenBurnConfig): Promise<void> {
 	await mkdir(getConfigDir(), { recursive: true });
 	await writeFile(join(getConfigDir(), "tokenburn.json"), JSON.stringify(cfg, null, 2) + "\n", "utf8");
@@ -188,29 +201,54 @@ const emptyStats = (): PeriodStats => ({
 	sessions: 0,
 });
 
+/** Refresh the per-file cache and return every session file's parsed turns. */
+async function loadAll(sessionsRoot: string): Promise<Turn[][]> {
+	const files = listSessionFiles(sessionsRoot);
+	const live = new Set(files);
+	for (const key of FILE_CACHE.keys()) if (!live.has(key)) FILE_CACHE.delete(key);
+
+	const out: Turn[][] = [];
+	for (const file of files) {
+		let sig: string;
+		try {
+			const st = statSync(file);
+			sig = `${st.mtimeMs}:${st.size}`;
+		} catch {
+			continue;
+		}
+		let entry = FILE_CACHE.get(file);
+		if (!entry || entry.sig !== sig) {
+			entry = { sig, turns: await parseFile(file) };
+			FILE_CACHE.set(file, entry);
+		}
+		out.push(entry.turns);
+	}
+	return out;
+}
+
+const turnTokens = (t: Turn, includeCache: boolean) =>
+	t.input + t.output + (includeCache ? t.cacheRead + t.cacheWrite : 0);
+
 export async function collectUsage(
 	sessionsRoot: string,
 	now: Date = new Date(),
 	includeCache = true,
 ): Promise<TokenBurnReport> {
-	const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
-	const dayOfWeek = (now.getDay() + 6) % 7; // Monday = 0
-	const startOfWeek = new Date(now.getFullYear(), now.getMonth(), now.getDate() - dayOfWeek).getTime();
-	const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+	const startOfDay = bucketStart(now.getTime(), "day");
+	const startOfWeek = bucketStart(now.getTime(), "week");
+	const startOfMonth = bucketStart(now.getTime(), "month");
+	const startOfYear = bucketStart(now.getTime(), "year");
 
 	const report: TokenBurnReport = {
 		today: emptyStats(),
 		week: emptyStats(),
 		month: emptyStats(),
+		year: emptyStats(),
 		total: emptyStats(),
 	};
 
-	const files = listSessionFiles(sessionsRoot);
-	const live = new Set(files);
-	for (const key of FILE_CACHE.keys()) if (!live.has(key)) FILE_CACHE.delete(key);
-
 	const add = (p: PeriodStats, t: Turn) => {
-		p.tokens += t.input + t.output + (includeCache ? t.cacheRead + t.cacheWrite : 0);
+		p.tokens += turnTokens(t, includeCache);
 		p.input += t.input;
 		p.output += t.output;
 		p.cacheRead += t.cacheRead;
@@ -218,29 +256,18 @@ export async function collectUsage(
 		p.cost += t.cost;
 	};
 
-	for (const file of files) {
-		let sig: string;
-		try {
-			const st = statSync(file);
-			sig = `${st.mtimeMs}:${st.size}`;
-		} catch {
-			continue;
-		}
-		let entry = FILE_CACHE.get(file);
-		if (!entry || entry.sig !== sig) {
-			entry = { sig, turns: await parseFile(file) };
-			FILE_CACHE.set(file, entry);
-		}
-
+	for (const turns of await loadAll(sessionsRoot)) {
 		let maxTs = 0;
-		for (const t of entry.turns) {
+		for (const t of turns) {
 			if (t.ts > maxTs) maxTs = t.ts;
 			add(report.total, t);
+			if (t.ts >= startOfYear) add(report.year, t);
 			if (t.ts >= startOfMonth) add(report.month, t);
 			if (t.ts >= startOfWeek) add(report.week, t);
 			if (t.ts >= startOfDay) add(report.today, t);
 		}
-		if (entry.turns.length > 0) report.total.sessions++;
+		if (turns.length > 0) report.total.sessions++;
+		if (maxTs >= startOfYear) report.year.sessions++;
 		if (maxTs >= startOfMonth) report.month.sessions++;
 		if (maxTs >= startOfWeek) report.week.sessions++;
 		if (maxTs >= startOfDay) report.today.sessions++;
@@ -249,13 +276,212 @@ export async function collectUsage(
 	return report;
 }
 
+// ---------------------------------------------------------------------------
+// Time series + chart
+// ---------------------------------------------------------------------------
+
+export type Unit = "day" | "week" | "month" | "year";
+
+/** Local-time start of the day / Monday-week / month containing `ts`. */
+export function bucketStart(ts: number, unit: Unit): number {
+	const d = new Date(ts);
+	if (unit === "day") return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+	if (unit === "week") {
+		const dow = (d.getDay() + 6) % 7; // Monday = 0
+		return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+	}
+	if (unit === "year") return new Date(d.getFullYear(), 0, 1).getTime();
+	return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+}
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+
+export function bucketLabel(start: number, unit: Unit): string {
+	const d = new Date(start);
+	if (unit === "year") return String(d.getFullYear());
+	if (unit === "month") return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}`;
+	const base = `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+	return unit === "day" ? `${base} ${["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][d.getDay()]}` : `${base} wk`;
+}
+
+export interface SeriesPoint {
+	start: number;
+	label: string;
+	tokens: number;
+	cost: number;
+}
+
+export const DEFAULT_COUNT: Record<Unit, number> = { day: 14, week: 8, month: 6, year: 5 };
+
+/** Last `count` buckets ending at `now`, oldest first, empty buckets zero-filled. */
+export async function collectSeries(
+	sessionsRoot: string,
+	unit: Unit,
+	count = DEFAULT_COUNT[unit],
+	now: Date = new Date(),
+	includeCache = true,
+): Promise<SeriesPoint[]> {
+	const starts: number[] = [];
+	for (let i = count - 1; i >= 0; i--) {
+		const y = now.getFullYear();
+		const m = now.getMonth();
+		const day = now.getDate();
+		const anchor =
+			unit === "day"
+				? new Date(y, m, day - i)
+				: unit === "week"
+					? new Date(y, m, day - i * 7)
+					: unit === "year"
+						? new Date(y - i, 0, 1)
+						: new Date(y, m - i, 1);
+		starts.push(bucketStart(anchor.getTime(), unit));
+	}
+	const points = new Map<number, SeriesPoint>(
+		starts.map((start) => [start, { start, label: bucketLabel(start, unit), tokens: 0, cost: 0 }]),
+	);
+	for (const turns of await loadAll(sessionsRoot)) {
+		for (const t of turns) {
+			const pt = points.get(bucketStart(t.ts, unit));
+			if (!pt) continue;
+			pt.tokens += turnTokens(t, includeCache);
+			pt.cost += t.cost;
+		}
+	}
+	return starts.map((s) => points.get(s)!);
+}
+
+/**
+ * Whole history: monthly columns while it spans <= 18 months, yearly after that.
+ * Always at least 2 columns so the chart has a shape.
+ */
+export async function collectAllSeries(
+	sessionsRoot: string,
+	now: Date = new Date(),
+	includeCache = true,
+): Promise<{ unit: Unit; series: SeriesPoint[] }> {
+	let first = now.getTime();
+	for (const turns of await loadAll(sessionsRoot)) for (const t of turns) if (t.ts < first) first = t.ts;
+	const f = new Date(first);
+	const months = (now.getFullYear() - f.getFullYear()) * 12 + (now.getMonth() - f.getMonth()) + 1;
+	if (months <= 18) {
+		const unit: Unit = "month";
+		return { unit, series: await collectSeries(sessionsRoot, unit, Math.max(2, months), now, includeCache) };
+	}
+	const years = now.getFullYear() - f.getFullYear() + 1;
+	return { unit: "year", series: await collectSeries(sessionsRoot, "year", years, now, includeCache) };
+}
+
+const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
+const SPARK = "▁▂▃▄▅▆▇█";
+
+/** Horizontal bar of `value/max` over `width` cells, with 1/8-cell precision. */
+export function bar(value: number, max: number, width: number): string {
+	if (max <= 0 || value <= 0) return "";
+	const eighths = Math.max(1, Math.round((value / max) * width * 8));
+	const full = Math.floor(eighths / 8);
+	return "█".repeat(full) + EIGHTHS[eighths % 8];
+}
+
+export function sparkline(values: number[]): string {
+	const max = Math.max(...values, 0);
+	if (max <= 0) return SPARK[0].repeat(values.length);
+	return values.map((v) => SPARK[Math.min(7, Math.round((v / max) * 7))]).join("");
+}
+
+const UNIT_TITLE: Record<Unit, string> = { day: "Daily", week: "Weekly", month: "Monthly", year: "Yearly" };
+const UNIT_NOUN: Record<Unit, string> = { day: "day", week: "week", month: "month", year: "year" };
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+export type Paint = (kind: "bar" | "now" | "over" | "axis" | "budget" | "dim" | "title", text: string) => string;
+const plain: Paint = (_k, t) => t;
+
+/** Two header rows for a column: [top, bottom]. */
+function columnLabels(p: SeriesPoint, unit: Unit): [string, string] {
+	const d = new Date(p.start);
+	if (unit === "day") return [pad2(d.getDate()), ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"][d.getDay()]];
+	if (unit === "week") return [`${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`, "wk"];
+	if (unit === "year") return [String(d.getFullYear()), ""];
+	return [MONTHS[d.getMonth()], String(d.getFullYear())];
+}
+
+/**
+ * Vertical column chart: y-axis, 1/8-row precision, optional budget line,
+ * highlighted current bucket and over-budget columns, summary footer.
+ */
+export function renderChart(
+	series: SeriesPoint[],
+	unit: Unit,
+	opts: { height?: number; budget?: { tokens?: number; cost?: number }; paint?: Paint; title?: string } = {},
+): string[] {
+	const paint = opts.paint ?? plain;
+	const height = opts.height ?? 8;
+	const colW = unit === "day" ? 3 : 6; // bar cells + 1 gap
+	const barW = colW - 1;
+
+	const peakPoint = series.reduce((m, p) => (p.tokens > m.tokens ? p : m), series[0]);
+	const dataMax = peakPoint?.tokens ?? 0;
+	const budgetTokens = opts.budget?.tokens;
+	const scaleMax = Math.max(dataMax, budgetTokens ?? 0);
+	const total = series.reduce((a, p) => a + p.tokens, 0);
+	const totalCost = series.reduce((a, p) => a + p.cost, 0);
+
+	const yLabels = [formatNum(scaleMax), formatNum(scaleMax / 2), "0"];
+	const yW = Math.max(...yLabels.map((l) => l.length)) + 1;
+	const labelFor = (row: number) => (row === height ? yLabels[0] : row === Math.ceil(height / 2) ? yLabels[1] : "");
+	const budgetRow = budgetTokens && scaleMax > 0 ? Math.max(1, Math.ceil((budgetTokens / scaleMax) * height)) : 0;
+
+	const isOver = (p: SeriesPoint) =>
+		opts.budget ? isOverBudget({ tokens: p.tokens, cost: p.cost } as PeriodStats, opts.budget) : false;
+	const kindOf = (i: number): "bar" | "now" | "over" =>
+		isOver(series[i]) ? "over" : i === series.length - 1 ? "now" : "bar";
+
+	const lines: string[] = [];
+	lines.push(
+		paint("title", opts.title ?? `${UNIT_TITLE[unit]} tokens`) +
+			paint("dim", ` · ${opts.title ? "" : "last "}${series.length} ${UNIT_NOUN[unit]}${series.length === 1 ? "" : "s"}`) +
+			(budgetTokens ? paint("budget", `  ┄ budget ${formatNum(budgetTokens)}`) : ""),
+	);
+
+	for (let row = height; row >= 1; row--) {
+		let line = paint("axis", `${labelFor(row).padStart(yW)} │`);
+		for (let i = 0; i < series.length; i++) {
+			const h = scaleMax > 0 ? (series[i].tokens / scaleMax) * height : 0;
+			let cell: string;
+			if (h >= row) cell = "█";
+			else if (h > row - 1 && series[i].tokens > 0) cell = SPARK[Math.min(7, Math.max(0, Math.floor((h - (row - 1)) * 8) - 1))];
+			else if (row === 1 && series[i].tokens > 0) cell = "▁";
+			else cell = row === budgetRow ? "┄" : " ";
+			const filled = cell !== " " && cell !== "┄";
+			const body = cell.repeat(barW);
+			line += filled ? paint(kindOf(i), body) : cell === "┄" ? paint("budget", body) : body;
+			line += row === budgetRow ? paint("budget", "┄") : " ";
+		}
+		lines.push(line);
+	}
+
+	lines.push(paint("axis", `${"".padStart(yW)} └${"─".repeat(series.length * colW)}`));
+	const pad = " ".repeat(yW + 2);
+	const cols = series.map((p, i) => ({ l: columnLabels(p, unit), now: i === series.length - 1 }));
+	lines.push(pad + cols.map((c) => c.l[0].padEnd(colW)).join(""));
+	lines.push(paint("dim", pad + cols.map((c) => c.l[1].padEnd(colW)).join("")));
+	lines.push(pad + cols.map((c) => (c.now ? paint("now", "▲".padEnd(colW)) : " ".repeat(colW))).join(""));
+
+	const avg = series.length ? total / series.length : 0;
+	lines.push(
+		paint(
+			"dim",
+			`Σ ${formatNum(total)} (${formatCost(totalCost)}) · avg ${formatNum(avg)}/${UNIT_NOUN[unit]}` +
+				(dataMax > 0 ? ` · peak ${formatNum(dataMax)} (${bucketLabel(peakPoint.start, unit)})` : ""),
+		),
+	);
+	return lines;
+}
+
 /** Clear the per-file cache (tests). */
 export function clearCache(): void {
 	FILE_CACHE.clear();
 }
 
-export type Window = "today" | "week" | "month" | "total";
-
 export function budgetsFor(cfg: TokenBurnConfig, w: Window): { tokens?: number; cost?: number } {
 	const b = cfg.budgets;
 	if (w === "today") return { tokens: b.dayTokens, cost: b.dayCost };
@@ -268,8 +494,22 @@ export function isOverBudget(p: PeriodStats, b: { tokens?: number; cost?: number
 	return (b.tokens !== undefined && p.tokens > b.tokens) || (b.cost !== undefined && p.cost > b.cost);
 }
 
+/** Map chart roles to pi theme colors. */
+export function themePaint(theme: { fg: (c: any, t: string) => string }): Paint {
+	const color: Record<string, string> = {
+		bar: "accent",
+		now: "success",
+		over: "error",
+		axis: "dim",
+		budget: "warning",
+		dim: "dim",
+		title: "accent",
+	};
+	return (kind, text) => theme.fg(color[kind], text);
+}
+
 export default function tokenBurnExtension(pi: ExtensionAPI) {
-	let config: TokenBurnConfig = { ...DEFAULT_CONFIG };
+	let config: TokenBurnConfig = freshConfig();
 
 	const updateUI = async (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
@@ -307,6 +547,7 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
 				line("Today", report.today, budgetsFor(config, "today")),
 				line("Week", report.week, budgetsFor(config, "week")),
 				line("Month", report.month, budgetsFor(config, "month")),
+				line("Year", report.year),
 				line("Total", report.total),
 				`└${"─".repeat(46)}┘`,
 			];
@@ -328,70 +569,199 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("tokenburn", {
-		description: "TokenBurn stats: show report, toggle widget, or set budgets",
-		getArgumentCompletions: (prefix: string) => {
-			const opts = ["report", "window", "cache", "status <today|week|month|total>", "budget <day|week|month> <tokens|$cost>"];
-			return opts.filter((o) => o.startsWith(prefix)).map((value) => ({ value }));
-		},
+		description: "TokenBurn: /tokenburn [day|week|month|year|all] chart, status <window>, cycle, window, budget, cache",
+		getArgumentCompletions: (prefix: string) => completions(prefix),
 		handler: async (args, ctx) => {
-			const [cmd, p1, p2] = (args ?? "").trim().split(/\s+/).filter(Boolean);
-
-			if (cmd === "window" || cmd === "widget") {
-				config.showWidget = !config.showWidget;
+			const cmd = parseCommand(args);
+			const persist = async () => {
 				await saveConfig(config);
 				await updateUI(ctx);
-				ctx.ui.notify(`tokenburn widget: ${config.showWidget ? "enabled" : "hidden"}`, "info");
-				return;
-			}
+			};
 
-			if (cmd === "status" && ["today", "week", "month", "total"].includes(p1)) {
-				config.statusWindow = p1 as any;
-				await saveConfig(config);
-				await updateUI(ctx);
-				ctx.ui.notify(`tokenburn status window set to: ${p1}`, "info");
-				return;
-			}
+			switch (cmd.kind) {
+				case "window":
+					config.showWidget = !config.showWidget;
+					await persist();
+					ctx.ui.notify(`tokenburn widget: ${config.showWidget ? "enabled" : "hidden"}`, "info");
+					return;
 
-			if (cmd === "cache") {
-				config.includeCache = !config.includeCache;
-				await saveConfig(config);
-				await updateUI(ctx);
-				ctx.ui.notify(`tokenburn: cache tokens ${config.includeCache ? "included" : "excluded"}`, "info");
-				return;
-			}
+				case "status":
+					config.statusWindow = cmd.window;
+					await persist();
+					ctx.ui.notify(`tokenburn status window: ${cmd.window}`, "info");
+					return;
 
-			if (cmd === "budget") {
-				const isCost = (p2 ?? "").startsWith("$");
-				const val = Number((p2 ?? "").replace(/^\$/, ""));
-				if (!["day", "week", "month"].includes(p1 ?? "") || !Number.isFinite(val) || val <= 0) {
-					ctx.ui.notify("Usage: /tokenburn budget <day|week|month> <tokens | $cost>", "warning");
+				case "cycle": {
+					const next = STATUS_WINDOWS[(STATUS_WINDOWS.indexOf(config.statusWindow) + 1) % STATUS_WINDOWS.length];
+					config.statusWindow = next;
+					await persist();
+					ctx.ui.notify(`tokenburn status window: ${next}`, "info");
+					return;
+				}
+
+				case "cache":
+					config.includeCache = !config.includeCache;
+					await persist();
+					ctx.ui.notify(`tokenburn: cache tokens ${config.includeCache ? "included" : "excluded"}`, "info");
+					return;
+
+				case "budget": {
+					const key = `${cmd.period}${cmd.isCost ? "Cost" : "Tokens"}` as keyof TokenBurnConfig["budgets"];
+					config.budgets[key] = cmd.amount;
+					await persist();
+					ctx.ui.notify(
+						`tokenburn ${cmd.period} budget: ${cmd.isCost ? formatCost(cmd.amount) : formatNum(cmd.amount) + " tokens"}`,
+						"info",
+					);
 					return;
 				}
-				const key = `${p1}${isCost ? "Cost" : "Tokens"}` as keyof TokenBurnConfig["budgets"];
-				config.budgets[key] = val;
-				await saveConfig(config);
-				await updateUI(ctx);
-				ctx.ui.notify(`tokenburn ${p1} budget: ${isCost ? formatCost(val) : formatNum(val) + " tokens"}`, "info");
-				return;
-			}
 
-			// Default: print report
-			const report = await collectUsage(getSessionsDir(), new Date(), config.includeCache);
-			const formatRow = (name: string, p: PeriodStats) =>
-				`${name.padEnd(8)}: ${formatNum(p.tokens).padStart(8)} tokens (${formatCost(p.cost)}) · in:${formatNum(p.input)} out:${formatNum(p.output)} cache:${formatNum(p.cacheRead + p.cacheWrite)} · ${p.sessions} sessions`;
-
-			const output = [
-				"🔥 TokenBurn Report",
-				"--------------------------------------------------",
-				formatRow("Today", report.today),
-				formatRow("This Week", report.week),
-				formatRow("This Month", report.month),
-				formatRow("All Time", report.total),
-				"--------------------------------------------------",
-				`Use '/tokenburn window' to toggle persistent status window.`,
-			].join("\n");
-
-			ctx.ui.notify(output, "info");
+				case "invalid":
+					ctx.ui.notify(cmd.message, "warning");
+					return;
+
+				case "report": {
+					const root = getSessionsDir();
+					const now = new Date();
+					const report = await collectUsage(root, now, config.includeCache);
+					const paint = config.chartColor ? themePaint(ctx.ui.theme) : undefined;
+
+					let chart: string[];
+					if (cmd.view === "all") {
+						const all = await collectAllSeries(root, now, config.includeCache);
+						chart = renderChart(all.series, all.unit, { paint, title: "All time" });
+					} else {
+						const series = await collectSeries(root, cmd.view, DEFAULT_COUNT[cmd.view], now, config.includeCache);
+						const budgetWindow: Window | undefined =
+							cmd.view === "day" ? "today" : cmd.view === "year" ? undefined : cmd.view;
+						chart = renderChart(series, cmd.view, {
+							paint,
+							budget: budgetWindow ? budgetsFor(config, budgetWindow) : undefined,
+						});
+					}
+
+					const row = (name: string, p: PeriodStats) =>
+						`${name.padEnd(10)} ${formatNum(p.tokens).padStart(8)} tokens ${formatCost(p.cost).padStart(9)} · in:${formatNum(p.input)} out:${formatNum(p.output)} cache:${formatNum(p.cacheRead + p.cacheWrite)} · ${p.sessions} sess`;
+					const rule = "─".repeat(60);
+					ctx.ui.notify(
+						[
+							"🔥 TokenBurn Report",
+							rule,
+							row("Today", report.today),
+							row("This Week", report.week),
+							row("This Month", report.month),
+							row("This Year", report.year),
+							row("All Time", report.total),
+							rule,
+							...chart,
+							rule,
+							"/tokenburn day|week|month|year|all · status <window> · cycle · window · budget · cache",
+						].join("\n"),
+						"info",
+					);
+					return;
+				}
+			}
 		},
 	});
 }
+
+// ---------------------------------------------------------------------------
+// Command parsing + completions (pure, unit-tested)
+// ---------------------------------------------------------------------------
+
+export const REPORT_VIEWS = ["day", "week", "month", "year", "all"] as const;
+export type ReportView = (typeof REPORT_VIEWS)[number];
+export const BUDGET_PERIODS = ["day", "week", "month"] as const;
+
+export type Command =
+	| { kind: "report"; view: ReportView }
+	| { kind: "status"; window: Window }
+	| { kind: "cycle" }
+	| { kind: "window" }
+	| { kind: "cache" }
+	| { kind: "budget"; period: (typeof BUDGET_PERIODS)[number]; amount: number; isCost: boolean }
+	| { kind: "invalid"; message: string };
+
+export const USAGE =
+	"Usage: /tokenburn [day|week|month|year|all] · status <today|week|month|year|total> · cycle · window · budget <day|week|month> <tokens|$cost> · cache";
+
+const asView = (w: string | undefined): ReportView | undefined =>
+	w === "today" ? "day" : (REPORT_VIEWS as readonly string[]).includes(w ?? "") ? (w as ReportView) : undefined;
+
+export function parseCommand(args: string | undefined): Command {
+	const [cmd, p1, p2] = (args ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
+	if (!cmd) return { kind: "report", view: "day" };
+
+	const view = asView(cmd);
+	if (view) return { kind: "report", view };
+
+	switch (cmd) {
+		case "report":
+		case "chart": {
+			if (p1 === undefined) return { kind: "report", view: "day" };
+			const v = asView(p1);
+			return v ? { kind: "report", view: v } : { kind: "invalid", message: `Unknown view "${p1}". ${USAGE}` };
+		}
+		case "status":
+			return (STATUS_WINDOWS as readonly string[]).includes(p1 ?? "")
+				? { kind: "status", window: p1 as Window }
+				: { kind: "invalid", message: `Usage: /tokenburn status <${STATUS_WINDOWS.join("|")}>` };
+		case "cycle":
+			return { kind: "cycle" };
+		case "window":
+		case "widget":
+			return { kind: "window" };
+		case "cache":
+			return { kind: "cache" };
+		case "budget": {
+			const isCost = (p2 ?? "").startsWith("$");
+			const amount = Number((p2 ?? "").replace(/^\$/, ""));
+			if (!(BUDGET_PERIODS as readonly string[]).includes(p1 ?? "") || !Number.isFinite(amount) || amount <= 0) {
+				return { kind: "invalid", message: "Usage: /tokenburn budget <day|week|month> <tokens | $cost>" };
+			}
+			return { kind: "budget", period: p1 as (typeof BUDGET_PERIODS)[number], amount, isCost };
+		}
+		default:
+			return { kind: "invalid", message: `Unknown option "${cmd}". ${USAGE}` };
+	}
+}
+
+export interface CompletionItem {
+	value: string;
+	/** Required by pi: it calls `label.endsWith(...)` when applying a completion. */
+	label: string;
+	description?: string;
+}
+
+const TOP_LEVEL: CompletionItem[] = [
+	{ value: "day", label: "day", description: "Report + daily chart (last 14 days)" },
+	{ value: "week", label: "week", description: "Report + weekly chart (last 8 weeks)" },
+	{ value: "month", label: "month", description: "Report + monthly chart (last 6 months)" },
+	{ value: "year", label: "year", description: "Report + yearly chart (last 5 years)" },
+	{ value: "all", label: "all", description: "Report + whole history" },
+	{ value: "status ", label: "status", description: "Set the status-bar period" },
+	{ value: "cycle", label: "cycle", description: "Rotate the status-bar period" },
+	{ value: "window", label: "window", description: "Toggle the panel below the editor" },
+	{ value: "budget ", label: "budget", description: "Set a day/week/month budget" },
+	{ value: "cache", label: "cache", description: "Toggle counting cache tokens" },
+];
+
+/** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
+export function completions(prefix: string): CompletionItem[] | null {
+	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
+	const sub = (head: string, words: readonly string[], desc: (w: string) => string): CompletionItem[] =>
+		words.map((w) => ({ value: `${head} ${w}`, label: w, description: desc(w) }));
+
+	let pool: CompletionItem[];
+	if (text.startsWith("status ")) pool = sub("status", STATUS_WINDOWS, (w) => `Show ${w} in the status bar`);
+	else if (text.startsWith("budget ") && !/^budget \S+ /.test(text))
+		pool = sub("budget", BUDGET_PERIODS, (w) => `Set the ${w} budget (tokens or $cost)`);
+	else if (/^(report|chart) /.test(text)) {
+		const head = text.split(" ")[0];
+		pool = sub(head, REPORT_VIEWS, (w) => `${head} for ${w}`);
+	} else pool = TOP_LEVEL;
+
+	const out = pool.filter((i) => i.value.startsWith(text));
+	return out.length > 0 ? out : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tokenburn",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Pi extension for live token usage monitoring and budget tracking (Day / Week / Month / Total). 0 prompt tokens.",
   "keywords": ["pi-package", "pi-extension", "tokenburn", "tokens", "analytics", "budget", "stats"],
   "license": "MIT",
@@ -11,6 +11,20 @@
   },
   "homepage": "https://github.com/sorinirimies/pi-tokenburn#readme",
   "files": ["extensions", "README.md", "LICENSE"],
-  "pi": { "extensions": ["./extensions/tokenburn.ts"] },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" }
+  "pi": {
+    "extensions": ["./extensions/tokenburn.ts"]
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "nu scripts/ci/quality_gate.nu"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  }
 }