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
34 changes: 33 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,38 @@ week, with the share of sessions in plan mode and auto-approve; how many session
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.
task notifications. `--json` returns the per-session stats, phase and intent.

It closes with **session intent**, what each session was for: bug fix, new
development, refactoring, tests, planning & design, docs & content, ops &
config, review, research & analysis, or other. The intent comes from rules,
not a model, and the strongest signal wins:

1. conventional commit messages and PR titles the session wrote (`fix:`, `feat:`, `refactor:`, `docs:`, `chore:`, ...),
2. review commands (`/code-review`, `/review`, `/security-review`),
3. words in the session title, then the git branch prefix (`fix/`, `feature/`, ...), then the first prompt,
4. what it changed: only plan / spec documents, docs, tests or CI and config files; mostly new files; or nothing at all (research).

Each session in `--json` carries its `intent` and the `intentEvidence` that
decided it. Prompts themselves are not in the report. Cursor logs no git
branch.

`ccreports intents` lists every session with its intent and evidence. With
`-j` it also prints the signals (title, every prompt typed in the session,
branches, commit messages, changed files per kind), so that a model can
classify the sessions as a whole; `--intents <file>` then applies its answer to any report,
replacing the rules' guess:

```sh
node bin/ccreports.mjs intents -j -o signals.json # signals per session
# ... classify, writing {"<session id>": "bugfix", ...} to intents.json
node bin/ccreports.mjs adoption --intents intents.json # evidence: claude
```

The `/ccreports:report` skill does this itself when you ask what your
sessions were for: Claude reads all prompts of each session, classifies it,
and runs the report with `--intents`. The rules themselves only look at the
first prompt.

