Skip to content

feat(overview): plain-text monthly usage overview command#528

Merged
iamtoruk merged 3 commits into
mainfrom
feat/overview-command
Jun 20, 2026
Merged

feat(overview): plain-text monthly usage overview command#528
iamtoruk merged 3 commits into
mainfrom
feat/overview-command

Conversation

@iamtoruk

Copy link
Copy Markdown
Member

What

Adds codeburn overview, a copy-pasteable plain-text usage report.

  • Defaults to the current month. --from/--to filters any range, plus --provider, --project, and --exclude.
  • --no-color for plain output; colored cyan section headings otherwise (also stripped automatically when the output is piped).
  • Sections: Totals, By tool, Top models, Highest-value days, Top projects, a per-day Daily table, By activity, and Tools, rendered as clean bordered tables.

Notes

  • Reads from the existing in-memory session aggregation (the same data the dashboard and menubar use), so it is unaffected by the report --format json validity issue (unescaped control characters and a NaN/Infinity-style literal) found while building this. That serializer bug is worth fixing separately.
  • Display-only polish lives in the command: cost gains thousands separators and tokens roll up to a B unit, via local wrappers that do not change the shared formatCost/formatTokens, so other commands' output and tests are untouched.
  • Project rows use the path basename (e.g. HackRome, eywa) rather than the sanitized full path.

Verification

  • tsc clean; full suite green (1242) including 3 new tests in tests/overview.test.ts.
  • Verified against real local data for the current month.

Example

CodeBurn  June 2026

Totals
  Cost       $2,795.10
  Tokens     3.49B   in 23.9M / out 20.2M / cache-w 72.5M / cache-r 3.38B
  Calls      14,755   sessions 753
  Cache hit  99.3%

By tool
┌──────────┬───────────┬────────┬───────┐
│ Tool     │      Cost │ Tokens │ Share │
├──────────┼───────────┼────────┼───────┤
│ claude   │ $2,662.37 │  3.34B │   95% │
│ codex    │   $119.12 │ 128.1M │    4% │
└──────────┴───────────┴────────┴───────┘

iamtoruk added 3 commits June 20, 2026 11:04
Add 'codeburn overview', a copy-pasteable text report. Defaults to the
current month, with --from/--to to filter and --no-color for plain
output. Renders Totals, By tool, Top models, Highest-value days, Top
projects, a daily table, By activity, and Tools, with colored section
headings (stripped under --no-color or when piped).

Reuses the existing session aggregation. Cost gains thousands
separators and tokens roll up to a B unit for readability via
display-only wrappers, without changing the shared formatters. Project
names use the path basename instead of the sanitized full path.
Piping output to a reader that closes early (| head, quitting less, a
missing command) made stdout writes throw EPIPE and crash with an
unhandled error event. Handle EPIPE on process.stdout and exit 0 so
piping the overview and other commands behaves normally.
Add a 'Your month at a glance' section featuring codeburn overview with
examples and sample output, a Commands-table entry, and the provider
flag note.
@iamtoruk iamtoruk force-pushed the feat/overview-command branch from ac48a9a to 178e233 Compare June 20, 2026 09:33
@iamtoruk iamtoruk merged commit c55dba2 into main Jun 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant