@tmustier/pi-usage-extension 0.9.5 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.10.1] - 2026-10-28
+
+### Fixed
+- Read sessions from the directory Pi uses. `/usage` always read `<agentDir>/sessions`, so with a custom session directory it showed sessions Pi no longer used and missed the ones it did. It now follows Pi's order: `--session-dir`, then `PI_CODING_AGENT_SESSION_DIR`, then the `sessionDir` setting (project over global). Thanks to @JeremieAlcaraz for the report ([#98](https://github.com/tmustier/pi-extensions/issues/98)).
+
+## [0.10.0] - 2026-10-26
+
+### Added
+- **This Month period.** New tab between Last Week and Last 30 Days covering the current calendar month from local midnight on the 1st, in the graph, table, insights, and exports. Useful when a usage budget resets on the 1st of each month.
+
+### Fixed
+- Collapse Windows home directories in project labels. Backslash paths are normalised, `C:\Users\<name>\...` collapses to `~/...` like `/Users/<name>` and `/home/<name>`, and other drive paths drop the drive letter (`D:\work\repo` becomes `work/repo`). Previously the project mix insight showed raw Windows paths.
+- Make the usage tests pass on Windows.
+
+Thanks to @mturley for This Month ([#114](https://github.com/tmustier/pi-extensions/pull/114), requested in [#107](https://github.com/tmustier/pi-extensions/issues/107)) and @dawidmachon for the Windows fix ([#110](https://github.com/tmustier/pi-extensions/pull/110)).
+
 ## [0.9.5] - 2026-09-22
 
 ### Changed

package/README.md

@@ -136,7 +136,7 @@ The **Graphs** view plots usage over time for the active period as a braille lin
 - **Grouping** (`g` to cycle): by provider, by model, by thinking level, or total only. The top 6 series are shown individually; the rest merge into an `other` series. A bold **Total** line is always drawn.
 - **Cumulative vs per-bucket** (`c` to toggle): running total across the period (default), or the raw per-bucket rate.
 - **Filtering**: move the legend cursor with `↑`/`↓` and toggle series visibility with `Enter`/`Space` (`a` shows all again). The y-axis rescales to the visible series — hide the big lines to zoom into the small ones.
-- **Buckets**: hourly for Today / This Week / Last Week, daily for Last 30 Days / All Time.
+- **Buckets**: hourly for Today / This Week / Last Week (and This Month during its first 8 days), daily for This Month after its first 8 days / Last 30 Days / All Time.
 - **Line clipping**: every series (provider, model, thinking level, `other`, Total) is drawn only between its first and last bucket with usage, so late-starting or retired series don't drag a flat zero/flat tail across the whole period.
 
 Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Auxiliary usage has no reliable thinking-level attribution and appears as `Tools/summaries` in that grouping. Reasoning token counts come from `usage.reasoning` where providers report them; pi only records this field since **pi 0.80.3 (30 June 2026)**, so earlier sessions show zero reasoning tokens even though thinking models were in use.
@@ -148,6 +148,7 @@ Thinking levels are replayed from `thinking_level_change` entries in each sessio
 | **Today** | From midnight (00:00) today |
 | **This Week** | From Monday 00:00 of the current week |
 | **Last Week** | Previous week (Monday 00:00 → this Monday 00:00) |
+| **This Month** | From local midnight on the first day of the current month |
 | **Last 30 Days** | Rolling window: the last 30 calendar days including today (from midnight 29 days back) |
 | **All Time** | All recorded sessions |
 
@@ -193,7 +194,7 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 
 ## Performance & Caching
 
-`/usage` builds its stats from every session JSONL file under `<agentDir>/sessions`. To keep opens fast on large histories (multi-GB, thousands of files):
+`/usage` builds its stats from every session JSONL file in Pi's session directory (see [Data Source](#data-source)). To keep opens fast on large histories (multi-GB, thousands of files):
 
 - **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
 - **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
@@ -225,11 +226,11 @@ The "Cache" column combines both read and write tokens.
 
 ## Data Source
 
-Statistics are parsed recursively from session files in `~/.pi/agent/sessions/`, including nested subagent runs such as `run-0/` directories. Each session is a JSONL file containing assistant messages and, on Pi 0.81.0+, optional usage on tool-result, compaction, and branch-summary entries.
+Statistics are parsed recursively from session files in Pi's session directory, including nested subagent runs such as `run-0/` directories. Each session is a JSONL file containing assistant messages and, on Pi 0.81.0+, optional usage on tool-result, compaction, and branch-summary entries.
 
 Assistant messages duplicated across branched session files are deduplicated by timestamp + total tokens. Auxiliary usage is deduplicated by its stable session entry id, which avoids collapsing parallel tools that happen to report identical usage. Nested-agent reports are suppressed when their child session files are part of the scan (resolved across all copies of the parent entry, since branch copies change runId-derived paths); reports whose children are missing stay under `Tools / summaries`. Tool and summary usage contributes cost and tokens to totals, graphs, project/session mix, and burn trend, but does not count as an assistant message or distort conversation context/cache insights.
 
-Respects the `PI_CODING_AGENT_DIR` environment variable if set.
+The session directory is the one Pi uses: `--session-dir`, then the `PI_CODING_AGENT_SESSION_DIR` environment variable, then the `sessionDir` setting (project `.pi/settings.json` over the global `settings.json`), and otherwise `~/.pi/agent/sessions/`. The agent directory respects the `PI_CODING_AGENT_DIR` environment variable if set.
 
 ## Changelog
 

package/data.ts

@@ -11,6 +11,7 @@
  *   re-parses files that changed since the last run.
  */
 
+import { readFileSync } from "node:fs";
 import { readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
@@ -149,6 +150,7 @@ export interface PeriodBounds {
 	todayMs: number;
 	weekStartMs: number;
 	lastWeekStartMs: number;
+	thisMonthStartMs: number;
 	last30DaysStartMs: number;
 	nowMs: number;
 }
@@ -157,6 +159,7 @@ export interface UsageData {
 	today: TimeFilteredStats;
 	thisWeek: TimeFilteredStats;
 	lastWeek: TimeFilteredStats;
+	thisMonth: TimeFilteredStats;
 	last30Days: TimeFilteredStats;
 	allTime: TimeFilteredStats;
 	/** Deduped usage bucketed by hour start (ms) → series key → metrics. */
@@ -164,9 +167,9 @@ export interface UsageData {
 	bounds: PeriodBounds;
 }
 
-export type TabName = "today" | "thisWeek" | "lastWeek" | "last30Days" | "allTime";
+export type TabName = "today" | "thisWeek" | "lastWeek" | "thisMonth" | "last30Days" | "allTime";
 
-export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "last30Days", "allTime"];
+export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "thisMonth", "last30Days", "allTime"];
 
 export type UsageSource = "assistant" | "auxiliary";
 
@@ -237,8 +240,24 @@ export function getAgentDir(): string {
 	return process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
 }
 
-export function getSessionsDir(): string {
-	return join(getAgentDir(), "sessions");
+function sessionDirSetting(settingsPath: string): string | undefined {
+	try {
+		const { sessionDir } = JSON.parse(readFileSync(settingsPath, "utf8"));
+		return typeof sessionDir === "string" ? sessionDir : undefined;
+	} catch {
+		return undefined; // No settings file, or one Pi cannot read either.
+	}
+}
+
+/** Where Pi keeps sessions: `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, then `sessionDir` from project over global settings. */
+function getSessionsDir(): string {
+	const flag = process.argv.lastIndexOf("--session-dir");
+	const configured =
+		(flag >= 0 ? process.argv[flag + 1] : undefined) ||
+		process.env.PI_CODING_AGENT_SESSION_DIR ||
+		sessionDirSetting(join(".pi", "settings.json")) ||
+		sessionDirSetting(join(getAgentDir(), "settings.json"));
+	return configured ? resolve(configured.replace(/^~(?=\/|$)/, homedir())) : join(getAgentDir(), "sessions");
 }
 
 export function getDefaultCachePath(): string {
@@ -1038,23 +1057,32 @@ function emptyPeriodRawData(): PeriodRawData {
  */
 export function projectLabelFromCwd(cwd: string): string {
 	if (!cwd) return "(unknown)";
+	// Normalize Windows separators so backslash paths (C:\Users\me\...) match the
+	// forward-slash forms compared below. Path text after the home prefix keeps
+	// its normalized forward slashes, which is what the label displays.
+	const normalized = cwd.replaceAll("\\", "/");
 	// Collapse any home-directory prefix to "~", not just the current user's —
 	// session stores merged from other machines can carry a different username.
-	const home = homedir();
+	const home = homedir().replaceAll("\\", "/");
 	let homePrefix: string | null = null;
-	if (cwd === home || cwd.startsWith(home + "/")) {
+	if (normalized === home || normalized.startsWith(home + "/")) {
 		homePrefix = home;
 	} else {
-		const m = /^(\/Users\/[^/]+|\/home\/[^/]+)(?=\/|$)/.exec(cwd);
+		const m = /^(\/Users\/[^/]+|\/home\/[^/]+|[A-Za-z]:\/Users\/[^/]+)(?=\/|$)/.exec(normalized);
 		if (m) homePrefix = m[1]!;
 	}
-	if (homePrefix !== null && cwd.length <= homePrefix.length) return "~";
-	let rel = homePrefix !== null ? cwd.slice(homePrefix.length + 1) : cwd;
+	if (homePrefix !== null && normalized.length <= homePrefix.length) return "~";
+	let rel = homePrefix !== null ? normalized.slice(homePrefix.length + 1) : normalized;
 	const wt = rel.indexOf("/.worktrees/");
 	if (wt !== -1) rel = rel.slice(0, wt);
 	const parts = rel.split("/").filter(Boolean);
-	const label = parts.slice(0, 2).join("/");
-	return homePrefix !== null ? `~/${label}` : `/${label}`;
+	if (homePrefix !== null) return `~/${parts.slice(0, 2).join("/")}`;
+	// Windows drive paths outside a home (D:/work/repo/sub): drop the drive segment
+	// so the label keeps meaningful segments (work/repo) and stays slash-separated.
+	const segments = /^[A-Za-z]:$/.test(parts[0] ?? "") ? parts.slice(1) : parts;
+	const label = segments.slice(0, 2).join("/");
+	if (/^[A-Za-z]:\//.test(normalized)) return label;
+	return `/${label}`;
 }
 
 function emptyUsageData(bounds: PeriodBounds): UsageData {
@@ -1062,6 +1090,7 @@ function emptyUsageData(bounds: PeriodBounds): UsageData {
 		today: emptyTimeFilteredStats(),
 		thisWeek: emptyTimeFilteredStats(),
 		lastWeek: emptyTimeFilteredStats(),
+		thisMonth: emptyTimeFilteredStats(),
 		last30Days: emptyTimeFilteredStats(),
 		allTime: emptyTimeFilteredStats(),
 		hourly: new Map(),
@@ -1115,6 +1144,7 @@ function getPeriodsForTimestamp(
 	todayMs: number,
 	weekStartMs: number,
 	lastWeekStartMs: number,
+	thisMonthStartMs: number,
 	last30DaysStartMs: number
 ): TabName[] {
 	const periods: TabName[] = ["allTime"];
@@ -1124,6 +1154,7 @@ function getPeriodsForTimestamp(
 	} else if (timestamp >= lastWeekStartMs) {
 		periods.push("lastWeek");
 	}
+	if (timestamp >= thisMonthStartMs) periods.push("thisMonth");
 	if (timestamp >= last30DaysStartMs) periods.push("last30Days");
 	return periods;
 }
@@ -1140,11 +1171,12 @@ function addMessagesToUsageData(
 	todayMs: number,
 	weekStartMs: number,
 	lastWeekStartMs: number,
+	thisMonthStartMs: number,
 	last30DaysStartMs: number,
 	rawByPeriod: Record<TabName, PeriodRawData>,
 	costByDayIdx: Map<number, number>
 ): void {
-	const sessionContributed = { today: false, thisWeek: false, lastWeek: false, last30Days: false, allTime: false };
+	const sessionContributed = { today: false, thisWeek: false, lastWeek: false, thisMonth: false, last30Days: false, allTime: false };
 
 	for (let mi = 0; mi < messages.length; mi++) {
 		const msg = messages[mi]!;
@@ -1161,7 +1193,14 @@ function addMessagesToUsageData(
 
 		addToHourlyBuckets(data.hourly, msg);
 
-		const periods = getPeriodsForTimestamp(msg.timestamp, todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs);
+		const periods = getPeriodsForTimestamp(
+			msg.timestamp,
+			todayMs,
+			weekStartMs,
+			lastWeekStartMs,
+			thisMonthStartMs,
+			last30DaysStartMs
+		);
 		const tokens = {
 			// Count fresh tokens processed this turn.
 			// Include cacheWrite because those prompt tokens were newly written and billed.
@@ -1240,6 +1279,7 @@ function addMessagesToUsageData(
 	if (sessionContributed.today) data.today.totals.sessions++;
 	if (sessionContributed.thisWeek) data.thisWeek.totals.sessions++;
 	if (sessionContributed.lastWeek) data.lastWeek.totals.sessions++;
+	if (sessionContributed.thisMonth) data.thisMonth.totals.sessions++;
 	if (sessionContributed.last30Days) data.last30Days.totals.sessions++;
 	if (sessionContributed.allTime) data.allTime.totals.sessions++;
 }
@@ -1364,7 +1404,7 @@ export interface CollectUsageOptions {
 	signal?: AbortSignal;
 	/** Called once before parsing begins and periodically while files are parsed. */
 	onProgress?: (progress: CollectProgress) => void;
-	/** Defaults to `<agentDir>/sessions`. */
+	/** Defaults to the directory where Pi keeps sessions. */
 	sessionsDir?: string;
 	/** Defaults to `<agentDir>/usage-extension-cache.json`. Pass `null` to disable the on-disk cache. */
 	cachePath?: string | null;
@@ -1397,6 +1437,12 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	startOfLastWeek.setDate(startOfLastWeek.getDate() - 7);
 	const lastWeekStartMs = startOfLastWeek.getTime();
 
+	// Calendar month to date, from local midnight on the first.
+	const startOfThisMonth = new Date(now);
+	startOfThisMonth.setDate(1);
+	startOfThisMonth.setHours(0, 0, 0, 0);
+	const thisMonthStartMs = startOfThisMonth.getTime();
+
 	// Rolling 30-day window: the last 30 calendar days including today,
 	// i.e. from midnight 29 days before today. setDate handles DST correctly.
 	const startOfLast30Days = new Date(startOfToday);
@@ -1526,11 +1572,19 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	}
 
 	// 6. Aggregate in sorted path order with cross-file dedupe.
-	const data = emptyUsageData({ todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs, nowMs: now.getTime() });
+	const data = emptyUsageData({
+		todayMs,
+		weekStartMs,
+		lastWeekStartMs,
+		thisMonthStartMs,
+		last30DaysStartMs,
+		nowMs: now.getTime(),
+	});
 	const rawByPeriod: Record<TabName, PeriodRawData> = {
 		today: emptyPeriodRawData(),
 		thisWeek: emptyPeriodRawData(),
 		lastWeek: emptyPeriodRawData(),
+		thisMonth: emptyPeriodRawData(),
 		last30Days: emptyPeriodRawData(),
 		allTime: emptyPeriodRawData(),
 	};
@@ -1597,6 +1651,7 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 			todayMs,
 			weekStartMs,
 			lastWeekStartMs,
+			thisMonthStartMs,
 			last30DaysStartMs,
 			rawByPeriod,
 			costByDayIdx

package/graph.ts

@@ -118,6 +118,8 @@ function domainFor(period: TabName, bounds: PeriodBounds, hourly: Map<number, Ma
 			return { startMs: bounds.weekStartMs, endMs: bounds.nowMs };
 		case "lastWeek":
 			return { startMs: bounds.lastWeekStartMs, endMs: bounds.weekStartMs };
+		case "thisMonth":
+			return { startMs: bounds.thisMonthStartMs, endMs: bounds.nowMs };
 		case "last30Days":
 			return { startMs: bounds.last30DaysStartMs, endMs: bounds.nowMs };
 		case "allTime": {

package/index.ts

@@ -2,7 +2,7 @@
  * /usage - Usage statistics dashboard
  *
  * Shows an inline view with usage stats grouped by provider.
- * - Tab cycles: Today → This Week → Last Week → All Time
+ * - Tab cycles: Today → This Week → Last Week → This Month → All Time
  * - Arrow keys navigate providers
  * - Enter expands/collapses to show models
  *
@@ -273,6 +273,7 @@ const TAB_LABELS: Record<TabName, string> = {
 	today: "Today",
 	thisWeek: "This Week",
 	lastWeek: "Last Week",
+	thisMonth: "This Month",
 	last30Days: "Last 30 Days",
 	allTime: "All Time",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.9.5",
+  "version": "0.10.1",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",