feat: weekly usage digest CLI command by kannupriyakalra · Pull Request #82 · pavanvamsi3/copilot-lens

kannupriyakalra · 2026-06-10T15:57:47Z

Summary

Implements the copilot-lens digest command from issue #70 — a Spotify Wrapped-style terminal summary of AI usage.

copilot-lens digest               # current week (default)
copilot-lens digest --last-week   # prior week
copilot-lens digest --month       # current month
copilot-lens digest --save        # also writes digest.md to cwd
copilot-lens digest --json        # machine-readable JSON

Sample output:

Week of Jun 2 – Jun 8, 2026
────────────────────────────────────
  📅  Active days       5 / 7
  💬  Sessions          34     ▲ 12% vs prior
  ⏱   Total time        6h 14m
  🔤  Tokens used       1.2M   ▲ 8% vs prior
  🏆  Most active repo  copilot-lens
  🕐  Peak hour         2 – 3 PM
  🔧  Top tool          Bash (41 calls)
  🤖  Top model         claude-sonnet-4-6

  Longest session: "copilot-lens" — 48m, 23 turns

Changes

src/digest.ts — getDigest(period) aggregates sessions from listSessions() filtered by date range; scans CLI event files for tool usage, accurate duration, and turn counts; pulls token totals from getTokenUsage().daily buckets filtered to the range. No new data sources.
src/cli-digest.tsx — Ink TUI mirroring cli-tokens.tsx style; --save writes digest.md; --json outputs raw JSON for piping.
src/cli.ts — wires digest subcommand and updates help text.
src/__tests__/cli-digest.test.ts — 8 tests covering all parseDigestArgs combinations.

Test plan

copilot-lens digest renders the weekly summary
copilot-lens digest --last-week shows prior week label
copilot-lens digest --month shows current month label
copilot-lens digest --json outputs valid JSON with all fields
copilot-lens digest --save writes digest.md and also renders TUI
copilot-lens digest --help shows usage text
No activity period shows "No activity found for this period."
All 122 unit tests pass

Closes #70

🤖 Generated with Claude Code

kannupriyakalra · 2026-06-10T16:08:59Z

Verification Report

Verdict: PASS (with one bug found and fixed)

Method: Cold-start via npx tsx src/cli.ts digest [flags] on feat/weekly-digest. All sessions in test env are claude-code source.

Steps

✅ copilot-lens digest --help → correct usage printed, all four flags listed

Usage: copilot-lens digest [options]

  Print a weekly usage summary to the terminal (Spotify Wrapped-style).

  Options:
    --last-week   Show last week instead of the current week
    --month       Show the current month's digest
    --save        Also write digest.md to the current directory
    --json        Output raw JSON (pipeline-friendly)
    -h, --help    Show this help

✅ copilot-lens digest → TUI renders correctly after fix

Week of Jun 8 – Jun 14, 2026
────────────────────────────────────
  📅  Active days       1 / 7
  💬  Sessions          8
  ⏱   Total time        9h 5m
  🔤  Tokens used       119.3M
  🏆  Most active repo  llm4s
  🕐  Peak hour         8 – 9 PM
  🤖  Top model         claude-sonnet-4-6

  Longest session: "modular-jingling-pike" — 2h 25m

✅ copilot-lens digest --last-week → shows prior week label, graceful empty state
```
Week of Jun 1 – Jun 7, 2026
No activity found for this period.
```

✅ copilot-lens digest --month → June 2026 digest with ▲ change badges

June 2026
────────────────────────────────────
  📅  Active days       1 / 30
  💬  Sessions          8     ▲ 167% vs prior
  ⏱   Total time        8h 59m
  🔤  Tokens used       116.1M     ▲ 189% vs prior
  🏆  Most active repo  llm4s
  🕐  Peak hour         8 – 9 PM
  🤖  Top model         claude-sonnet-4-6

✅ copilot-lens digest --json → valid JSON, all 16 fields present, correct schema

✅ copilot-lens digest --save → prints Saved digest to .../digest.md to stderr, renders TUI, writes well-formed Markdown table

