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
52 changes: 50 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ccreports

Reports Claude Code (and [GitHub Copilot](#github-copilot)) **tool calls, skills, slash commands, subagents, token usage and cost** from
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
[ccusage](https://github.com/ccusage/ccusage), which covers tokens and cost;
ccreports adds what you actually *did* with those tokens.
Expand Down Expand Up @@ -199,8 +199,9 @@ byte order mark so Excel shows non-ASCII characters correctly.
| `--no-subagents` | Exclude subagent transcripts |
| `--compact` | Hide cache token columns (automatic below 120 columns) |
| `--dir <path>` | Projects directory (repeatable). Default: `CLAUDE_CONFIG_DIR` (comma-separated) or `~/.claude` / `~/.config/claude` |
| `--source <src>` | `claude` (default), `copilot` or `all` - see [GitHub Copilot](#github-copilot) |
| `--source <src>` | `claude` (default), `copilot`, `cursor` or `all` - see [GitHub Copilot](#github-copilot) and [Cursor](#cursor) |
| `--copilot-dir <path>` | Copilot session-state directory (repeatable). Default: `COPILOT_HOME` or `~/.copilot`, then `session-state` |
| `--cursor-dir <path>` | Cursor config directory (repeatable). Default: `CURSOR_CONFIG_DIR` or `~/.cursor` |
| `-v, --version` | Print the ccreports version. Reports name it too: in the HTML header line, as a footer in table and Markdown output, and as `ccreportsVersion` in JSON |

### GitHub Copilot
Expand Down Expand Up @@ -265,6 +266,53 @@ checks work differently for Copilot:
With `--source all`, each product gets its own recommendations, weighed
against its own cost, and in JSON every recommendation has a `source`.

### Cursor

`--source cursor` reports Cursor, from the agent transcripts in
`~/.cursor/projects/<project>/agent-transcripts/<id>/<id>.jsonl`. Both the
Cursor CLI and the agent in the Cursor editor write them. `--source all`
adds Cursor to Claude Code and GitHub Copilot.

```sh
node bin/ccreports.mjs --source cursor # summary
node bin/ccreports.mjs session --source cursor
node bin/ccreports.mjs adoption --source cursor
```

**Activity only.** Cursor keeps token usage on its servers. Its local logs
have no tokens, models or cost, so Cursor reports leave out those columns.
In `--source all` reports, Cursor sessions count in sessions, tools, skills
and adoption, but add nothing to tokens and cost.

How the transcripts map onto the reports:

- **Sessions and prompts:** one transcript per session. A prompt is a
message with a `<user_query>`. Cursor's own session metadata
(`~/.cursor/chats/…/meta.json`) marks a session as CLI and gives its title
and working directory. Sessions without it come from the editor.
- **Time:** lines have no timestamps. Recent prompts carry one, and every
record gets the time of the prompt that started its turn. Older transcripts
without any use the file's modification time.
- **Project:** the working directory from the CLI's metadata. Otherwise the
transcript's folder name (`Z-Sources-My-App`), decoded against the folders
that exist on disk. `(no folder)` is the editor without an open folder.
- **Tools** keep Cursor's names (`Read`, `Shell`, `Write`, …). Tools called
through `CallDynamicTool` count under their own name; those outside
Cursor's namespace count as MCP tools (`mcp__<server>__<tool>`). `-x`
breaks down `Shell` commands. Edits are `Write`, `Edit`, `StrReplace`,
`MultiEdit` and `Delete`. `SwitchMode` and `CreatePlan` mark plan mode.
- **Skills you invoke** come from the skill block Cursor attaches to your
message (`/github` in the CLI, or picked in the editor). **Skills the
agent uses** are `Read` calls on a `SKILL.md` in a skills folder Cursor
loads from, such as `.cursor/skills`, `.claude/skills` or `.agents/skills`.
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.

## What is counted

- **Tokens** – `usage` from each assistant message, deduplicated per
Expand Down
41 changes: 31 additions & 10 deletions bin/ccreports.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import path from 'node:path';
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 { 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';
Expand All @@ -15,7 +16,7 @@ import { openFile, FORMAT_EXTENSIONS } from '../src/open.mjs';
import { loadPlugins, pluginRows, pluginsJSON } from '../src/plugins.mjs';
import { VERSION } from '../src/version.mjs';

const HELP = `ccreports - Claude Code (and GitHub Copilot) tool, skill, slash-command and token usage
const HELP = `ccreports - Claude Code (and GitHub Copilot, Cursor) tool, skill, slash-command and token usage

Usage: ccreports [report] [options]

Expand All @@ -31,7 +32,8 @@ Reports:
recommendations Best-practice recommendations based on your usage, with the cost at stake

Options:
--source <src> claude (default), copilot (GitHub Copilot CLI / VS Code agent) or all
--source <src> claude (default), copilot (GitHub Copilot CLI / VS Code agent),
cursor (Cursor CLI / editor agent; activity only, no tokens) or all
-s, --since <date> Include from this date (YYYYMMDD or YYYY-MM-DD)
-u, --until <date> Include up to and including this date
-p, --project <text> Only projects whose path contains <text> (case-insensitive)
Expand All @@ -54,6 +56,7 @@ Options:
--no-color Disable colors (also honors NO_COLOR)
--dir <path> Projects directory to scan (repeatable; default from CLAUDE_CONFIG_DIR or ~/.claude)
--copilot-dir <path> Copilot session-state directory (repeatable; default from COPILOT_HOME or ~/.copilot)
--cursor-dir <path> Cursor config directory (repeatable; default from CURSOR_CONFIG_DIR or ~/.cursor)
-v, --version Show the ccreports version
-h, --help Show this help
`;
Expand Down Expand Up @@ -91,6 +94,7 @@ try {
dir: { type: 'string', multiple: true },
source: { type: 'string' },
'copilot-dir': { type: 'string', multiple: true },
'cursor-dir': { type: 'string', multiple: true },
version: { type: 'boolean', short: 'v' },
help: { type: 'boolean', short: 'h' },
},
Expand All @@ -114,7 +118,7 @@ if (!REPORTS.includes(report)) fail(`unknown report "${report}". Expected one of
if (positionals.length > 1) fail(`unexpected argument "${positionals[1]}"`);
if (opts.order && !['asc', 'desc'].includes(opts.order)) fail('--order must be asc or desc');
const source = (opts.source ?? 'claude').toLowerCase();
if (!['claude', 'copilot', 'all'].includes(source)) fail('--source must be claude, copilot or all');
if (!['claude', 'copilot', 'cursor', 'all'].includes(source)) fail('--source must be claude, copilot, cursor or all');

let format = opts.json ? 'json' : (opts.format ?? 'table').toLowerCase();
if (format === 'md') format = 'markdown';
Expand Down Expand Up @@ -147,16 +151,30 @@ const toTTY = !opts.output && !opts.open && process.stdout.isTTY;
const includeSubagents = !opts['no-subagents'];
const dirs = opts.dir?.length ? opts.dir : defaultProjectDirs();
const copilotDirs = opts['copilot-dir']?.length ? opts['copilot-dir'] : defaultCopilotDirs();
const claudeData = source !== 'copilot' ? await loadRecords({ dirs, includeSubagents }) : null;
const copilotData = source !== 'claude' ? await loadCopilotRecords({ dirs: copilotDirs, includeSubagents }) : null;
const data = claudeData && copilotData ? mergeData(claudeData, copilotData) : claudeData ?? copilotData;
const cursorDirs = opts['cursor-dir']?.length ? opts['cursor-dir'] : defaultCursorDirs();
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 loaded = [claudeData, copilotData, cursorData].filter(Boolean);
const data = loaded.length > 1 ? mergeData(...loaded) : loaded[0];
if (data.files === 0) {
const scanned = [...(claudeData ? dirs : []), ...(copilotData ? copilotDirs : [])];
fail(`no ${source === 'copilot' ? 'sessions' : 'transcripts'} found in: ${scanned.join(', ')}`);
const scanned = [...(claudeData ? dirs : []), ...(copilotData ? copilotDirs : []), ...(cursorData ? cursorDirs : [])];
fail(`no ${source === 'claude' ? 'transcripts' : 'sessions'} found in: ${scanned.join(', ')}`);
}
const product = { claude: 'Claude Code', copilot: 'GitHub Copilot', all: 'Claude Code and GitHub Copilot' }[source];
const product = {
claude: 'Claude Code',
copilot: 'GitHub Copilot',
cursor: 'Cursor',
all: 'Claude Code, GitHub Copilot and Cursor',
}[source];

const showCost = !opts['no-cost'];
// Cursor logs no token usage: its own reports leave out cost, and combined
// ones count its sessions in activity only.
const showCost = !opts['no-cost'] && source !== 'cursor';
if (source === 'all' && cursorData?.files) {
console.error('ccreports: Cursor logs no token usage; its sessions count in activity (prompts, tools, skills) only.');
}
let pricer, pricingSource;
if (showCost) {
const pricing = await loadPricingTable({ offline: opts.offline });
Expand Down Expand Up @@ -195,6 +213,8 @@ const docOpts = {
pricer,
plugins,
product,
// No token usage at all (Cursor alone): reports leave out the token columns.
tokens: data.usage.length > 0,
};

// The adoption assessment and recommendations: their own reports, or appended
Expand All @@ -207,6 +227,7 @@ if (report === 'recommendations' || opts.recommendations) {
const parts = [
['claude', claudeData],
['copilot', copilotData],
['cursor', cursorData],
]
.filter(([, d]) => d?.files)
.map(([src, d]) => ({ src, doc: buildRecommendations(d, { ...docOpts, source: src }) }));
Expand Down
11 changes: 8 additions & 3 deletions skills/report/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: report
description: Report the user's own Claude Code usage from their local session logs (~/.claude/projects), and their GitHub Copilot CLI / VS Code agent usage (~/.copilot/session-state) - tokens and estimated API cost, tool / skill / slash-command / hook / subagent counts and the tokens each consumed, context size, sessions, an adoption assessment (chat, assisted, agent-first, multi-agent) and best-practice recommendations backed by their data. Use when the user asks how much they used or spent, which tools or skills they use most, what consumes their tokens, how their usage trends per day/week/month/project/session, how far they have adopted agentic workflows, how to use Claude Code or Copilot more effectively or cheaply, how their Claude Code and Copilot usage compare, or wants such a report as a table, Markdown, CSV, JSON or HTML page.
description: Report the user's own Claude Code usage from their local session logs (~/.claude/projects), their GitHub Copilot CLI / VS Code agent usage (~/.copilot/session-state), and their Cursor CLI / editor agent activity (~/.cursor/projects) - tokens and estimated API cost, tool / skill / slash-command / hook / subagent counts and the tokens each consumed, context size, sessions, an adoption assessment (chat, assisted, agent-first, multi-agent) and best-practice recommendations backed by their data. Use when the user asks how much they used or spent, which tools or skills they use most, what consumes their tokens, how their usage trends per day/week/month/project/session, how far they have adopted agentic workflows, how to use Claude Code, Copilot or Cursor more effectively or cheaply, how their usage of these tools compares, or wants such a report as a table, Markdown, CSV, JSON or HTML page.
argument-hint: "[summary|daily|weekly|monthly|session|project|adoption|recommendations] [options]"
---

Expand Down Expand Up @@ -33,7 +33,8 @@ the request:
| an adoption / maturity assessment | `adoption`, or `-a` to add it to another report |
| advice: how to use Claude Code better or cheaper | `recommendations`, or `-r` to add it to another report |
| the same for GitHub Copilot (CLI or VS Code agent) | any of the above with `--source copilot` |
| Claude Code and Copilot together, or compared | any of the above with `--source all` (recommendations get a section per product) |
| the same for Cursor (CLI or editor agent; activity only, no tokens or cost) | any of the above with `--source cursor` |
| Claude Code, Copilot and Cursor together, or compared | any of the above with `--source all` (recommendations get a section per product) |

Useful options: `-s/--since` and `-u/--until` (`YYYYMMDD`), `-p/--project <text>`,
`-n/--top <n>`, `--compact`, `--no-cost`, `-f/--format table|json|csv|markdown|html`,
Expand Down Expand Up @@ -65,7 +66,7 @@ of every table. Keep these caveats in mind and mention them when relevant:
- The adoption phases are per session, from the user's own logs; PRs are those
Claude Code created.

With `--source copilot` or `all`, also keep in mind:
With `--source copilot`, `cursor` or `all`, also keep in mind:

- Copilot cost is what it billed in AI credits (1 AIU = $0.01); where nothing
was billed, Claude models are priced at API rates and other models (GPT,
Expand All @@ -75,3 +76,7 @@ With `--source copilot` or `all`, also keep in mind:
shut down cleanly have no token counts.
- Copilot's tokens per tool are rougher than Claude Code's: they are scaled
down to at most what each session sent.
- Cursor keeps token usage on its servers: Cursor reports show activity only
(sessions, prompts, tools, skills, commands, adoption), and add nothing to
tokens or cost in combined reports. Skills the agent picks itself are
inferred from it reading a SKILL.md.
10 changes: 7 additions & 3 deletions src/adoption.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ const SURFACES = {
remote: 'Web',
'copilot-cli': 'Copilot CLI',
'copilot-vscode': 'Copilot in VS Code',
'cursor-cli': 'Cursor CLI',
'cursor-ide': 'Cursor editor',
};

/** Places one session's stats in a phase (first matching rule wins). */
Expand Down Expand Up @@ -166,24 +168,26 @@ export function buildAdoption(data, opts) {
right('PRs'),
right('Edits per session'),
right('Median tool calls per prompt'),
right('Tokens per session'),
...(opts.tokens !== false ? [right('Tokens per session')] : []),
...(showCost ? [right('Cost per session')] : []),
];
// The phase descriptions name Claude; other products' reports say "the agent".
const agentName = (opts.product ?? 'Claude Code') === 'Claude Code' ? 'Claude' : 'The agent';
const cohortRows = PHASES.map((p) => {
const list = byPhase.get(p.key);
const prs = sum(list, (s) => s.prs);
const m = median(list.map((s) => s.toolCallsPerPrompt));
return {
cells: [
p.title,
p.description,
p.description.replace(/^Claude\b/, agentName),
average(prs, list.length),
list.length,
share(list.length, stats.length),
prs,
average(sum(list, (s) => s.edits), list.length),
m == null ? '' : average(m, 1),
list.length ? Math.round(sum(list, (s) => s.totalTokens) / 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 Down
3 changes: 3 additions & 0 deletions src/aggregate.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -299,6 +299,9 @@ export function aggregate(data, { report = 'summary', since, until, project, tim
}
}

// Activity without tokens (Cursor's prompts): counts the session and its time only.
for (const rec of data.events ?? []) accept(rec);

for (const rec of data.hooks ?? []) {
for (const b of accept(rec) ?? []) {
const h = b.hooks.get(rec.command) ?? { events: new Set(), runs: 0, errors: 0, blocked: 0, durationMs: 0, contextTokens: 0 };
Expand Down
3 changes: 2 additions & 1 deletion src/copilot.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -424,10 +424,11 @@ export function mergeData(...parts) {
skills: [...first.skills],
commands: [...first.commands],
hooks: [...first.hooks],
events: [...(first.events ?? [])],
};
for (const p of rest) {
out.files += p.files;
for (const k of ['usage', 'tools', 'skills', 'commands', 'hooks']) out[k].push(...p[k]);
for (const k of ['usage', 'tools', 'skills', 'commands', 'hooks', 'events']) out[k].push(...(p[k] ?? []));
for (const [k, v] of p.sessions) out.sessions.set(k, v);
for (const [k, v] of p.titles) out.titles.set(k, v);
}
Expand Down
Loading
Loading