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
49 changes: 42 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,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.

Every period report, `session` included, ends with 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.

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.
Expand Down Expand Up @@ -124,8 +128,11 @@ your sessions as the unit. Each session lands in the first phase that fits:

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
session and the share of each cohort that used plan mode and auto-approve (Claude
Code's auto mode or Copilot's autopilot, which run without asking per step; not
Cursor's Auto model setting, and Cursor doesn't log auto-run); the phase mix per
week, with the share of sessions in plan mode and auto-approve; how many sessions use each capability
(plan mode, auto-approve, skills, subagents, background agents, worktrees, MCP, web, PRs); and usage by
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
Expand Down Expand Up @@ -253,7 +260,12 @@ How the Copilot logs map onto the reports:
own events. Hooks are named by event (`PreToolUse`), since Copilot doesn't
log the command. **Pull requests** are the PR links in the output of
`gh pr create` or a `create_pull_request` MCP call.
- Installed plugins are listed for Claude Code only.
- **Installed plugins** come from `installedPlugins` in
`~/.copilot/config.json`, with the enabled state from `enabledPlugins` in
`settings.json`. A plugin's skills count whether Copilot logs them as
`plugin:skill` or by the skill's own name. Copilot logs hooks by event,
so plugin hook runs stay 0. With `--source all` the table gets a
**Product** column.

**Recommendations** run the same checks as for Claude Code. Their advice
names Copilot's own levers: `.github/copilot-instructions.md` / `AGENTS.md`,
Expand Down Expand Up @@ -320,10 +332,33 @@ How the transcripts map onto the reports:
A read made only to look at or edit a skill counts as a use too.
- **Recommendations:** without tokens, only the workflow checks can fire:
coding step by step, and skills.
- **Not available:** tokens, cost, models, context size, hooks, compactions,
subagents and pull requests. The transcripts don't record tool results, so
no PR links either. IDE chats from before Cursor wrote transcripts are
kept only in the editor's database and aren't read.
- **Subagents:** launches are counted (with their type, and whether they ran
in the background), but a subagent's own work isn't in the transcript.
- **Not available:** tokens, cost, models that answered, context size, hooks,
compactions and pull requests. The transcripts don't record tool results,
so no PR links either.

**Cursor's database.** The editor also keeps its chats in a SQLite database,
`state.vscdb` in Cursor's user folder (`%APPDATA%\Cursor\User` on Windows,
`~/Library/Application Support/Cursor/User` on macOS, `~/.config/Cursor/User`
on Linux; `CURSOR_USER_DIR` overrides it). ccreports reads it read-only, and
only metadata, never chat text or tool results:

- **Model you picked and mode,** for every chat in it. `"default"` is
Cursor's **Auto** model setting. The adoption report's Agent adoption
table gets an **Auto model** row, as a share of the sessions that log a
model choice (the CLI's don't). Mode (`agent`, `chat` for Ask, `plan`)
counts toward plan mode.
- **Chats without a transcript,** such as editor chats from before Cursor
wrote transcripts. They count from the database: prompts, and tool calls
under Cursor's internal names (`write`, `search_replace`,
`run_terminal_cmd`, …), timed per message. Their project is the
workspace folder the chat belongs to. Drafts never sent are skipped.
- Token counts in the database are left out: Cursor fills them in for too
few messages to add up.

Reading it needs Node 22.13 or later (`node:sqlite`). On older Node,
ccreports skips the database and says so.

## What is counted

Expand Down
18 changes: 14 additions & 4 deletions bin/ccreports.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,15 @@ import { parseArgs } from 'node:util';
import { loadRecords, defaultProjectDirs } from '../src/loader.mjs';
import { loadCopilotRecords, defaultCopilotDirs, mergeData } from '../src/copilot.mjs';
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 { FORMATS, toTerminal, toMarkdown, toCsv, toHtml } from '../src/formats.mjs';
import { loadPricingTable, createPricer } from '../src/pricing.mjs';
import { buildAdoption, PHASES, AUTONOMY_THRESHOLD } from '../src/adoption.mjs';
import { buildRecommendations } from '../src/recommendations.mjs';
import { openFile, FORMAT_EXTENSIONS } from '../src/open.mjs';
import { loadPlugins, pluginRows, pluginsJSON } from '../src/plugins.mjs';
import { loadPlugins, loadCopilotPlugins, pluginRows, pluginsJSON } from '../src/plugins.mjs';
import { VERSION } from '../src/version.mjs';

