Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# ccreports

Reports Claude Code (and [GitHub Copilot](#github-copilot) and [Cursor](#cursor)) **tool calls, skills, slash commands, subagents, token usage and cost** from
the local session transcripts in `~/.claude/projects`. Inspired by
Reports Claude Code **tool calls, skills, slash commands, subagents, token usage and cost** from
the local session transcripts in `~/.claude/projects`, and the same for
[GitHub Copilot](#github-copilot) and [Cursor](#cursor) from their own local
logs (Cursor: activity only). Inspired by
[ccusage](https://github.com/ccusage/ccusage), which covers tokens and cost;
ccreports adds what you actually *did* with those tokens.

Expand All @@ -15,6 +17,7 @@ No install needed:
npx ccreports@latest # summary
npx ccreports@latest daily -b # per day, with tool / skill / agent breakdown
npx ccreports@latest -a -r -f html -o report.html # summary + adoption + recommendations as a page
npx ccreports@latest --source copilot # GitHub Copilot instead (cursor, or all for every tool)
```

Or install it globally: `npm install -g ccreports`, then run `ccreports`.
Expand Down Expand Up @@ -63,6 +66,10 @@ both, so rows can add up to more than the total. With `--breakdown`, a
**Per Session** column gives each tool / skill / command / agent count divided
by the row's sessions.

The `session` report names each session by its title (the first 8 characters
of its id when it has none), cut to at most 35 characters with `…` in every
display format. JSON keeps the full title.

**Tokens per tool, skill and subagent.** Breakdown sub-rows fill the token
columns like their parent row: *Output* (the tool input the model wrote),
*Cache Create* (the result entering the context), *Cache Read* (re-reads),
Expand Down Expand Up @@ -115,7 +122,8 @@ The report opens with a short written assessment, then shows the cohorts (as
cards in HTML) with PRs, edits, tool calls per prompt, tokens and cost per
session; the phase mix per week; how many sessions use each capability
(skills, subagents, background agents, worktrees, MCP, web, PRs); and usage by
surface (CLI, desktop, IDE, SDK). PRs are the `pr-link` entries Claude Code
surface (CLI, desktop, IDE, SDK, and the Copilot and Cursor surfaces with
`--source`). PRs are the `pr-link` entries Claude Code
records when it creates a PR; prompts exclude agent-to-agent messages and
task notifications. `--json` returns the per-session stats and phase.

Expand Down Expand Up @@ -315,6 +323,9 @@ How the transcripts map onto the reports:

## What is counted

For Claude Code; GitHub Copilot and Cursor are described in their own
sections above.

- **Tokens** – `usage` from each assistant message, deduplicated per
`message.id + requestId`. One API response is written as several lines, and
resumed sessions copy earlier history, so naive summing overcounts. Totals
Expand Down
9 changes: 7 additions & 2 deletions src/report.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@ const left = (title, maxWidth) => ({ title, align: 'left', maxWidth });
const path = (title) => ({ title, align: 'left', maxWidth: 40, clip: 'start' });
const wrapped = (title) => ({ title, align: 'left', maxWidth: 100, wrap: true });

// Session names: at most 35 characters in every display format (JSON keeps the full title).
export const SESSION_NAME_MAX = 35;
export const sessionName = (title) =>
title.length > SESSION_NAME_MAX ? title.slice(0, SESSION_NAME_MAX - 1) + '…' : title;

/** Shell command categories by calls, Other last. */
const shellCategoryRows = (categories) =>
ranked(categories, (c) => c.calls).sort((a, b) => (a[0] === OTHER_CATEGORY) - (b[0] === OTHER_CATEGORY));
Expand Down Expand Up @@ -193,7 +198,7 @@ export function buildPeriodReport(report, { buckets, totals }, opts) {
const hasSubRows = breakdown || shell;
const isSession = report === 'session';
const lead = isSession
? [left('Session', 36), path('Project'), left('Last Activity')]
? [left('Session', SESSION_NAME_MAX), path('Project'), left('Last Activity')]
: [report === 'project' ? path('Project') : left(PERIOD[report].title)];
// A session row is always one session, so the per-session columns only make
// sense for the other reports. Per Session is filled on breakdown sub-rows.
Expand Down Expand Up @@ -233,7 +238,7 @@ export function buildPeriodReport(report, { buckets, totals }, opts) {
for (const b of buckets) {
const models = ranked(b.models, (m) => m.totalTokens).map(([m]) => shortModel(m));
const leadCells = isSession
? [b.title ?? b.key.slice(0, 8), [...b.projects][0] ?? '', localTime(b.lastActivity, timeZone)]
? [sessionName(b.title ?? b.key.slice(0, 8)), [...b.projects][0] ?? '', localTime(b.lastActivity, timeZone)]
: [b.key];
rows.push({
cells: [
Expand Down
15 changes: 15 additions & 0 deletions test/ccreports.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -315,3 +315,18 @@ test('reports hook runs, failures, duration and added context', async () => {
await rm(root, { recursive: true, force: true });
}
});

test('session names are at most 35 characters in reports', async () => {
const { sessionName, SESSION_NAME_MAX } = await import('../src/report.mjs');
assert.equal(SESSION_NAME_MAX, 35);
assert.equal(sessionName('Short title'), 'Short title');
assert.equal(sessionName('x'.repeat(35)), 'x'.repeat(35));
const long = sessionName('Investigate why the nightly build fails on Windows agents');
assert.equal(long.length, 35);
assert.equal(long, 'Investigate why the nightly build …');

const rec = { timestamp: '2026-10-01T10:00:00Z', sessionId: 's1', project: '/p', agent: null, name: 'Bash' };
const data = { usage: [], tools: [rec], skills: [], commands: [], hooks: [], titles: new Map([['s1', 'A'.repeat(50)]]) };
const doc = buildPeriodReport('session', aggregate(data, { report: 'session' }), {});
assert.equal(doc.sections[0].rows[0].cells[0], 'A'.repeat(34) + '…');
});
Loading