Skip to content

Commit 5280b29

Browse files
jzlikeweiclaude
authored andcommitted
feat(ccusage): add --human/-H flag for human-readable token display
Add support for displaying token counts with K/M/B suffixes (e.g., 1.23M instead of 1,234,567). Numbers below 1K are kept as-is. Defaults to 2 decimal places. Available in daily, monthly, weekly, session, and blocks commands. Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent 2d4222c commit 5280b29

7 files changed

Lines changed: 125 additions & 1 deletion

File tree

‎apps/ccusage/src/_shared-args.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,12 @@ export const sharedArgs = {
110110
description: 'Force compact mode for narrow displays (better for screenshots)',
111111
default: false,
112112
},
113+
human: {
114+
type: 'boolean',
115+
short: 'H',
116+
description: 'Display token counts in human-readable format (K/M/B suffixes)',
117+
default: false,
118+
},
113119
} as const satisfies Args;
114120

115121
/**

‎apps/ccusage/src/commands/blocks.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
formatModelsDisplayMultiline,
66
formatNumber,
77
ResponsiveTable,
8+
setHumanReadableNumbers,
89
} from '@ccusage/terminal/table';
910
import { Result } from '@praha/byethrow';
1011
import { define } from 'gunshi';
@@ -278,6 +279,11 @@ export const blocksCommand = define({
278279
log(JSON.stringify(jsonOutput, null, 2));
279280
}
280281
} else {
282+
// Enable human-readable numbers if requested
283+
if (mergedOptions.human) {
284+
setHumanReadableNumbers(true);
285+
}
286+
281287
// Table output
282288
if (ctx.values.active && blocks.length === 1) {
283289
// Detailed active block view

‎apps/ccusage/src/commands/daily.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
formatTotalsRow,
77
formatUsageDataRow,
88
pushBreakdownRows,
9+
setHumanReadableNumbers,
910
} from '@ccusage/terminal/table';
1011
import { Result } from '@praha/byethrow';
1112
import { define } from 'gunshi';
@@ -134,6 +135,11 @@ export const dailyCommand = define({
134135
log(JSON.stringify(jsonOutput, null, 2));
135136
}
136137
} else {
138+
// Enable human-readable numbers if requested
139+
if (mergedOptions.human) {
140+
setHumanReadableNumbers(true);
141+
}
142+
137143
// Print header
138144
logger.box('Claude Code Token Usage Report - Daily');
139145

‎apps/ccusage/src/commands/monthly.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
formatTotalsRow,
77
formatUsageDataRow,
88
pushBreakdownRows,
9+
setHumanReadableNumbers,
910
} from '@ccusage/terminal/table';
1011
import { Result } from '@praha/byethrow';
1112
import { define } from 'gunshi';
@@ -94,6 +95,11 @@ export const monthlyCommand = define({
9495
log(JSON.stringify(jsonOutput, null, 2));
9596
}
9697
} else {
98+
// Enable human-readable numbers if requested
99+
if (mergedOptions.human) {
100+
setHumanReadableNumbers(true);
101+
}
102+
97103
// Print header
98104
logger.box('Claude Code Token Usage Report - Monthly');
99105

‎apps/ccusage/src/commands/session.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
formatTotalsRow,
77
formatUsageDataRow,
88
pushBreakdownRows,
9+
setHumanReadableNumbers,
910
} from '@ccusage/terminal/table';
1011
import { Result } from '@praha/byethrow';
1112
import { define } from 'gunshi';
@@ -47,6 +48,11 @@ export const sessionCommand = define({
4748
logger.level = 0;
4849
}
4950

51+
// Enable human-readable numbers if requested (before any output)
52+
if (mergedOptions.human) {
53+
setHumanReadableNumbers(true);
54+
}
55+
5056
// Handle specific session ID lookup
5157
if (mergedOptions.id != null) {
5258
return handleSessionIdLookup(

‎apps/ccusage/src/commands/weekly.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
formatTotalsRow,
77
formatUsageDataRow,
88
pushBreakdownRows,
9+
setHumanReadableNumbers,
910
} from '@ccusage/terminal/table';
1011
import { Result } from '@praha/byethrow';
1112
import { define } from 'gunshi';
@@ -104,6 +105,11 @@ export const weeklyCommand = define({
104105
log(JSON.stringify(jsonOutput, null, 2));
105106
}
106107
} else {
108+
// Enable human-readable numbers if requested
109+
if (mergedOptions.human) {
110+
setHumanReadableNumbers(true);
111+
}
112+
107113
// Print header
108114
logger.box('Claude Code Token Usage Report - Weekly');
109115

‎packages/terminal/src/table.ts‎

Lines changed: 89 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,12 +351,48 @@ export class ResponsiveTable {
351351
}
352352
}
353353

354+
let _humanReadable = false;
355+
356+
/**
357+
* Enables or disables human-readable number formatting (K/M/B suffixes)
358+
* @param human - Whether to use human-readable format
359+
*/
360+
export function setHumanReadableNumbers(human: boolean): void {
361+
_humanReadable = human;
362+
}
363+
364+
/**
365+
* Formats a number with human-readable suffixes (K, M, B)
366+
* Numbers below 1000 are displayed as-is with locale formatting
367+
* @param num - The number to format
368+
* @returns Formatted string with suffix (e.g., "1.23M", "456K")
369+
*/
370+
export function formatNumberHuman(num: number): string {
371+
const absNum = Math.abs(num);
372+
const sign = num < 0 ? '-' : '';
373+
374+
if (absNum >= 1_000_000_000) {
375+
return `${sign}${(absNum / 1_000_000_000).toFixed(2)}B`;
376+
}
377+
if (absNum >= 1_000_000) {
378+
return `${sign}${(absNum / 1_000_000).toFixed(2)}M`;
379+
}
380+
if (absNum >= 1_000) {
381+
return `${sign}${(absNum / 1_000).toFixed(2)}K`;
382+
}
383+
return num.toLocaleString('en-US');
384+
}
385+
354386
/**
355387
* Formats a number with locale-specific thousand separators
388+
* When human-readable mode is enabled, uses K/M/B suffixes instead
356389
* @param num - The number to format
357-
* @returns Formatted number string with commas as thousand separators
390+
* @returns Formatted number string
358391
*/
359392
export function formatNumber(num: number): string {
393+
if (_humanReadable) {
394+
return formatNumberHuman(num);
395+
}
360396
return num.toLocaleString('en-US');
361397
}
362398

