Skip to content
Open
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
29 changes: 27 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,13 +70,38 @@ 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.

Every period report, `session` included, ends with a **Skills** table: every
Every period report, `session` included, has a **Skills** table: every
skill used in the range, by model and by user, with estimated tokens and cost,
as in the summary. `--top` limits the breakdown sub-rows, not this list.

In table, Markdown and HTML output the overview comes first: skills, plugins,
usage limits and any `-a` / `-r` sections. The period table itself (*Usage per
session*, *per day*, ...) is at the bottom. CSV keeps the period table first.
Every report names the period its data covers, from the first to the last
activity within the filters, e.g. `Data: 2025-12-06 → 2026-11-04 (334 days)`.
It also appears as `coverage` in JSON. Below it are the headline figures:
sessions, prompts, tool calls, pull requests, tokens and estimated cost. In
HTML these are tiles, followed by a row of links to every section. Each table
keeps to the window width and scrolls sideways on its own. *Phase mix per
week* draws the phase shares as one stacked bar, and weeks with fewer than 3
sessions are dimmed. HTML reports add a **How it's measured**
section above the period table. It describes the data read, the period and
time zone, and how sessions, tokens, cost, tools, usage limits, adoption phases,
session intent and recommendations are counted, covering only what the
report contains. The section starts collapsed. HTML also folds what is long:
the period report's Skills table shows its top 15 rows with a *Show all*
button, and the sort order is kept when it folds. Recommendations with low
impact or under $1 at stake sit under a "more" toggle. Table, Markdown and
CSV output keep everything open.

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.
display format. JSON keeps the full title. Each session's **Intent**,
**Phase** (as in the adoption report) and **Prompts** follow *Last Activity*.
HTML and Markdown list the newest session first, and `--order asc|desc`
overrides that. With `--source all` a **Tool**
column names the AI tool each session ran in (Claude Code, GitHub Copilot or
Cursor); JSON rows always have it as `tool`.

**Tokens per tool, skill and subagent.** Breakdown sub-rows fill the token
columns like their parent row: *Output* (the tool input the model wrote),
Expand Down
61 changes: 59 additions & 2 deletions bin/ccreports.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,10 @@ import { loadCursorRecords, defaultCursorDirs } from '../src/cursor.mjs';
import { defaultCursorUserDirs } from '../src/cursor-state.mjs';
import { aggregate, parseDateArg, toJSON, REPORTS } from '../src/aggregate.mjs';
import { buildPeriodReport, buildSummary } from '../src/report.mjs';
import { coverage, methodSection } from '../src/method.mjs';
import { FORMATS, toTerminal, toMarkdown, toCsv, toHtml } from '../src/formats.mjs';
import { loadPricingTable, createPricer } from '../src/pricing.mjs';
import { buildAdoption, buildIntents, parseIntents, PHASES, AUTONOMY_THRESHOLD } from '../src/adoption.mjs';
import { buildAdoption, buildIntents, parseIntents, sessionStats, PHASES, AUTONOMY_THRESHOLD } from '../src/adoption.mjs';
import { INTENTS } from '../src/intent.mjs';
import { buildRecommendations } from '../src/recommendations.mjs';
import { openFile, FORMAT_EXTENSIONS } from '../src/open.mjs';
Expand Down Expand Up @@ -214,7 +215,9 @@ if (showCost) {
}

const result = aggregate(data, { report, since, until, project: opts.project, timeZone: opts.timezone, pricer });
if (opts.order === 'desc') result.buckets.reverse();
// Documents read top-down list the newest session first; --order overrides.
const newestFirst = !opts.order && report === 'session' && ['html', 'markdown'].includes(format);
if (opts.order === 'desc' || newestFirst) result.buckets.reverse();

// Warnings go to stderr so redirected output stays clean.
if (showCost) {
Expand Down Expand Up @@ -249,6 +252,8 @@ const docOpts = {
plugins,
product,
intents,
// Session reports over several products name each session's tool.
toolColumn: source === 'all',
// No token usage at all (Cursor alone): reports leave out the token columns.
tokens: data.usage.length > 0,
};
Expand Down Expand Up @@ -284,9 +289,25 @@ const usageLimits = ['adoption', 'recommendations'].includes(report)
? null
: limitStats(data, { since, until, project: opts.project, timeZone: opts.timezone });

// The period the data covers: first to last activity within the filters.
const range = coverage(result.totals, { timeZone: opts.timezone });

// Per-session phase, intent, prompts and PRs (the adoption assessment's stats):
// columns of the session table and figures in the headline.
const documentFormat = ['table', 'markdown', 'html'].includes(format);
const perSession = adoption?.stats ?? (documentFormat && result.totals.sessions.size ? sessionStats(data, docOpts) : null);
if (perSession && report === 'session') {
const phaseTitle = Object.fromEntries(PHASES.map((p) => [p.key, p.title.replace(/^Phase \d · /, '')]));
const intentTitle = Object.fromEntries(INTENTS.map((i) => [i.key, i.title]));
docOpts.sessionInfo = new Map(
perSession.map((s) => [s.id, { phase: phaseTitle[s.phase] ?? '', intent: intentTitle[s.intent] ?? '', prompts: s.prompts }]),
);
}

let output;
if (format === 'json') {
const meta = { report, source, since, until, pricingSource, ccreportsVersion: VERSION };
if (range) meta.coverage = { from: range.from, to: range.to, days: range.days };
const adoptionJson = adoption && {
summary: adoption.summary,
phases: PHASES,
Expand Down Expand Up @@ -332,6 +353,29 @@ if (format === 'json') {
if (!part || part === doc) continue;
doc = { ...doc, summary: [...(doc.summary ?? []), ...part.summary], sections: [...doc.sections, ...part.sections] };
}
// A page to read: how it is measured, then the period table (per session,
// day, ...) at the bottom, below the overview sections.
const tail = [];
if (format === 'html') {
const has = {
claude: !!claudeData?.files,
copilot: !!copilotData?.files,
cursor: !!cursorData?.files,
cost: showCost,
breakdown: report === 'summary' || !!opts.breakdown,
shell: opts.shell,
adoption: !!adoption,
intentsByClaude: !!intents,
recommendations: !!advice,
};
tail.push(methodSection(has, { since, until, project: opts.project, timeZone: opts.timezone, pricingSource, range }));
}
doc = {
...doc,
kpis: headline(result.totals, perSession, { showCost, tokens: data.usage.length > 0 }),
coverage: range,
sections: [...doc.sections.filter((s) => !s.main), ...tail, ...doc.sections.filter((s) => s.main)],
};
output = {
table: () => toTerminal(doc, { color: toTTY && !opts['no-color'] && !process.env.NO_COLOR, version: VERSION }) + '\n',
markdown: () => toMarkdown(doc, { version: VERSION }),
Expand Down Expand Up @@ -361,3 +405,16 @@ if (file) {
} else {
process.stdout.write(output);
}

/** The headline figures: sessions, prompts, tool calls, PRs, tokens and cost. */
function headline(totals, perSession, { showCost, tokens }) {
const sum = (f) => perSession.reduce((n, s) => n + f(s), 0);
return [
{ label: 'sessions', value: totals.sessions.size },
...(perSession ? [{ label: 'prompts', value: sum((s) => s.prompts) }] : []),
{ label: 'tool calls', value: totals.toolCalls },
...(perSession ? [{ label: 'pull requests', value: sum((s) => s.prs) }] : []),
...(tokens ? [{ label: 'tokens', value: totals.totalTokens, compact: true }] : []),
...(showCost ? [{ label: 'estimated cost', value: totals.costUSD, usd: true }] : []),
];
}
3 changes: 3 additions & 0 deletions skills/report/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ Useful options: `-s/--since` and `-u/--until` (`YYYYMMDD`), `-p/--project <text>
- For a page to view or share, write HTML to a file in the current working
directory unless the user names another place, e.g.
`-f html -o ccreports-adoption.html`, then give the user the full path.
HTML reports list the overview first, then a *How it's measured* section
and the period table (per session, day, ...) at the bottom; the header
names the period the data covers.
When they ask to see or open it, add `--open`: the CLI launches the file in
its associated app (browser for HTML, Excel for CSV). From your shell it does
not open files unless `--open` is passed.
Expand Down
14 changes: 9 additions & 5 deletions src/adoption.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -223,9 +223,9 @@ export function buildAdoption(data, opts) {
const cohortColumns = [
left('Phase'),
left('How'),
right('PRs per session'),
right('Of sessions'),
right('Sessions'),
right('Share of sessions'),
right('PRs per session'),
right('PRs'),
right('Edits per session'),
right('Median tool calls per prompt'),
Expand All @@ -244,9 +244,9 @@ export function buildAdoption(data, opts) {
cells: [
p.title,
p.description.replace(/^Claude\b/, agentName),
average(prs, list.length),
list.length,
share(list.length, stats.length),
list.length,
average(prs, list.length),
prs,
average(sum(list, (s) => s.edits), list.length),
m == null ? '' : average(m, 1),
Expand All @@ -272,6 +272,8 @@ export function buildAdoption(data, opts) {
}
const weeks = [...weekMap.values()].sort((a, b) => (a.key < b.key ? -1 : 1));
const weekRows = weeks.map((w) => ({
// Weeks with only a session or two swing between 0% and 100%.
muted: w.total < 3,
cells: [
w.key,
w.total,
Expand Down Expand Up @@ -327,7 +329,9 @@ export function buildAdoption(data, opts) {
{ title: 'Adoption cohorts', note: `sessions by how they used ${opts.product ?? 'Claude Code'}`, cards: true, columns: cohortColumns, rows: cohortRows },
{
title: 'Phase mix per week',
note: 'by the week a session started',
note: 'by the week a session started; weeks with fewer than 3 sessions are dimmed',
// HTML draws the phase shares as one stacked bar.
stack: { start: 2, count: PHASES.length, title: 'Phase mix' },
columns: [
left('Week'),
right('Sessions'),
Expand Down
12 changes: 11 additions & 1 deletion src/aggregate.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,13 @@ function newBucket(key) {

export const MAIN_AGENT = '(main session)';

/** The AI tool a session ran in, from its entrypoint (copilot-cli, cursor-ide, cli, ...). */
export function toolOf(entrypoint) {
if (entrypoint?.startsWith('copilot')) return 'GitHub Copilot';
if (entrypoint?.startsWith('cursor')) return 'Cursor';
return 'Claude Code';
}

function agentEntry(bucket, type) {
const key = type ?? MAIN_AGENT;
if (!bucket.agents.has(key)) {
Expand Down Expand Up @@ -327,7 +334,10 @@ export function aggregate(data, { report = 'summary', since, until, project, tim
b.avgContextTokens = b.contextRequests ? Math.round(b.contextTokensSum / b.contextRequests) : 0;
}
if (report === 'session') {
for (const b of list) b.title = data.titles.get(b.key) ?? null;
for (const b of list) {
b.title = data.titles.get(b.key) ?? null;
b.tool = toolOf(data.sessions?.get(b.key)?.entrypoint);
}
list.sort((a, b) => (a.lastActivity < b.lastActivity ? -1 : 1));
} else if (report === 'project') {
list.sort((a, b) => a.totalTokens - b.totalTokens);
Expand Down
Loading
Loading