```sh
node bin/ccreports.mjs adoption -s 20261001 -f html -o adoption.html
Expand Down Expand Up @@ -205,6 +236,7 @@ byte order mark so Excel shows non-ASCII characters correctly.
| `-x, --shell` | Programs run by Bash / PowerShell calls, grouped by purpose: a table per shell in the summary, `[bash]` / `[powershell]` sub-rows in period reports |
| `-a, --adoption` | Append the adoption assessment to the report |
| `-r, --recommendations` | Append best-practice recommendations to the report |
| `--intents <file>` | Session intents assigned elsewhere (`{"<session id>": "<intent>"}`), replacing the rules' guess |
| `-n, --top <n>` | Rows per ranked list (`0` = all) |
| `-f, --format <fmt>` | `table` (default), `json`, `csv`, `markdown` / `md`, `html` |
| `-j, --json` | Same as `--format json` |
Expand Down
46 changes: 43 additions & 3 deletions bin/ccreports.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#!/usr/bin/env node
import { writeFile, mkdtemp } from 'node:fs/promises';
import { writeFile, mkdtemp, readFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { parseArgs } from 'node:util';
Expand All @@ -11,7 +11,8 @@ 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 { buildAdoption, buildIntents, parseIntents, 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';
import { loadPlugins, loadCopilotPlugins, pluginRows, pluginsJSON } from '../src/plugins.mjs';
Expand All @@ -30,6 +31,9 @@ Reports:
session One row per session
project One row per project (working directory)
adoption Adoption assessment: sessions by phase (chat, assisted, agent-first, multi-agent)
and by intent (bug fix, new development, refactoring, research, ...)
intents Each session's intent and the evidence for it; in JSON also the signals
(title, first prompt, branch, commits, changed files) to classify from
recommendations Best-practice recommendations based on your usage, with the cost at stake

Options:
Expand All @@ -42,6 +46,8 @@ Options:
-x, --shell Programs run by Bash / PowerShell calls (summary tables, sub-rows in period reports)
-a, --adoption Append the adoption assessment to the report
-r, --recommendations Append best-practice recommendations to the report
--intents <file> Session intents assigned elsewhere (JSON: {"<session id>": "<intent>"}),
replacing the rules' guess, e.g. classified by Claude in the skill
-n, --top <n> Rows per ranked list (default 15 summary, 5 breakdown; 0 = all)
-f, --format <fmt> table (default), json, csv, markdown (md) or html
-j, --json Same as --format json
Expand Down Expand Up @@ -79,6 +85,7 @@ try {
shell: { type: 'boolean', short: 'x' },
adoption: { type: 'boolean', short: 'a' },
recommendations: { type: 'boolean', short: 'r' },
intents: { type: 'string' },
top: { type: 'string', short: 'n' },
format: { type: 'string', short: 'f' },
json: { type: 'boolean', short: 'j' },
Expand Down Expand Up @@ -147,6 +154,23 @@ if (opts.timezone) {
}
}

let intents;
if (opts.intents) {
let json;
try {
json = JSON.parse((await readFile(opts.intents, 'utf8')).replace(/^/, ''));
} catch (err) {
fail(`cannot read --intents ${opts.intents}: ${err.message}`);
}
const parsedIntents = parseIntents(json);
intents = parsedIntents.intents;
if (parsedIntents.unknown.length) {
console.error(
`ccreports: ignored unknown intents in ${opts.intents}: ${[...new Set(parsedIntents.unknown)].join(', ')} (expected ${INTENTS.map((i) => i.key).join(', ')})`,
);
}
}

const toTTY = !opts.output && !opts.open && process.stdout.isTTY;

const includeSubagents = !opts['no-subagents'];
Expand Down Expand Up @@ -223,13 +247,15 @@ const docOpts = {
pricer,
plugins,
product,
intents,
// 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
// to another with --adoption / --recommendations.
const adoption = report === 'adoption' || opts.adoption ? buildAdoption(data, docOpts) : null;
const intentDoc = report === 'intents' ? buildIntents(data, docOpts) : null;
// Recommendations per product: each names its own settings and commands, and
// is weighed against that product's own cost.
let advice = null;
Expand Down Expand Up @@ -264,6 +290,20 @@ if (format === 'json') {
let json;
if (report === 'adoption') {
json = { ...meta, ...adoptionJson };
} else if (report === 'intents') {
json = {
...meta,
intents: INTENTS,
sessions: intentDoc.stats.map((s) => ({
id: s.id,
title: s.title,
project: s.project,
firstActivity: s.firstActivity,
intent: s.intent,
evidence: s.intentEvidence,
signals: s.intentSignals,
})),
};
} else if (report === 'recommendations') {
json = { ...meta, recommendations: advice.items };
} else if (report === 'summary') {
Expand All @@ -277,7 +317,7 @@ if (format === 'json') {
} else if (result.totals.sessions.size === 0) {
fail('no usage found for the selected filters.');
} else {
const own = { adoption, recommendations: advice }[report];
const own = { adoption, intents: intentDoc, recommendations: advice }[report];
let doc = own ?? (report === 'summary' ? buildSummary(result, docOpts) : buildPeriodReport(report, result, docOpts));
// Appended parts: their summary lines on top, their sections after the report's own.
for (const part of [adoption, advice]) {
Expand Down
52 changes: 50 additions & 2 deletions skills/report/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: report
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]"
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), what each session was for (bug fix, new development, refactoring, research, ...) 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, what they spend their sessions on, 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|intents|recommendations] [options]"
---

# ccreports
Expand Down Expand Up @@ -31,6 +31,7 @@ the request:
| what each tool, skill or subagent consumed | add `-b` (breakdown) to a period report |
| which programs / CLI commands Bash and PowerShell calls ran | add `-x` (`--shell`) to `summary` or a period report |
| an adoption / maturity assessment | `adoption`, or `-a` to add it to another report |
| what sessions were for (bug fixes, features, refactoring, research, ...) | `adoption` (its Session intent section), or `intents` per session; classify them yourself, see [Classifying session intent](#classifying-session-intent) |
| 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` |
| the same for Cursor (CLI or editor agent; activity only, no tokens or cost) | any of the above with `--source cursor` |
Expand All @@ -53,6 +54,49 @@ Useful options: `-s/--since` and `-u/--until` (`YYYYMMDD`), `-p/--project <text>
not open files unless `--open` is passed.
- If Node.js is missing or older than 20, say so; don't install it for them.

## Classifying session intent

ccreports guesses each session's intent with rules. When the user asks what
their sessions were for, or asks for intent to be classified by Claude, classify
the sessions yourself instead; it is more accurate than the rules. For an
adoption report where intent is not the question, the rules are enough.

1. Export the signals, with the same `--source`, `-s`, `-u` and `-p` options as
the report, to a temporary file (your scratchpad directory if you have one):

```sh
node "<base directory>/../../bin/ccreports.mjs" intents -j --no-open -o "<tmp>/ccreports-intent-signals.json" [options]
```

With more than about 200 sessions, or a file over about 300 KB (every
prompt is in it), narrow the range with `--since` or ask the user which
period to classify.
2. Read the file (in parts if it is large). `intents` lists the keys to choose
from. Each session has a `title` and `signals`: `prompts` (every prompt the
user typed, in order, each cut at 500 characters), `branches`,
`workMessages` (commit messages and PR titles it wrote), `commands`,
`files` (changed files per kind: code, tests, docs, ops, plans), `newFiles`,
`edits`, and the rules' guess (`ruleIntent`, `ruleEvidence`). Read all of a
session's prompts and pick one key for its main purpose:
- Judge the session as a whole: the first prompt sets the task, but later
prompts show where the work went (a question that turns into "now build
it" is new development; a feature session that becomes chasing an error
is a bug fix when most prompts are about that error).
- Commits and PR titles are the strongest evidence, then the prompts and
the title, then the branch (a long-lived `feature/` branch also hosts
fixes).
- A session that changed nothing is research, even if it talks about a bug.
- Keep `ruleIntent` when the signals don't point elsewhere; use `other` only
when nothing hints at a purpose.
3. Write `{ "<session id>": "<key>", ... }` to `<tmp>/ccreports-intents.json`.
4. Run the report the user asked for with `--intents "<tmp>/ccreports-intents.json"`,
e.g. `adoption --intents …` or `intents --intents …` (not `-j`, which would
print the prompts again). The section notes how many sessions you classified;
their evidence reads `claude`.

The signals hold the user's own prompts from their local logs. Use them only to
classify; don't quote them in the report or the answer unless asked.

## Explaining the results

Lead with what stands out (biggest cost driver, trend, phase), not a restatement
Expand All @@ -65,6 +109,10 @@ of every table. Keep these caveats in mind and mention them when relevant:
- Context size counts the main conversation only.
- The adoption phases are per session, from the user's own logs; PRs are those
Claude Code created.
- Session intent (bug fix, new development, refactoring, ...) comes from rules
over commit messages, titles, branch names, the first prompt and the files
changed, unless you classified it. Either way it is a best guess per session;
`intents` shows the evidence.

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

Expand Down
Loading
Loading