# AI Usage Digest
## Week of Jun 8 – Jun 14, 2026
| Metric | Value |
|--------|-------|
| Active days | 1 / 7 |
| Sessions | 8 |
...
**Longest session:** "modular-jingling-pike" — 2h 25m
_Generated by copilot-lens_

✅ copilot-lens --help → digest correctly listed alongside tokens
✅ All 122 unit tests pass (8 new parseDigestArgs tests + 114 existing)
🔍 --bogus-flag → silently ignored, runs week digest. Consistent with tokens behavior.
🔍 --json --save together → --json takes priority, TUI suppressed and --save skipped. The old digest.md is not overwritten. This may surprise users who expect both to act; worth a note in --help if that combination is intentional.

Bug fixed in this review

totalDays off-by-one (fixed in commit db94427):

digest.ts line 93 had Math.round(...) + 1. Since end is already 23:59:59.999, Math.round(6.9999...) = 7 and the extra +1 made weeks display 8 and June display 31. Removed the +1:

Week now shows 1 / 7 ✅
June now shows 1 / 30 ✅

Observations for maintainer

topTool is always null for pure Claude Code setups — tool scanning only runs for cli-source sessions. On a machine with no Copilot CLI sessions (like this test), the 🔧 Top tool row never appears. The issue mockup shows it as a key metric. Consider pulling tool data from getClaudeCodeAnalytics() (it's already computed in sessions.ts) when cli sessions are absent.
Longest-session title shows session slug — Claude Code sessions use slugs (e.g. "modular-jingling-pike") as titles since there's no user-defined name. This is fine as a fallback, but for cli sessions the cwd basename is used which is more readable. No action needed; just worth knowing.
Tokens fluctuate slightly between invocations — The getTokenUsage 30 s cache means rapid sequential calls within the window return the same value; longer waits pick up in-progress session writes. Normal behavior, but explains why token counts in this report vary slightly between steps.

Copilot

Pull request overview

Adds a new copilot-lens digest CLI subcommand that produces a “Wrapped-style” usage summary for a selected period (week by default, with --last-week / --month) with optional JSON output and Markdown export.

Changes:

Introduces getDigest(period) to aggregate session counts, active days, durations, tool usage, token totals, and “prior period” comparisons.
Adds an Ink-based TUI (cli-digest.tsx) plus --save (writes digest.md) and --json modes.
Wires the new digest subcommand into the main CLI and adds argument-parsing tests.

Show a summary per file

File	Description
src/digest.ts	New digest aggregation logic over sessions + token usage + CLI event scanning.
src/cli-digest.tsx	New Ink TUI and CLI entrypoint for `copilot-lens digest`, including `--save` and `--json`.
src/cli.ts	Adds `digest` subcommand routing and updates top-level help text.
src/tests/cli-digest.test.ts	Adds unit tests for `parseDigestArgs`.

Copilot's findings

Files reviewed: 4/4 changed files
Comments generated: 7

kannupriyakalra · 2026-06-18T19:28:35Z

+    fs.writeFileSync(outPath, md, "utf-8");
+    process.stderr.write(`Saved digest to ${outPath}\n`);


Fixed — wrapped writeFileSync in a try/catch. On error it now prints a clear message to stderr and sets process.exitCode = 1, while the TUI still renders.

kannupriyakalra · 2026-06-18T19:28:43Z

+  if (opts.save) {
+    const data = getDigest(opts.period);
+    const md = toMarkdown(data);


Fixed — DigestApp now accepts an optional precomputed prop. In --save mode the result from the first getDigest() call is passed directly as precomputed, so the TUI skips the second computation entirely.

kannupriyakalra · 2026-06-18T19:28:51Z

+export function getDigest(period: DigestPeriod = "week"): DigestData {
+  const { cur, prior } = getBounds(period);
+  const allSessions = listSessions();


Added 7 Vitest tests in src/__tests__/cli-digest.test.ts covering: required fields, totalDays for week/month periods, rangeLabel format, priorTokens shape, longestSession shape, and ISO date string validity.

kannupriyakalra · 2026-06-18T19:28:59Z

+  Commands:
+    (default)   Start the web dashboard
+    tokens      Show token usage in the terminal (Ink TUI)
+    digest      Show a weekly usage summary in the terminal


Fixed — updated the help description in src/cli.ts from "weekly" to "period-based" to accurately reflect that --last-week and --month are also supported.

kannupriyakalra · 2026-06-18T19:29:06Z

+const HELP = `
+  Usage: copilot-lens digest [options]
+
+  Print a weekly usage summary to the terminal (Spotify Wrapped-style).


Fixed — updated the HELP string in src/cli-digest.tsx to say "period-based" instead of "weekly" so it matches the actual supported options.

kannupriyakalra · 2026-06-18T19:17:57Z

Hey @pavanvamsi3 — all 7 Copilot reviewer comments have been addressed. Could you take another look when you get a chance? Thanks!

Adds `copilot-lens digest` — a Spotify Wrapped-style terminal summary of AI usage for the current week, last week, or current month. - src/digest.ts: date-range aggregation over sessions and token data - src/cli-digest.tsx: Ink TUI showing active days, sessions, time, tokens (with ▲/▼ % vs prior period), top repo/hour/tool/model, and longest session; --save writes digest.md; --json for scripting - Wire into cli.ts under the `digest` subcommand - Tests for parseDigestArgs covering all flags and edge cases Closes #70 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

end is already set to 23:59:59.999, so Math.round(6.999...) already gives 7; adding 1 made week show 8, June show 31. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Read events.jsonl from end of file so large sessions reflect the most recent activity for tool counts and duration - Remove all-time topModel fallback — only show model from the selected period's token data to avoid stale/misleading values - Wrap fs.writeFileSync in try/catch; print clear error and set non-zero exitCode on failure without blocking TUI render - Pass pre-computed DigestData to DigestApp when --save is used to avoid calling getDigest() twice - Fix help text: "weekly" → "period-based" in cli.ts and cli-digest.tsx - Add 7 getDigest() tests covering all three periods, field shapes, date string format, and boundary invariants Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

kannupriyakalra · 2026-06-18T19:25:38Z

Merge conflicts resolved — rebased onto latest main. The branch is now clean and ready for re-review.

pavanvamsi3 requested a review from Copilot June 11, 2026 20:32

Copilot started reviewing on behalf of pavanvamsi3 June 11, 2026 20:32 View session

Copilot AI reviewed Jun 11, 2026

View reviewed changes

kannupriyakalra and others added 4 commits June 19, 2026 00:48

feat: wire digest subcommand into CLI and help text

4e39212

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: off-by-one in totalDays — remove spurious +1 from range calc

19d4f20

end is already set to 23:59:59.999, so Math.round(6.999...) already gives 7; adding 1 made week show 8, June show 31. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

kannupriyakalra force-pushed the feat/weekly-digest branch from d6f631b to b895784 Compare June 18, 2026 19:22

Navigation Menu

feat: weekly usage digest CLI command - #82

feat: weekly usage digest CLI command#82
kannupriyakalra wants to merge 4 commits into
mainfrom
feat/weekly-digest

kannupriyakalra commented Jun 10, 2026

Uh oh!

kannupriyakalra commented Jun 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

kannupriyakalra Jun 18, 2026

Uh oh!

kannupriyakalra Jun 18, 2026

Uh oh!

kannupriyakalra Jun 18, 2026

Uh oh!

kannupriyakalra Jun 18, 2026

Uh oh!

kannupriyakalra Jun 18, 2026

Uh oh!

kannupriyakalra commented Jun 18, 2026

Uh oh!

kannupriyakalra commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		fs.writeFileSync(outPath, md, "utf-8");
		process.stderr.write(`Saved digest to ${outPath}\n`);

Conversation

kannupriyakalra commented Jun 10, 2026

Summary

Changes

Test plan

Uh oh!

kannupriyakalra commented Jun 10, 2026

Verification Report

Steps

Bug fixed in this review

Observations for maintainer

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

kannupriyakalra Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

kannupriyakalra Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

kannupriyakalra Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

kannupriyakalra Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

kannupriyakalra Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

kannupriyakalra commented Jun 18, 2026

Uh oh!

kannupriyakalra commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants