Skip to content

Commit 7ae1aec

Browse files
jay-tauCopilot
andcommitted
feat: add --human/-H flag for human-readable token display
Add a --human / -H CLI flag to all report commands across all apps (ccusage, codex, opencode, amp, pi) that displays token counts with K/M/B suffixes (e.g., 1.23M instead of 1,234,567). Implementation details: - Add formatNumberHuman() using Intl.NumberFormat compact notation - Extend formatNumber() with optional humanReadable parameter - Thread humanReadable through formatUsageDataRow, formatTotalsRow, pushBreakdownRows and all direct formatNumber callsites - JSON output remains unchanged (raw numbers always) - Add comprehensive in-source tests for the new formatter Closes ccusage#958 Co-authored-by: Copilot <[email protected]>
1 parent 9f4129c commit 7ae1aec

22 files changed

Lines changed: 477 additions & 249 deletions

File tree

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

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,15 @@ export const dailyCommand = define({
4141
type: 'boolean',
4242
description: 'Force compact table mode',
4343
},
44+
human: {
45+
type: 'boolean',
46+
short: 'H',
47+
description: 'Display token counts in human-readable format (K/M/B suffixes)',
48+
},
4449
},
4550
async run(ctx) {
4651
const jsonOutput = Boolean(ctx.values.json);
52+
const humanReadable = Boolean(ctx.values.human);
4753

4854
const { events } = await loadAmpUsageEvents();
4955

@@ -168,11 +174,11 @@ export const dailyCommand = define({
168174
table.push([
169175
data.date,
170176
formatModelsDisplayMultiline(data.modelsUsed),
171-
formatNumber(data.inputTokens),
172-
formatNumber(data.outputTokens),
173-
formatNumber(data.cacheCreationTokens),
174-
formatNumber(data.cacheReadTokens),
175-
formatNumber(data.totalTokens),
177+
formatNumber(data.inputTokens, humanReadable),
178+
formatNumber(data.outputTokens, humanReadable),
179+
formatNumber(data.cacheCreationTokens, humanReadable),
180+
formatNumber(data.cacheReadTokens, humanReadable),
181+
formatNumber(data.totalTokens, humanReadable),
176182
data.credits.toFixed(2),
177183
formatCurrency(data.totalCost),
178184
]);
@@ -182,11 +188,11 @@ export const dailyCommand = define({
182188
table.push([
183189
pc.yellow('Total'),
184190
'',
185-
pc.yellow(formatNumber(totals.inputTokens)),
186-
pc.yellow(formatNumber(totals.outputTokens)),
187-
pc.yellow(formatNumber(totals.cacheCreationTokens)),
188-
pc.yellow(formatNumber(totals.cacheReadTokens)),
189-
pc.yellow(formatNumber(totals.totalTokens)),
191+
pc.yellow(formatNumber(totals.inputTokens, humanReadable)),
192+
pc.yellow(formatNumber(totals.outputTokens, humanReadable)),
193+
pc.yellow(formatNumber(totals.cacheCreationTokens, humanReadable)),
194+
pc.yellow(formatNumber(totals.cacheReadTokens, humanReadable)),
195+
pc.yellow(formatNumber(totals.totalTokens, humanReadable)),
190196
pc.yellow(totals.credits.toFixed(2)),
191197
pc.yellow(formatCurrency(totals.totalCost)),
192198
]);

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

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,15 @@ export const monthlyCommand = define({
4141
type: 'boolean',
4242
description: 'Force compact table mode',
4343
},
44+
human: {
45+
type: 'boolean',
46+
short: 'H',
47+
description: 'Display token counts in human-readable format (K/M/B suffixes)',
48+
},
4449
},
4550
async run(ctx) {
4651
const jsonOutput = Boolean(ctx.values.json);
52+
const humanReadable = Boolean(ctx.values.human);
4753

4854
const { events } = await loadAmpUsageEvents();
4955

@@ -168,11 +174,11 @@ export const monthlyCommand = define({
168174
table.push([
169175
data.month,
170176
formatModelsDisplayMultiline(data.modelsUsed),
171-
formatNumber(data.inputTokens),
172-
formatNumber(data.outputTokens),
173-
formatNumber(data.cacheCreationTokens),
174-
formatNumber(data.cacheReadTokens),
175-
formatNumber(data.totalTokens),
177+
formatNumber(data.inputTokens, humanReadable),
178+
formatNumber(data.outputTokens, humanReadable),
179+
formatNumber(data.cacheCreationTokens, humanReadable),
180+
formatNumber(data.cacheReadTokens, humanReadable),
181+
formatNumber(data.totalTokens, humanReadable),
176182
data.credits.toFixed(2),
177183
formatCurrency(data.totalCost),
178184
]);
@@ -182,11 +188,11 @@ export const monthlyCommand = define({
182188
table.push([
183189
pc.yellow('Total'),
184190
'',
185-
pc.yellow(formatNumber(totals.inputTokens)),
186-
pc.yellow(formatNumber(totals.outputTokens)),
187-
pc.yellow(formatNumber(totals.cacheCreationTokens)),
188-
pc.yellow(formatNumber(totals.cacheReadTokens)),
189-
pc.yellow(formatNumber(totals.totalTokens)),
191+
pc.yellow(formatNumber(totals.inputTokens, humanReadable)),
192+
pc.yellow(formatNumber(totals.outputTokens, humanReadable)),
193+
pc.yellow(formatNumber(totals.cacheCreationTokens, humanReadable)),
194+
pc.yellow(formatNumber(totals.cacheReadTokens, humanReadable)),
195+
pc.yellow(formatNumber(totals.totalTokens, humanReadable)),
190196
pc.yellow(totals.credits.toFixed(2)),
191197
pc.yellow(formatCurrency(totals.totalCost)),
192198
]);

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

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,15 @@ export const sessionCommand = define({
4040
type: 'boolean',
4141
description: 'Force compact table mode',
4242
},
43+
human: {
44+
type: 'boolean',
45+
short: 'H',
46+
description: 'Display token counts in human-readable format (K/M/B suffixes)',
47+
},
4348
},
4449
async run(ctx) {
4550
const jsonOutput = Boolean(ctx.values.json);
51+
const humanReadable = Boolean(ctx.values.human);
4652

4753
const { events, threads } = await loadAmpUsageEvents();
4854

@@ -180,11 +186,11 @@ export const sessionCommand = define({
180186
table.push([
181187
displayTitle,
182188
formatModelsDisplayMultiline(data.modelsUsed),
183-
formatNumber(data.inputTokens),
184-
formatNumber(data.outputTokens),
185-
formatNumber(data.cacheCreationTokens),
186-
formatNumber(data.cacheReadTokens),
187-
formatNumber(data.totalTokens),
189+
formatNumber(data.inputTokens, humanReadable),
190+
formatNumber(data.outputTokens, humanReadable),
191+
formatNumber(data.cacheCreationTokens, humanReadable),
192+
formatNumber(data.cacheReadTokens, humanReadable),
193+
formatNumber(data.totalTokens, humanReadable),
188194
data.credits.toFixed(2),
189195
formatCurrency(data.totalCost),
190196
]);
@@ -194,11 +200,11 @@ export const sessionCommand = define({
194200
table.push([
195201
pc.yellow('Total'),
196202
'',
197-
pc.yellow(formatNumber(totals.inputTokens)),
198-
pc.yellow(formatNumber(totals.outputTokens)),
199-
pc.yellow(formatNumber(totals.cacheCreationTokens)),
200-
pc.yellow(formatNumber(totals.cacheReadTokens)),
201-
pc.yellow(formatNumber(totals.totalTokens)),
203+
pc.yellow(formatNumber(totals.inputTokens, humanReadable)),
204+
pc.yellow(formatNumber(totals.outputTokens, humanReadable)),
205+
pc.yellow(formatNumber(totals.cacheCreationTokens, humanReadable)),
206+
pc.yellow(formatNumber(totals.cacheReadTokens, humanReadable)),
207+
pc.yellow(formatNumber(totals.totalTokens, humanReadable)),
202208
pc.yellow(totals.credits.toFixed(2)),
203209
pc.yellow(formatCurrency(totals.totalCost)),
204210
]);

‎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/_session_id.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ export type SessionIdContext = {
2525
export async function handleSessionIdLookup(
2626
ctx: SessionIdContext,
2727
useJson: boolean,
28+
humanReadable = false,
2829
): Promise<void> {
2930
const sessionUsage = await loadSessionUsageById(ctx.values.id, {
3031
mode: ctx.values.mode,
@@ -72,7 +73,7 @@ export async function handleSessionIdLookup(
7273
const totalTokens = calculateSessionTotalTokens(sessionUsage.entries);
7374

7475
log(`Total Cost: ${formatCurrency(sessionUsage.totalCost)}`);
75-
log(`Total Tokens: ${formatNumber(totalTokens)}`);
76+
log(`Total Tokens: ${formatNumber(totalTokens, humanReadable)}`);
7677
log(`Total Entries: ${sessionUsage.entries.length}`);
7778
log('');
7879

@@ -87,10 +88,10 @@ export async function handleSessionIdLookup(
8788
table.push([
8889
formatDateCompact(entry.timestamp, ctx.values.timezone, ctx.values.locale),
8990
entry.message.model ?? 'unknown',
90-
formatNumber(entry.message.usage.input_tokens),
91-
formatNumber(entry.message.usage.output_tokens),
92-
formatNumber(entry.message.usage.cache_creation_input_tokens ?? 0),
93-
formatNumber(entry.message.usage.cache_read_input_tokens ?? 0),
91+
formatNumber(entry.message.usage.input_tokens, humanReadable),
92+
formatNumber(entry.message.usage.output_tokens, humanReadable),
93+
formatNumber(entry.message.usage.cache_creation_input_tokens ?? 0, humanReadable),
94+
formatNumber(entry.message.usage.cache_read_input_tokens ?? 0, humanReadable),
9495
formatCurrency(entry.costUSD ?? 0),
9596
]);
9697
}

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

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ export const blocksCommand = define({
154154

155155
// --jq implies --json
156156
const useJson = mergedOptions.json || mergedOptions.jq != null;
157+
const humanReadable = Boolean(mergedOptions.human);
157158
if (useJson) {
158159
logger.level = 0;
159160
}
@@ -200,7 +201,9 @@ export const blocksCommand = define({
200201
}
201202
}
202203
if (!useJson && maxTokensFromAll > 0) {
203-
logger.info(`Using max tokens from previous sessions: ${formatNumber(maxTokensFromAll)}`);
204+
logger.info(
205+
`Using max tokens from previous sessions: ${formatNumber(maxTokensFromAll, humanReadable)}`,
206+
);
204207
}
205208
}
206209

@@ -301,19 +304,19 @@ export const blocksCommand = define({
301304
log(`Time Remaining: ${pc.green(`${Math.floor(remaining / 60)}h ${remaining % 60}m`)}\n`);
302305

303306
log(pc.bold('Current Usage:'));
304-
log(` Input Tokens: ${formatNumber(block.tokenCounts.inputTokens)}`);
305-
log(` Output Tokens: ${formatNumber(block.tokenCounts.outputTokens)}`);
307+
log(` Input Tokens: ${formatNumber(block.tokenCounts.inputTokens, humanReadable)}`);
308+
log(` Output Tokens: ${formatNumber(block.tokenCounts.outputTokens, humanReadable)}`);
306309
log(` Total Cost: ${formatCurrency(block.costUSD)}\n`);
307310

308311
if (burnRate != null) {
309312
log(pc.bold('Burn Rate:'));
310-
log(` Tokens/minute: ${formatNumber(burnRate.tokensPerMinute)}`);
313+
log(` Tokens/minute: ${formatNumber(burnRate.tokensPerMinute, humanReadable)}`);
311314
log(` Cost/hour: ${formatCurrency(burnRate.costPerHour)}\n`);
312315
}
313316

314317
if (projection != null) {
315318
log(pc.bold('Projected Usage (if current rate continues):'));
316-
log(` Total Tokens: ${formatNumber(projection.totalTokens)}`);
319+
log(` Total Tokens: ${formatNumber(projection.totalTokens, humanReadable)}`);
317320
log(` Total Cost: ${formatCurrency(projection.totalCost)}\n`);
318321

319322
if (ctx.values.tokenLimit != null) {
@@ -331,11 +334,11 @@ export const blocksCommand = define({
331334
: pc.green('OK');
332335

333336
log(pc.bold('Token Limit Status:'));
334-
log(` Limit: ${formatNumber(limit)} tokens`);
337+
log(` Limit: ${formatNumber(limit, humanReadable)} tokens`);
335338
log(
336-
` Current Usage: ${formatNumber(currentTokens)} (${((currentTokens / limit) * 100).toFixed(1)}%)`,
339+
` Current Usage: ${formatNumber(currentTokens, humanReadable)} (${((currentTokens / limit) * 100).toFixed(1)}%)`,
337340
);
338-
log(` Remaining: ${formatNumber(remainingTokens)} tokens`);
341+
log(` Remaining: ${formatNumber(remainingTokens, humanReadable)} tokens`);
339342
log(` Projected Usage: ${percentUsed.toFixed(1)}% ${status}`);
340343
}
341344
}
@@ -395,7 +398,7 @@ export const blocksCommand = define({
395398
formatBlockTime(block, useCompactFormat, ctx.values.locale),
396399
status,
397400
formatModels(block.models),
398-
formatNumber(totalTokens),
401+
formatNumber(totalTokens, humanReadable),
399402
];
400403

401404
// Add percentage if token limit is set
@@ -415,7 +418,7 @@ export const blocksCommand = define({
415418
const currentTokens = getTotalTokens(block.tokenCounts);
416419
const remainingTokens = Math.max(0, actualTokenLimit - currentTokens);
417420
const remainingText =
418-
remainingTokens > 0 ? formatNumber(remainingTokens) : pc.red('0');
421+
remainingTokens > 0 ? formatNumber(remainingTokens, humanReadable) : pc.red('0');
419422

420423
// Calculate remaining percentage (how much of limit is left)
421424
const remainingPercent =
@@ -425,7 +428,9 @@ export const blocksCommand = define({
425428

426429
const remainingRow = [
427430
{
428-
content: pc.gray(`(assuming ${formatNumber(actualTokenLimit)} token limit)`),
431+
content: pc.gray(
432+
`(assuming ${formatNumber(actualTokenLimit, humanReadable)} token limit)`,
433+
),
429434
hAlign: 'right' as const,
430435
},
431436
pc.blue('REMAINING'),
@@ -440,7 +445,7 @@ export const blocksCommand = define({
440445
// PROJECTED row
441446
const projection = projectBlockUsage(block);
442447
if (projection != null) {
443-
const projectedTokens = formatNumber(projection.totalTokens);
448+
const projectedTokens = formatNumber(projection.totalTokens, humanReadable);
444449
const projectedText =
445450
actualTokenLimit != null &&
446451
actualTokenLimit > 0 &&

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

Lines changed: 41 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,8 @@ export const dailyCommand = define({
134134
log(JSON.stringify(jsonOutput, null, 2));
135135
}
136136
} else {
137+
const humanReadable = Boolean(mergedOptions.human);
138+
137139
// Print header
138140
logger.box('Claude Code Token Usage Report - Daily');
139141

@@ -173,19 +175,24 @@ export const dailyCommand = define({
173175

174176
// Add data rows for this project
175177
for (const data of projectData) {
176-
const row = formatUsageDataRow(data.date, {
177-
inputTokens: data.inputTokens,
178-
outputTokens: data.outputTokens,
179-
cacheCreationTokens: data.cacheCreationTokens,
180-
cacheReadTokens: data.cacheReadTokens,
181-
totalCost: data.totalCost,
182-
modelsUsed: data.modelsUsed,
183-
});
178+
const row = formatUsageDataRow(
179+
data.date,
180+
{
181+
inputTokens: data.inputTokens,
182+
outputTokens: data.outputTokens,
183+
cacheCreationTokens: data.cacheCreationTokens,
184+
cacheReadTokens: data.cacheReadTokens,
185+
totalCost: data.totalCost,
186+
modelsUsed: data.modelsUsed,
187+
},
188+
undefined,
189+
humanReadable,
190+
);
184191
table.push(row);
185192

186193
// Add model breakdown rows if flag is set
187194
if (mergedOptions.breakdown) {
188-
pushBreakdownRows(table, data.modelBreakdowns);
195+
pushBreakdownRows(table, data.modelBreakdowns, 1, 0, humanReadable);
189196
}
190197
}
191198

@@ -195,19 +202,24 @@ export const dailyCommand = define({
195202
// Standard display without project grouping
196203
for (const data of dailyData) {
197204
// Main row
198-
const row = formatUsageDataRow(data.date, {
199-
inputTokens: data.inputTokens,
200-
outputTokens: data.outputTokens,
201-
cacheCreationTokens: data.cacheCreationTokens,
202-
cacheReadTokens: data.cacheReadTokens,
203-
totalCost: data.totalCost,
204-
modelsUsed: data.modelsUsed,
205-
});
205+
const row = formatUsageDataRow(
206+
data.date,
207+
{
208+
inputTokens: data.inputTokens,
209+
outputTokens: data.outputTokens,
210+
cacheCreationTokens: data.cacheCreationTokens,
211+
cacheReadTokens: data.cacheReadTokens,
212+
totalCost: data.totalCost,
213+
modelsUsed: data.modelsUsed,
214+
},
215+
undefined,
216+
humanReadable,
217+
);
206218
table.push(row);
207219

208220
// Add model breakdown rows if flag is set
209221
if (mergedOptions.breakdown) {
210-
pushBreakdownRows(table, data.modelBreakdowns);
222+
pushBreakdownRows(table, data.modelBreakdowns, 1, 0, humanReadable);
211223
}
212224
}
213225
}
@@ -216,13 +228,17 @@ export const dailyCommand = define({
216228
addEmptySeparatorRow(table, 8);
217229

218230
// Add totals
219-
const totalsRow = formatTotalsRow({
220-
inputTokens: totals.inputTokens,
221-
outputTokens: totals.outputTokens,
222-
cacheCreationTokens: totals.cacheCreationTokens,
223-
cacheReadTokens: totals.cacheReadTokens,
224-
totalCost: totals.totalCost,
225-
});
231+
const totalsRow = formatTotalsRow(
232+
{
233+
inputTokens: totals.inputTokens,
234+
outputTokens: totals.outputTokens,
235+
cacheCreationTokens: totals.cacheCreationTokens,
236+
cacheReadTokens: totals.cacheReadTokens,
237+
totalCost: totals.totalCost,
238+
},
239+
false,
240+
humanReadable,
241+
);
226242
table.push(totalsRow);
227243

228244
log(table.toString());

0 commit comments

Comments
 (0)