ccusage 0.5.0 → 0.6.1

package/README.md

@@ -5,6 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/ccusage?color=yellow)](https://npmjs.com/package/ccusage)
 [![NPM Downloads](https://img.shields.io/npm/dy/ccusage)](https://www.npmjs.com/package/ccusage)
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ryoppippi/ccusage)
+
 <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
 
 <div align="center">
@@ -16,34 +17,36 @@ A CLI tool for analyzing Claude Code usage from local JSONL files.
 Inspired by [this article](https://note.com/milliondev/n/n1d018da2d769) about tracking Claude Code usage costs.
 
 ## What is `ccusage` (by NotebookLM)
+
 <details>
  <summary>Podcact</summary>
 
 # English
-https://github.com/user-attachments/assets/7a00f2f3-82a7-41b6-a8da-e04b76b5e35a
 
+https://github.com/user-attachments/assets/7a00f2f3-82a7-41b6-a8da-e04b76b5e35a
 
 # 日本語
+
 https://github.com/user-attachments/assets/db09fc06-bf57-4d37-9b06-514851bcc1d0
 
 </details>
 
-
 ## Motivation
 
-Claude Code's Max plan offers unlimited usage - but wouldn't it be interesting to know how much you'd be paying if you were on a pay-per-use plan? 
+Claude Code's Max plan offers unlimited usage - but wouldn't it be interesting to know how much you'd be paying if you were on a pay-per-use plan?
 
 This tool helps you understand the value you're getting from your subscription by calculating the equivalent costs of your actual usage. See how much you're saving and enjoy that satisfying feeling of getting great value! 😊
 
 ## Features
 
 - 📊 **Daily Report**: View token usage and costs aggregated by date
+- 📅 **Monthly Report**: View token usage and costs aggregated by month
 - 💬 **Session Report**: View usage grouped by conversation sessions
 - 📅 **Date Filtering**: Filter reports by date range using `--since` and `--until`
 - 📁 **Custom Path**: Support for custom Claude data directory locations
 - 🎨 **Beautiful Output**: Colorful table-formatted display
 - 📄 **JSON Output**: Export data in structured JSON format with `--json`
-- 💰 **Cost Tracking**: Shows costs in USD for each day/session
+- 💰 **Cost Tracking**: Shows costs in USD for each day/month/session
 - 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
 
 ## Important Disclaimer
@@ -51,6 +54,7 @@ This tool helps you understand the value you're getting from your subscription b
 ⚠️ **This is NOT an official Claude tool** - it's an independent community project that analyzes locally stored usage data.
 
 **Cost calculations are estimates only** and may not reflect actual billing:
+
 - Costs shown are virtual/estimated based on token counts and model pricing data
 - Actual costs may vary due to pricing changes, special rates, or billing adjustments
 - We do not guarantee the accuracy of calculated costs
@@ -134,10 +138,41 @@ ccusage daily --json
 ccusage daily --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage daily --mode calculate  # Always calculate costs from tokens
 ccusage daily --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage daily --order asc       # Show oldest dates first
+ccusage daily --order desc      # Show newest dates first (default)
 ```
 
 `ccusage` is an alias for `ccusage daily`, so you can run it without specifying the subcommand.
 
+### Monthly Report
+
+Shows token usage and costs aggregated by month:
+
+```bash
+# Show all monthly usage
+ccusage monthly
+
+# Filter by date range
+ccusage monthly --since 20250101 --until 20250531
+
+# Use custom Claude data directory
+ccusage monthly --path /custom/path/to/.claude
+
+# Output in JSON format
+ccusage monthly --json
+
+# Control cost calculation mode
+ccusage monthly --mode auto       # Use costUSD when available, calculate otherwise (default)
+ccusage monthly --mode calculate  # Always calculate costs from tokens
+ccusage monthly --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage monthly --order asc       # Show oldest months first
+ccusage monthly --order desc      # Show newest months first (default)
+```
+
 ### Session Report
 
 Shows usage grouped by conversation sessions, sorted by cost:
@@ -159,6 +194,10 @@ ccusage session --json
 ccusage session --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage session --mode calculate  # Always calculate costs from tokens
 ccusage session --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage session --order asc       # Show oldest sessions first
+ccusage session --order desc      # Show newest sessions first (default)
 ```
 
 ### Options
@@ -166,10 +205,11 @@ ccusage session --mode display    # Always show pre-calculated costUSD values
 All commands support the following options:
 
 - `-s, --since <date>`: Filter from date (YYYYMMDD format)
-- `-u, --until <date>`: Filter until date (YYYYMMDD format)  
+- `-u, --until <date>`: Filter until date (YYYYMMDD format)
 - `-p, --path <path>`: Custom path to Claude data directory (default: `~/.claude`)
 - `-j, --json`: Output results in JSON format instead of table
 - `-m, --mode <mode>`: Cost calculation mode: `auto` (default), `calculate`, or `display`
+- `-o, --order <order>`: Sort order: `desc` (newest first, default) or `asc` (oldest first).
 - `-d, --debug`: Show pricing mismatch information for debugging
 - `--debug-samples <number>`: Number of sample discrepancies to show in debug output (default: 5)
 - `-h, --help`: Display help message
@@ -197,10 +237,12 @@ ccusage mcp --mode calculate
 ```
 
 The MCP server supports both **stdio** and **HTTP stream** transports:
+
 - **stdio** (default): Best for local integration where the client directly spawns the process
 - **HTTP stream**: Best for remote access when you need to call the server from another machine or network location
 
 Available MCP tools:
+
 - `daily`: Returns daily usage reports (accepts `since`, `until`, `mode` parameters)
 - `session`: Returns session usage reports (accepts `since`, `until`, `mode` parameters)
 
@@ -212,18 +254,18 @@ Available MCP tools:
 
 To use ccusage MCP with Claude Desktop, add this to your Claude Desktop configuration file:
 
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
-  "mcpServers": {
-    "ccusage": {
-      "command": "npx",
-      "args": ["ccusage@latest", "mcp"],
-      "env": {}
-    }
-  }
+	"mcpServers": {
+		"ccusage": {
+			"command": "npx",
+			"args": ["ccusage@latest", "mcp"],
+			"env": {}
+		}
+	}
 }
 ```
 
@@ -231,13 +273,13 @@ Or if you have ccusage installed globally:
 
 ```json
 {
-  "mcpServers": {
-    "ccusage": {
-      "command": "ccusage",
-      "args": ["mcp"],
-      "env": {}
-    }
-  }
+	"mcpServers": {
+		"ccusage": {
+			"command": "ccusage",
+			"args": ["mcp"],
+			"env": {}
+		}
+	}
 }
 ```
 
@@ -246,6 +288,7 @@ After adding this configuration, restart Claude Desktop. You'll then be able to
 ## Output Example
 
 ### Daily Report
+
 ```
 ╭──────────────────────────────────────────╮
 │                                          │
@@ -265,6 +308,7 @@ After adding this configuration, restart Claude Desktop. You'll then be able to
 ```
 
 ### Session Report
+
 ```
 ╭───────────────────────────────────────────────╮
 │                                               │
@@ -284,6 +328,7 @@ After adding this configuration, restart Claude Desktop. You'll then be able to
 ```
 
 ## Requirements
+
 - Claude Code usage history files (`~/.claude/projects/**/*.jsonl`)
 
 ## License

package/dist/calculate-cost.d.ts

@@ -1,18 +1,21 @@
-import "./index-BurjgCfW.js";
-import "./pricing-fetcher-DygIroMj.js";
-import { TokenData, TokenTotals } from "./types-B3ib19os.js";
-import { DailyUsage, SessionUsage } from "./data-loader-LMCrJ-lW.js";
+import "./pricing-fetcher-CfEgfzSr.js";
+import { DailyUsage, MonthlyUsage, SessionUsage } from "./data-loader-VdEcqJHc.js";
 
 //#region src/calculate-cost.d.ts
-declare function calculateTotals(data: Array<DailyUsage | SessionUsage>): TokenTotals;
-declare function getTotalTokens(tokens: TokenData): number;
-declare function createTotalsObject(totals: TokenTotals): {
+type TokenData = {
   inputTokens: number;
   outputTokens: number;
   cacheCreationTokens: number;
   cacheReadTokens: number;
-  totalTokens: number;
+};
+type TokenTotals = TokenData & {
   totalCost: number;
 };
+type TotalsObject = TokenTotals & {
+  totalTokens: number;
+};
+declare function calculateTotals(data: Array<DailyUsage | MonthlyUsage | SessionUsage>): TokenTotals;
+declare function getTotalTokens(tokens: TokenData): number;
+declare function createTotalsObject(totals: TokenTotals): TotalsObject;
 //#endregion
 export { calculateTotals, createTotalsObject, getTotalTokens };

package/dist/{core-BgFXUe_h.js → core-B0ovMhJe.js}

@@ -38,8 +38,8 @@ const $output = Symbol("ZodOutput");
 const $input = Symbol("ZodInput");
 var $ZodRegistry = class {
 	constructor() {
-		this._map = new WeakMap();
-		this._idmap = new Map();
+		this._map = /* @__PURE__ */ new WeakMap();
+		this._idmap = /* @__PURE__ */ new Map();
 	}
 	add(schema, ..._meta) {
 		const meta = _meta[0];
@@ -85,7 +85,7 @@ var JSONSchemaGenerator = class {
 		this.unrepresentable = params?.unrepresentable ?? "throw";
 		this.override = params?.override ?? (() => {});
 		this.io = params?.io ?? "output";
-		this.seen = new Map();
+		this.seen = /* @__PURE__ */ new Map();
 	}
 	process(schema, _params = {
 		path: [],
@@ -630,7 +630,7 @@ function toJSONSchema(input, _params) {
 	return gen.emit(input, _params);
 }
 function isTransforming(_schema, _ctx) {
-	const ctx = _ctx ?? { seen: new Set() };
+	const ctx = _ctx ?? { seen: /* @__PURE__ */ new Set() };
 	if (ctx.seen.has(_schema)) return false;
 	ctx.seen.add(_schema);
 	const schema = _schema;

package/dist/{data-loader-r5ZcMQy7.js → data-loader-DP5qBPn6.js}

@@ -1,5 +1,5 @@
-import { array, number, object, optional, safeParse, string } from "./dist-FwNhpFrW.js";
-import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-B5yPtoTB.js";
+import { array, number, object, optional, pipe, regex, safeParse, string } from "./dist-C0-Tf5eD.js";
+import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-BPUgMrB_.js";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -575,7 +575,7 @@ var require_walker = __commonJS({ "node_modules/fdir/dist/api/walker.js"(exports
 				counts: new counter_1.Counter(),
 				options,
 				queue: new queue_1.Queue((error, state) => this.callbackInvoker(state, error, callback$1)),
-				symlinks: new Map(),
+				symlinks: /* @__PURE__ */ new Map(),
 				visited: [""].slice(0, 0),
 				controller: new AbortController()
 			};
@@ -2110,9 +2110,9 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 		if (glob$1 === "" || typeof glob$1 !== "string" && !isState) throw new TypeError("Expected pattern to be a non-empty string");
 		const opts = options || {};
 		const posix$1 = opts.windows;
-		const regex = isState ? picomatch$2.compileRe(glob$1, options) : picomatch$2.makeRe(glob$1, options, false, true);
-		const state = regex.state;
-		delete regex.state;
+		const regex$1 = isState ? picomatch$2.compileRe(glob$1, options) : picomatch$2.makeRe(glob$1, options, false, true);
+		const state = regex$1.state;
+		delete regex$1.state;
 		let isIgnored = () => false;
 		if (opts.ignore) {
 			const ignoreOpts = {
@@ -2124,14 +2124,14 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 			isIgnored = picomatch$2(opts.ignore, ignoreOpts, returnState);
 		}
 		const matcher = (input, returnObject = false) => {
-			const { isMatch, match, output } = picomatch$2.test(input, regex, options, {
+			const { isMatch, match, output } = picomatch$2.test(input, regex$1, options, {
 				glob: glob$1,
 				posix: posix$1
 			});
 			const result = {
 				glob: glob$1,
 				state,
-				regex,
+				regex: regex$1,
 				posix: posix$1,
 				input,
 				output,
@@ -2170,7 +2170,7 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 	* @return {Object} Returns an object with matching info.
 	* @api public
 	*/
-	picomatch$2.test = (input, regex, options, { glob: glob$1, posix: posix$1 } = {}) => {
+	picomatch$2.test = (input, regex$1, options, { glob: glob$1, posix: posix$1 } = {}) => {
 		if (typeof input !== "string") throw new TypeError("Expected input to be a string");
 		if (input === "") return {
 			isMatch: false,
@@ -2184,8 +2184,8 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 			output = format ? format(input) : input;
 			match = output === glob$1;
 		}
-		if (match === false || opts.capture === true) if (opts.matchBase === true || opts.basename === true) match = picomatch$2.matchBase(input, regex, options, posix$1);
-		else match = regex.exec(output);
+		if (match === false || opts.capture === true) if (opts.matchBase === true || opts.basename === true) match = picomatch$2.matchBase(input, regex$1, options, posix$1);
+		else match = regex$1.exec(output);
 		return {
 			isMatch: Boolean(match),
 			match,
@@ -2206,8 +2206,8 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 	* @api public
 	*/
 	picomatch$2.matchBase = (input, glob$1, options) => {
-		const regex = glob$1 instanceof RegExp ? glob$1 : picomatch$2.makeRe(glob$1, options);
-		return regex.test(utils$1.basename(input));
+		const regex$1 = glob$1 instanceof RegExp ? glob$1 : picomatch$2.makeRe(glob$1, options);
+		return regex$1.test(utils$1.basename(input));
 	};
 	/**
 	* Returns true if **any** of the given glob `patterns` match the specified `string`.
@@ -2291,9 +2291,9 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 		const append = opts.contains ? "" : "$";
 		let source = `${prepend}(?:${state.output})${append}`;
 		if (state && state.negated === true) source = `^(?!${source}).*$`;
-		const regex = picomatch$2.toRegex(source, options);
-		if (returnState === true) regex.state = state;
-		return regex;
+		const regex$1 = picomatch$2.toRegex(source, options);
+		if (returnState === true) regex$1.state = state;
+		return regex$1;
 	};
 	/**
 	* Create a regular expression from a parsed glob pattern.
@@ -2573,14 +2573,14 @@ function getPartialMatcher(patterns, options) {
 		if (inputParts[0] === ".." && ONLY_PARENT_DIRECTORIES.test(input)) return true;
 		for (let i = 0; i < patterns.length; i++) {
 			const patternParts = patternsParts[i];
-			const regex = regexes[i];
+			const regex$1 = regexes[i];
 			const inputPatternCount = inputParts.length;
 			const minParts = Math.min(inputPatternCount, patternParts.length);
 			let j = 0;
 			while (j < minParts) {
 				const part = patternParts[j];
 				if (part.includes("/")) return true;
-				const match = regex[j].test(inputParts[j]);
+				const match = regex$1[j].test(inputParts[j]);
 				if (!match) break;
 				if (part === "**") return true;
 				j++;
@@ -2608,7 +2608,7 @@ function isDynamicPattern(pattern, options) {
 	return scan$2.isGlob || scan$2.negated;
 }
 function log(...tasks) {
-	console.log(`[tinyglobby ${new Date().toLocaleTimeString("es")}]`, ...tasks);
+	console.log(`[tinyglobby ${(/* @__PURE__ */ new Date()).toLocaleTimeString("es")}]`, ...tasks);
 }
 const PARENT_DIRECTORY = /^(\/?\.\.)+/;
 const ESCAPING_BACKSLASHES = /\\(?=[()[\]{}!*+?@|])/g;
@@ -2770,7 +2770,9 @@ async function glob(patternsOrOptions, options) {
 
 //#endregion
 //#region src/data-loader.ts
-const getDefaultClaudePath = () => path.join(homedir(), ".claude");
+function getDefaultClaudePath() {
+	return path.join(homedir(), ".claude");
+}
 const UsageDataSchema = object({
 	timestamp: string(),
 	version: optional(string()),
@@ -2786,7 +2788,7 @@ const UsageDataSchema = object({
 	costUSD: optional(number())
 });
 const DailyUsageSchema = object({
-	date: string(),
+	date: pipe(string(), regex(/^\d{4}-\d{2}-\d{2}$/)),
 	inputTokens: number(),
 	outputTokens: number(),
 	cacheCreationTokens: number(),
@@ -2804,30 +2806,38 @@ const SessionUsageSchema = object({
 	lastActivity: string(),
 	versions: array(string())
 });
-const formatDate = (dateStr) => {
+const MonthlyUsageSchema = object({
+	month: pipe(string(), regex(/^\d{4}-\d{2}$/)),
+	inputTokens: number(),
+	outputTokens: number(),
+	cacheCreationTokens: number(),
+	cacheReadTokens: number(),
+	totalCost: number()
+});
+function formatDate(dateStr) {
 	const date = new Date(dateStr);
 	const year = date.getFullYear();
 	const month = String(date.getMonth() + 1).padStart(2, "0");
 	const day = String(date.getDate()).padStart(2, "0");
 	return `${year}-${month}-${day}`;
-};
-const calculateCostForEntry = (data, mode, modelPricing) => {
+}
+function calculateCostForEntry(data, mode, modelPricing) {
 	if (mode === "display") return data.costUSD ?? 0;
 	if (mode === "calculate") {
-		if (data.message.model) {
+		if (data.message.model != null) {
 			const pricing = getModelPricing(data.message.model, modelPricing);
-			if (pricing) return calculateCostFromTokens(data.message.usage, pricing);
+			if (pricing != null) return calculateCostFromTokens(data.message.usage, pricing);
 		}
 		return 0;
 	}
-	if (data.costUSD !== void 0) return data.costUSD;
-	if (data.message.model) {
+	if (data.costUSD != null) return data.costUSD;
+	if (data.message.model != null) {
 		const pricing = getModelPricing(data.message.model, modelPricing);
-		if (pricing) return calculateCostFromTokens(data.message.usage, pricing);
+		if (pricing != null) return calculateCostFromTokens(data.message.usage, pricing);
 	}
 	return 0;
-};
-async function loadUsageData(options) {
+}
+async function loadDailyUsageData(options) {
 	const claudePath = options?.claudePath ?? getDefaultClaudePath();
 	const claudeDir = path.join(claudePath, "projects");
 	const files = await glob(["**/*.jsonl"], {
@@ -2835,9 +2845,9 @@ async function loadUsageData(options) {
 		absolute: true
 	});
 	if (files.length === 0) return [];
-	const mode = options?.mode || "auto";
+	const mode = options?.mode ?? "auto";
 	const modelPricing = mode === "display" ? {} : await fetchModelPricing();
-	const dailyMap = new Map();
+	const allEntries = [];
 	for (const file of files) {
 		const content = await readFile(file, "utf-8");
 		const lines = content.trim().split("\n").filter((line) => line.length > 0);
@@ -2847,31 +2857,43 @@ async function loadUsageData(options) {
 			if (!result.success) continue;
 			const data = result.output;
 			const date = formatDate(data.timestamp);
-			const existing = dailyMap.get(date) || {
-				date,
-				inputTokens: 0,
-				outputTokens: 0,
-				cacheCreationTokens: 0,
-				cacheReadTokens: 0,
-				totalCost: 0
-			};
-			existing.inputTokens += data.message.usage.input_tokens ?? 0;
-			existing.outputTokens += data.message.usage.output_tokens ?? 0;
-			existing.cacheCreationTokens += data.message.usage.cache_creation_input_tokens ?? 0;
-			existing.cacheReadTokens += data.message.usage.cache_read_input_tokens ?? 0;
 			const cost = calculateCostForEntry(data, mode, modelPricing);
-			existing.totalCost += cost;
-			dailyMap.set(date, existing);
-		} catch (e) {}
+			allEntries.push({
+				data,
+				date,
+				cost
+			});
+		} catch {}
 	}
-	let results = Array.from(dailyMap.values());
-	if (options?.since || options?.until) results = results.filter((data) => {
-		const dateStr = data.date.replace(/-/g, "");
-		if (options.since && dateStr < options.since) return false;
-		if (options.until && dateStr > options.until) return false;
+	const groupedByDate = Object.groupBy(allEntries, (entry) => entry.date);
+	const results = Object.entries(groupedByDate).map(([date, entries]) => {
+		if (entries == null) return void 0;
+		return entries.reduce((acc, entry) => ({
+			date,
+			inputTokens: acc.inputTokens + (entry.data.message.usage.input_tokens ?? 0),
+			outputTokens: acc.outputTokens + (entry.data.message.usage.output_tokens ?? 0),
+			cacheCreationTokens: acc.cacheCreationTokens + (entry.data.message.usage.cache_creation_input_tokens ?? 0),
+			cacheReadTokens: acc.cacheReadTokens + (entry.data.message.usage.cache_read_input_tokens ?? 0),
+			totalCost: acc.totalCost + entry.cost
+		}), {
+			date,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheCreationTokens: 0,
+			cacheReadTokens: 0,
+			totalCost: 0
+		});
+	}).filter((item) => item != null).filter((item) => {
+		if (options?.since != null || options?.until != null) {
+			const dateStr = item.date.replace(/-/g, "");
+			if (options.since != null && dateStr < options.since) return false;
+			if (options.until != null && dateStr > options.until) return false;
+		}
 		return true;
 	});
-	return sort(results).desc((item) => new Date(item.date).getTime());
+	const sortOrder = options?.order ?? "desc";
+	const sortedResults = sort(results);
+	return sortOrder === "desc" ? sortedResults.desc((item) => new Date(item.date).getTime()) : sortedResults.asc((item) => new Date(item.date).getTime());
 }
 async function loadSessionData(options) {
 	const claudePath = options?.claudePath ?? getDefaultClaudePath();
@@ -2881,64 +2903,99 @@ async function loadSessionData(options) {
 		absolute: true
 	});
 	if (files.length === 0) return [];
-	const mode = options?.mode || "auto";
+	const mode = options?.mode ?? "auto";
 	const modelPricing = mode === "display" ? {} : await fetchModelPricing();
-	const sessionMap = new Map();
+	const allEntries = [];
 	for (const file of files) {
 		const relativePath = path.relative(claudeDir, file);
 		const parts = relativePath.split(path.sep);
-		const sessionId = parts[parts.length - 2];
-		const projectPath = parts.slice(0, -2).join(path.sep);
+		const sessionId = parts[parts.length - 2] ?? "unknown";
+		const joinedPath = parts.slice(0, -2).join(path.sep);
+		const projectPath = joinedPath.length > 0 ? joinedPath : "Unknown Project";
 		const content = await readFile(file, "utf-8");
 		const lines = content.trim().split("\n").filter((line) => line.length > 0);
-		let lastTimestamp = "";
 		for (const line of lines) try {
 			const parsed = JSON.parse(line);
 			const result = safeParse(UsageDataSchema, parsed);
 			if (!result.success) continue;
 			const data = result.output;
-			const key = `${projectPath}/${sessionId}`;
-			const existing = sessionMap.get(key) || {
-				sessionId: sessionId || "unknown",
-				projectPath: projectPath || "Unknown Project",
-				inputTokens: 0,
-				outputTokens: 0,
-				cacheCreationTokens: 0,
-				cacheReadTokens: 0,
-				totalCost: 0,
-				lastActivity: "",
-				versions: [],
-				versionSet: new Set()
-			};
-			existing.inputTokens += data.message.usage.input_tokens ?? 0;
-			existing.outputTokens += data.message.usage.output_tokens ?? 0;
-			existing.cacheCreationTokens += data.message.usage.cache_creation_input_tokens ?? 0;
-			existing.cacheReadTokens += data.message.usage.cache_read_input_tokens ?? 0;
+			const sessionKey = `${projectPath}/${sessionId}`;
 			const cost = calculateCostForEntry(data, mode, modelPricing);
-			existing.totalCost += cost;
-			if (data.timestamp > lastTimestamp) {
-				lastTimestamp = data.timestamp;
-				existing.lastActivity = formatDate(data.timestamp);
-			}
-			if (data.version) existing.versionSet.add(data.version);
-			sessionMap.set(key, existing);
-		} catch (e) {}
+			allEntries.push({
+				data,
+				sessionKey,
+				sessionId,
+				projectPath,
+				cost,
+				timestamp: data.timestamp
+			});
+		} catch {}
 	}
-	let results = Array.from(sessionMap.values()).map((session) => {
-		const { versionSet,...sessionData } = session;
-		return {
-			...sessionData,
+	const groupedBySessions = Object.groupBy(allEntries, (entry) => entry.sessionKey);
+	const results = Object.entries(groupedBySessions).map(([_, entries]) => {
+		if (entries == null) return void 0;
+		const latestEntry = entries.reduce((latest, current) => current.timestamp > latest.timestamp ? current : latest);
+		const versionSet = /* @__PURE__ */ new Set();
+		for (const entry of entries) if (entry.data.version != null) versionSet.add(entry.data.version);
+		const aggregated = entries.reduce((acc, entry) => ({
+			sessionId: latestEntry.sessionId,
+			projectPath: latestEntry.projectPath,
+			inputTokens: acc.inputTokens + (entry.data.message.usage.input_tokens ?? 0),
+			outputTokens: acc.outputTokens + (entry.data.message.usage.output_tokens ?? 0),
+			cacheCreationTokens: acc.cacheCreationTokens + (entry.data.message.usage.cache_creation_input_tokens ?? 0),
+			cacheReadTokens: acc.cacheReadTokens + (entry.data.message.usage.cache_read_input_tokens ?? 0),
+			totalCost: acc.totalCost + entry.cost,
+			lastActivity: formatDate(latestEntry.timestamp),
 			versions: Array.from(versionSet).sort()
-		};
-	});
-	if (options?.since || options?.until) results = results.filter((session) => {
-		const dateStr = session.lastActivity.replace(/-/g, "");
-		if (options.since && dateStr < options.since) return false;
-		if (options.until && dateStr > options.until) return false;
+		}), {
+			sessionId: latestEntry.sessionId,
+			projectPath: latestEntry.projectPath,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheCreationTokens: 0,
+			cacheReadTokens: 0,
+			totalCost: 0,
+			lastActivity: formatDate(latestEntry.timestamp),
+			versions: Array.from(versionSet).sort()
+		});
+		return aggregated;
+	}).filter((item) => item != null).filter((item) => {
+		if (options?.since != null || options?.until != null) {
+			const dateStr = item.lastActivity.replace(/-/g, "");
+			if (options.since != null && dateStr < options.since) return false;
+			if (options.until != null && dateStr > options.until) return false;
+		}
 		return true;
 	});
-	return sort(results).desc((item) => new Date(item.lastActivity).getTime());
+	const sortOrder = options?.order ?? "desc";
+	const sortedResults = sort(results);
+	return sortOrder === "desc" ? sortedResults.desc((item) => new Date(item.lastActivity).getTime()) : sortedResults.asc((item) => new Date(item.lastActivity).getTime());
+}
+async function loadMonthlyUsageData(options) {
+	const dailyData = await loadDailyUsageData(options);
+	const groupedByMonth = Object.groupBy(dailyData, (data) => data.date.substring(0, 7));
+	const monthlyArray = Object.entries(groupedByMonth).map(([month, dailyEntries]) => {
+		if (dailyEntries == null) return void 0;
+		return dailyEntries.reduce((acc, data) => ({
+			month,
+			inputTokens: acc.inputTokens + data.inputTokens,
+			outputTokens: acc.outputTokens + data.outputTokens,
+			cacheCreationTokens: acc.cacheCreationTokens + data.cacheCreationTokens,
+			cacheReadTokens: acc.cacheReadTokens + data.cacheReadTokens,
+			totalCost: acc.totalCost + data.totalCost
+		}), {
+			month,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheCreationTokens: 0,
+			cacheReadTokens: 0,
+			totalCost: 0
+		});
+	}).filter((item) => item != null);
+	const sortOrder = options?.order ?? "desc";
+	const sortedMonthly = sort(monthlyArray);
+	return sortOrder === "desc" ? sortedMonthly.desc((item) => item.month) : sortedMonthly.asc((item) => item.month);
 }
 
 //#endregion
-export { DailyUsageSchema, SessionUsageSchema, UsageDataSchema, __commonJS, __require, __toESM, calculateCostForEntry, formatDate, getDefaultClaudePath, glob, loadSessionData, loadUsageData };
+export { DailyUsageSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, __commonJS, __require, __toESM, calculateCostForEntry, formatDate, getDefaultClaudePath, glob, loadDailyUsageData, loadMonthlyUsageData, loadSessionData };