@@ -984,6 +1020,58 @@ if (import.meta.vitest != null) {
9841020
});
9851021
});
9861022

1023+
describe('formatNumberHuman', () => {
1024+
it('formats billions', () => {
1025+
expect(formatNumberHuman(1_000_000_000)).toBe('1.00B');
1026+
expect(formatNumberHuman(2_500_000_000)).toBe('2.50B');
1027+
expect(formatNumberHuman(1_234_567_890)).toBe('1.23B');
1028+
});
1029+
1030+
it('formats millions', () => {
1031+
expect(formatNumberHuman(1_000_000)).toBe('1.00M');
1032+
expect(formatNumberHuman(1_500_000)).toBe('1.50M');
1033+
expect(formatNumberHuman(12_345_678)).toBe('12.35M');
1034+
});
1035+
1036+
it('formats thousands', () => {
1037+
expect(formatNumberHuman(1_000)).toBe('1.00K');
1038+
expect(formatNumberHuman(1_500)).toBe('1.50K');
1039+
expect(formatNumberHuman(999_999)).toBe('1000.00K');
1040+
});
1041+
1042+
it('keeps numbers below 1000 as-is', () => {
1043+
expect(formatNumberHuman(0)).toBe('0');
1044+
expect(formatNumberHuman(1)).toBe('1');
1045+
expect(formatNumberHuman(999)).toBe('999');
1046+
expect(formatNumberHuman(500)).toBe('500');
1047+
});
1048+
1049+
it('handles negative numbers', () => {
1050+
expect(formatNumberHuman(-1_500_000)).toBe('-1.50M');
1051+
expect(formatNumberHuman(-2_500)).toBe('-2.50K');
1052+
expect(formatNumberHuman(-500)).toBe('-500');
1053+
});
1054+
});
1055+
1056+
describe('setHumanReadableNumbers', () => {
1057+
afterEach(() => {
1058+
setHumanReadableNumbers(false);
1059+
});
1060+
1061+
it('formatNumber uses human-readable format when enabled', () => {
1062+
setHumanReadableNumbers(true);
1063+
expect(formatNumber(1_500_000)).toBe('1.50M');
1064+
expect(formatNumber(2_500)).toBe('2.50K');
1065+
expect(formatNumber(500)).toBe('500');
1066+
});
1067+
1068+
it('formatNumber uses default format when disabled', () => {
1069+
setHumanReadableNumbers(false);
1070+
expect(formatNumber(1_500_000)).toBe('1,500,000');
1071+
expect(formatNumber(2_500)).toBe('2,500');
1072+
});
1073+
});
1074+
9871075
describe('formatCurrency', () => {
9881076
it('formats positive amounts', () => {
9891077
expect(formatCurrency(10)).toBe('$10.00');

0 commit comments

Comments
 (0)