const HELP = `ccreports - Claude Code (and GitHub Copilot, Cursor) tool, skill, slash-command and token usage
Expand Down Expand Up @@ -155,7 +156,12 @@ const cursorDirs = opts['cursor-dir']?.length ? opts['cursor-dir'] : defaultCurs
const wants = (src) => source === src || source === 'all';
const claudeData = wants('claude') ? await loadRecords({ dirs, includeSubagents }) : null;
const copilotData = wants('copilot') ? await loadCopilotRecords({ dirs: copilotDirs, includeSubagents }) : null;
const cursorData = wants('cursor') ? await loadCursorRecords({ dirs: cursorDirs, includeSubagents }) : null;
const cursorData = wants('cursor')
? await loadCursorRecords({ dirs: cursorDirs, userDirs: defaultCursorUserDirs(), includeSubagents })
: null;
if (cursorData?.stateSkipped) {
console.error("ccreports: reading Cursor's database needs Node 22.13+; older chats and model choices are left out.");
}
const loaded = [claudeData, copilotData, cursorData].filter(Boolean);
const data = loaded.length > 1 ? mergeData(...loaded) : loaded[0];
if (data.files === 0) {
Expand Down Expand Up @@ -195,8 +201,12 @@ if (showCost) {
}

// Installed plugins and what of each was used, in every report.
// (Claude Code plugins only.)
const plugins = claudeData ? pluginRows(await loadPlugins(dirs), result.totals, { project: opts.project }) : [];
// (Claude Code and GitHub Copilot; Cursor's installs aren't read.)
const installed = [
...(claudeData ? await loadPlugins(dirs) : []),
...(copilotData ? await loadCopilotPlugins(copilotDirs) : []),
];
const plugins = pluginRows(installed, result.totals, { project: opts.project });

// Only the terminal table hides columns to fit the screen.
const compact = format === 'table' && (opts.compact || (toTTY && process.stdout.columns < 120));
Expand Down
58 changes: 48 additions & 10 deletions src/adoption.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ export const PHASES = [
// Tool calls per prompt you typed at which a session counts as agent-first.
export const AUTONOMY_THRESHOLD = 10;
const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
// Modes that run without asking per tool call: Claude Code's auto mode, Copilot's autopilot.
const AUTO_MODES = ['auto', 'autopilot'];

const SURFACES = {
cli: 'CLI',
Expand All @@ -40,10 +42,14 @@ export function classify(s) {
return 'assisted';
}

// Feature rows of the "Agent adoption" table: label and whether a session used it.
// Feature rows of the "Agent adoption" table: label, whether a session used it
// and, where only some sessions log it, which sessions the share is out of.
const FEATURES = [
['Code edits', (s) => s.edits > 0],
['Pull requests', (s) => s.prs > 0],
['Plan mode', (s) => s.planMode],
['Auto-approve', (s) => s.autoMode],
['Auto model', (s) => s.autoModel, (s) => s.modelChoice != null],
['Skills', (s) => s.skills > 0],
['Subagents', (s) => s.subagentLaunches > 0],
['Background agents', (s) => s.backgroundAgents > 0],
Expand Down Expand Up @@ -81,6 +87,11 @@ export function sessionStats(data, { since, until, project, timeZone, pricer } =
surface: SURFACES[info?.entrypoint] ?? info?.entrypoint ?? 'unknown',
prompts: info?.prompts.size ?? 0,
prs: info?.prs.size ?? 0,
planMode: info?.modes?.has('plan') ?? false,
autoMode: AUTO_MODES.some((m) => info?.modes?.has(m)),
// The model picked for the session, where logged (Cursor's database); "default" is Cursor's Auto.
modelChoice: info?.modelChoice ?? null,
autoModel: info?.modelChoice === 'default',
toolCalls: b.toolCalls,
skills: b.skillCalls,
subagentLaunches: b.subagentLaunches,
Expand Down Expand Up @@ -115,7 +126,7 @@ const left = (title) => ({ title, align: 'left' });
const pct = (v) => `${Math.round(v * 100)}%`;

/** Written assessment lines. */
function assess(stats, byPhase) {
function assess(stats, byPhase, features) {
if (!stats.length) return [];
const lines = [];
const ranked = PHASES.map((p) => ({ ...p, n: byPhase.get(p.key).length })).sort((a, b) => b.n - a.n);
Expand Down Expand Up @@ -145,7 +156,7 @@ function assess(stats, byPhase) {
lines.push(`PRs per session: ${parts.join(', ')}.`);
}

const unused = FEATURES.filter(([, used]) => !stats.some(used)).map(([label]) => label.toLowerCase());
const unused = features.filter(([, used]) => !stats.some(used)).map(([label]) => label.toLowerCase());
if (unused.length) lines.push(`Not used in this period: ${unused.join(', ')}.`);
return lines;
}
Expand All @@ -156,6 +167,13 @@ export function buildAdoption(data, opts) {
const stats = sessionStats(data, opts);
const byPhase = new Map(PHASES.map((p) => [p.key, stats.filter((s) => s.phase === p.key)]));
const sum = (list, f) => list.reduce((s, x) => s + f(x), 0);
// Cursor's logs don't record auto-run, so its reports leave auto mode out.
const logsAuto = opts.product !== 'Cursor';
// Only Cursor logs the model you picked: the row shows when some session has it.
const logsModelChoice = stats.some((s) => s.modelChoice != null);
const features = FEATURES.filter(
([label]) => (logsAuto || label !== 'Auto-approve') && (logsModelChoice || label !== 'Auto model'),
).map(([label, ...rest]) => [label === 'Auto model' && opts.product !== 'Cursor' ? 'Auto model (Cursor)' : label, ...rest]);

// Cohorts: one card per phase.
// Column order matters for the HTML cards: title, subtitle, headline figure.
Expand All @@ -168,6 +186,8 @@ export function buildAdoption(data, opts) {
right('PRs'),
right('Edits per session'),
right('Median tool calls per prompt'),
right('Plan mode'),
...(logsAuto ? [right('Auto-approve')] : []),
...(opts.tokens !== false ? [right('Tokens per session')] : []),
...(showCost ? [right('Cost per session')] : []),
];
Expand All @@ -187,6 +207,8 @@ export function buildAdoption(data, opts) {
prs,
average(sum(list, (s) => s.edits), list.length),
m == null ? '' : average(m, 1),
share(list.filter((s) => s.planMode).length, list.length),
...(logsAuto ? [share(list.filter((s) => s.autoMode).length, list.length)] : []),
...(opts.tokens !== false ? [list.length ? Math.round(sum(list, (s) => s.totalTokens) / list.length) : ''] : []),
...(showCost ? [list.length ? money(sum(list, (s) => s.costUSD) / list.length) : ''] : []),
],
Expand All @@ -197,15 +219,24 @@ export function buildAdoption(data, opts) {
const weekMap = new Map();
for (const s of stats) {
const key = weekStart(s.firstActivity, timeZone);
const w = weekMap.get(key) ?? { key, total: 0, prs: 0, phases: Object.fromEntries(PHASES.map((p) => [p.key, 0])) };
const w = weekMap.get(key) ?? { key, total: 0, prs: 0, plan: 0, auto: 0, phases: Object.fromEntries(PHASES.map((p) => [p.key, 0])) };
w.total += 1;
w.prs += s.prs;
if (s.planMode) w.plan += 1;
if (s.autoMode) w.auto += 1;
w.phases[s.phase] += 1;
weekMap.set(key, w);
}
const weeks = [...weekMap.values()].sort((a, b) => (a.key < b.key ? -1 : 1));
const weekRows = weeks.map((w) => ({
cells: [w.key, w.total, ...PHASES.map((p) => share(w.phases[p.key], w.total)), w.prs],
cells: [
w.key,
w.total,
...PHASES.map((p) => share(w.phases[p.key], w.total)),
share(w.plan, w.total),
...(logsAuto ? [share(w.auto, w.total)] : []),
w.prs,
],
}));

// Usage by surface.
Expand All @@ -220,26 +251,33 @@ export function buildAdoption(data, opts) {
.sort((a, b) => b[1].sessions - a[1].sessions)
.map(([name, e]) => ({ cells: [name, e.sessions, share(e.sessions, stats.length), e.prs] }));

const featureRows = FEATURES.map(([label, used]) => {
const featureRows = features.map(([label, used, logged]) => {
const n = stats.filter(used).length;
return { cells: [label, n, share(n, stats.length)] };
return { cells: [label, n, share(n, logged ? stats.filter(logged).length : stats.length)] };
});

const range = opts.since || opts.until ? ` (${opts.since ?? '…'} → ${opts.until ?? 'today'})` : '';
return {
title: `${opts.product ?? 'Claude Code'} adoption${range}`,
summary: assess(stats, byPhase),
summary: assess(stats, byPhase, features),
sections: [
{ 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',
columns: [left('Week'), right('Sessions'), ...PHASES.map((p) => right(p.title)), right('PRs')],
columns: [
left('Week'),
right('Sessions'),
...PHASES.map((p) => right(p.title)),
right('Plan mode'),
...(logsAuto ? [right('Auto-approve')] : []),
right('PRs'),
],
rows: weekRows,
},
{
title: 'Agent adoption',
note: 'share of sessions using each capability',
note: `share of sessions using each capability${logsModelChoice ? '; Auto model: of the sessions that log the model picked' : ''}`,
columns: [left('Capability'), right('Sessions'), right('Share of sessions')],
rows: featureRows,
},
Expand Down
Loading
Loading