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 and Cursor from their own local
logs (Cursor: activity only). Inspired by
ccusage, which covers tokens and cost;
ccreports adds what you actually did with those tokens.
Zero dependencies, Node.js 20+.
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.
See example-output.html for an example HTML report: per-session usage across Claude Code, GitHub Copilot and Cursor, with adoption and recommendations (session titles and project paths anonymized).
At the prompt of a Claude Code terminal session:
/plugin install ccreports --marketplace Expecho/ccreports
Answer y to add the marketplace, then pick a scope. From a shell:
claude plugin install ccreports --marketplace Expecho/ccreports. In the
desktop app: click + next to the prompt box, then Plugins, Add marketplace with
Expecho/ccreports, then Add plugin.
The plugin adds a report skill: ask Claude things like "what did I spend on
Claude Code this week?" or "which tools use most of my tokens?", or run it
directly:
/ccreports:report adoption as html
/ccreports:report weekly -b --since 20261001
Claude runs the bundled CLI (Node.js 20+ required) and explains the results.
node bin/ccreports.mjs # summary: totals + ranked tools, MCP servers, skills, commands, hooks, plugins, models
node bin/ccreports.mjs daily # one row per day
node bin/ccreports.mjs weekly -b # per week, with top tools/skills/commands as sub-rows
node bin/ccreports.mjs -x # summary plus the programs run by Bash / PowerShell calls
node bin/ccreports.mjs monthly --json
node bin/ccreports.mjs session -s 20261020
node bin/ccreports.mjs project -p agent42Or install it globally with npm link and run ccreports.
Period reports (daily/weekly/monthly/project) include a Sessions column:
the sessions active in that period. A session that spans two days counts in
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.
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),
Total Tokens and Cost; in --compact layout Input is all input-side
tokens. Tool and skill rows leave the uncached Input column empty: results
always arrive through the cache. The summary's Tools, MCP servers and Skills
tables add Input (est.), Output (est.), Tokens (est.) and Cost
(est.); the Subagents table shows exact Input and Output. The logs record usage per request only, so
for tools and skills this is reconstructed (shown with ~):
- the tool input the model wrote counts as output tokens;
- the result is what it adds to the context of the next request. In a tool
loop that is measured:
context(next) − context(this) − output(this), split over parallel calls by result length. When a human message or compaction sits in between, or for a skill typed as a command, it is estimated from the text length at a characters-per-token ratio calibrated on the measured turns (about 2.2–2.4 in practice); - input and result are then re-sent with every later request of that conversation until it ends or is compacted - these re-reads (cache reads) are usually most of it;
- cost prices the input as output tokens, the first inclusion as a cache write and the re-reads as cache reads, at the model of the request.
A model-invoked skill is its Skill call plus the skill content it loads.
Subagent rows are exact: all tokens of that type's own transcripts. Items are
counted in the period of the call, even when re-reads happen later.
Context size is the full prompt of a request: input + cache write + cache read tokens (output excluded). Only main-conversation requests count, since subagents run in their own context window.
| Report | Max Context | Avg column |
|---|---|---|
session |
the session's peak | Avg Context: its average request |
| others + summary | the largest peak of any session | Avg Max Context: session peaks averaged |
ccreports adoption is modelled on GitHub Copilot's adoption cohorts, with
your sessions as the unit. Each session lands in the first phase that fits:
| Phase | Rule |
|---|---|
| Chat | no code edits and no PR |
| Phase 3 · Multi-agent | 2+ subagents, a background agent, a worktree, or agents messaging each other |
| Phase 2 · Agent-first | 10+ tool calls per prompt you typed |
| Phase 1 · Assisted | everything else that changed code |
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 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
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:
- conventional commit messages and PR titles the session wrote (
fix:,feat:,refactor:,docs:,chore:, ...), - review commands (
/code-review,/review,/security-review), - words in the session title, then the git branch prefix (
fix/,feature/, ...), then the first prompt, - 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:
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: claudeThe /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.
node bin/ccreports.mjs adoption -s 20261001 -f html -o adoption.html
node bin/ccreports.mjs -s 20261001 --adoption -f html -o report.html # summary + adoption--adoption (-a) appends the assessment to any report: the written
assessment goes on top, the adoption tables after the report's own. In JSON
it adds an adoption object.
ccreports recommendations (or -r on any report) checks your usage for
patterns worth changing. A recommendation only appears when the data clearly
shows the pattern; each comes with its evidence, what to do, and, where it can
be priced, the cost at stake (amounts overlap). Impact is the share of cost at
stake: high from 15%, medium from 5%.
| Fires when | Recommends |
|---|---|
| ≥25% of cost comes from requests with >200k tokens of context | new session or /clear per task, /compact with a focus |
| a tool's results take ≥10% of all tokens, or ≥200k tokens per call | tool-specific levers the user controls: quiet scripts, CLAUDE.md guidance, output caps (bashOutputMaxChars, CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, MAX_MCP_OUTPUT_TOKENS), PostToolUse hooks, subagents, lean skills |
| main-session Read/Grep/Glob take ≥12% of tokens while subagents do <25% | delegate exploration to an Explore subagent |
| subagents run on Opus/Fable and Sonnet 5.5 would save ≥$1 and ≥10% | model: sonnet / haiku for routine agents, CLAUDE_CODE_SUBAGENT_MODEL for built-in ones (repriced savings shown) |
| ≥3 sessions (or ≥10%) hit compaction | split tasks, compact yourself at natural breaks |
| ≥3 cache misses in main conversations, costing ≥3% more than cache reads would | per cause: expired (pause longer than the 5-minute / 1-hour cache) → /compact or /clear before continuing after a break, promptCacheTtl; invalidated (no pause, the start of the prompt changed) → keep the tool set stable (matters when tool search is off); model switch → pick the model at the start. Misses right after a compaction are left out |
| ≥30% of coding sessions are Assisted | hand over whole tasks, plan mode, skills |
| background agents and worktrees in <10% of sessions; skills in <10% | parallel subagents, worktrees (isolation: worktree, claude -w); recurring workflows as skills |
| a hook failed ≥10 times and in ≥50% of its runs | fix paths / interpreters or remove the hook from its settings file (with a sample error) |
node bin/ccreports.mjs recommendations -s 20261001
node bin/ccreports.mjs -s 20261001 -a -r -f html -o report.html # summary + adoption + recommendations| Format | Notes |
|---|---|
table |
Box-drawn terminal tables. Colors only on a TTY; cache columns hidden below 120 columns or with --compact. |
json |
Every bucket with all tools, MCP servers, skills, commands, hooks, models and subagent types (not limited by --top). |
markdown |
GitHub-flavored tables, one ## heading per summary section; breakdown sub-rows included. |
csv |
Raw numbers (no separators, $ or %; cost to 4 decimals). The summary is several tables separated by blank lines; breakdown sub-rows are left out. |
html |
Self-contained page (no external assets), light/dark aware, share columns drawn as bars, sortable columns. |
node bin/ccreports.mjs -s 20261001 -f html -o usage.html
node bin/ccreports.mjs monthly -f csv -o monthly.csv
node bin/ccreports.mjs weekly -b -f md >> REPORT.mdWarnings (unpriced models, built-in prices) go to stderr, so redirected output stays clean.
A report written with -o opens in the app your system associates with the
file - the browser for HTML, Excel for CSV, your editor for Markdown or JSON -
when you run ccreports from a terminal; scripts, CI (CI set) and agents
don't open anything unless they pass --open. ccreports -f html --open
writes to a temp file and opens it in one step. CSV files start with a UTF-8
byte order mark so Excel shows non-ASCII characters correctly.
| Option | |
|---|---|
-s, --since / -u, --until |
Date range, YYYYMMDD or YYYY-MM-DD (inclusive) |
-p, --project <text> |
Filter on project path (case-insensitive substring) |
-b, --breakdown |
Per-row tool / skill / command sub-rows |
-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 |
-o, --output <file> |
Write to a file instead of stdout; run from a terminal, the file then opens in its associated app |
--open |
Open the report in its associated app (browser, Excel, editor); without -o it goes to a temp file |
--no-open |
Don't open the file written with -o |
--order asc|desc |
Row order |
--timezone <tz> |
Timezone for date grouping |
--no-cost |
Skip cost estimates |
--offline |
Use cached (or built-in) pricing; never fetch |
--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, cursor or all - see GitHub Copilot and 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 |
--source copilot reports GitHub Copilot instead, from the session logs in
~/.copilot/session-state/<id>/events.jsonl. The Copilot CLI writes them,
and so does Copilot's agent in VS Code. --source all combines both tools in
one report. Every report works for Copilot, including recommendations.
node bin/ccreports.mjs --source copilot # summary
node bin/ccreports.mjs weekly -b --source copilot
node bin/ccreports.mjs --source all -a -f html -o both.htmlHow the Copilot logs map onto the reports:
- Tokens. Recent Copilot versions log usage per request
(
session.usage_record). Older sessions only have totals per model for each run, written at shutdown. These count as that many requests, at the time of shutdown, and have no context size. Sessions that never shut down cleanly have no token counts. Copilot's input tokens include cached tokens, so the cached tokens are subtracted to match Claude's Input column. - Cost is what Copilot billed in AI credits (1 AIU = $0.01). Requests without AI credits are priced at Claude API rates when the model is a Claude model; other models (GPT and local ones) are reported as unpriced. The summary also shows the premium requests used.
- Tools keep Copilot's names (
view,powershell,apply_patch, …). MCP tools are namedmcp__<server>__<tool>.taskcalls are subagent launches.-xbreaks downpowershell/bashcommands. - Tokens per tool are estimates, as for Claude Code. Copilot logs few requests that can be measured, and it trims old tool output, so a session's estimates are scaled down to at most its total input. Cost (est.) is the matching share of what the session was billed. Sessions without token counts get no estimates.
- Skills, slash commands, hooks, compactions and prompts come from their
own events. Hooks are named by event (
PreToolUse), since Copilot doesn't log the command. Pull requests are the PR links in the output ofgh pr createor acreate_pull_requestMCP call. - Installed plugins come from
installedPluginsin~/.copilot/config.json, with the enabled state fromenabledPluginsinsettings.json. A plugin's skills count whether Copilot logs them asplugin:skillor by the skill's own name. Copilot logs hooks by event, so plugin hook runs stay 0. With--source allthe 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,
custom agents (.github/agents/), skills, the explore agent, /compact,
/clear, /context, /model, /mcp, and plan mode and autopilot. Some
checks work differently for Copilot:
- Long contexts and prompt-cache rebuilds use only the requests logged one by one. Shutdown totals have no context size.
- Delegating exploration is judged by the share of sessions that launched a subagent. Older Copilot logs count subagents' tokens as the main session's, so token shares can't show delegation.
- The step-by-step coding check also says how many coding sessions used plan mode and autopilot.
- Cheaper models for subagents is skipped, since Copilot bills at its own rates and premium-request multipliers.
- Running work in parallel looks at background agents only, since Copilot has no worktree isolation.
- Failing hooks: a hook that errors counts as failed, even though Copilot also denies the tool call it guarded.
With --source all, each product gets its own recommendations, weighed
against its own cost, and in JSON every recommendation has a source.
--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.
node bin/ccreports.mjs --source cursor # summary
node bin/ccreports.mjs session --source cursor
node bin/ccreports.mjs adoption --source cursorActivity 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 throughCallDynamicToolcount under their own name; those outside Cursor's namespace count as MCP tools (mcp__<server>__<tool>).-xbreaks downShellcommands. Edits areWrite,Edit,StrReplace,MultiEditandDelete.SwitchModeandCreatePlanmark plan mode. - Skills you invoke come from the skill block Cursor attaches to your
message (
/githubin the CLI, or picked in the editor). Skills the agent uses areReadcalls on aSKILL.mdin a skills folder Cursor loads from, such as.cursor/skills,.claude/skillsor.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.
- 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,chatfor 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.
For Claude Code; GitHub Copilot and Cursor are described in their own sections above.
-
Tokens –
usagefrom each assistant message, deduplicated permessage.id + requestId. One API response is written as several lines, and resumed sessions copy earlier history, so naive summing overcounts. Totals matchccusage. -
Tools – every
tool_useblock, deduplicated by tool-use id. MCP tools (mcp__<server>__<tool>) are also rolled up per server. -
Skills – two sources, reported separately:
- by model:
Skilltool calls; - by user: a slash command followed by the skill's content
(
Base directory for this skill: …).
Directory scopes like
.claude/worktrees/x:planare normalized toplan. - by model:
-
Shell commands (
--shell) – the programs aBashorPowerShellcall ran: the first word of every pipeline stage,&&/;list element,$( … )subshell and PowerShell script block. Quoted text, heredocs, here-strings and comments are not split, so inline code (python -c "…",cat <<EOF) is not counted; nor are variables, keywords, PowerShell values and members ($x = …,.Count,[IO.File]::…) or functions the command defines itself. Paths are reduced to the program (C:\…\git.exe→git) and PowerShell names are case-insensitive. A call running several programs counts once for each. Reports group them by purpose (search & read files, change directory, text & data processing, print output, files, Git & GitHub, build / run / test, cloud & network, processes & system, other): Calls counts a call once per purpose, so Share (of that tool's calls) adds up to more than 100%. Tokens (est.) and Cost (est.) are the call's estimate (see Tokens per tool above) split evenly over its programs and over its purposes, so they add up to the tool's total instead of double counting; acd/Set-Locationprints nothing and only gets tokens when the call ran nothing else. The Commands column shows each program's calls and~tokens. JSON output always includesshellCommands(per program, with its category) andshellCategories, both with tokens and cost. -
Slash commands – user messages containing
<command-name>, including built-ins like/clearand/model. A user-typed skill counts both as a command and as a skill. -
Hooks – the
hook_*attachments Claude Code writes per hook run, deduplicated by uuid and grouped by command. The summary's Hooks table shows the events each hook ran on, runs, Failed (non-blocking errors: the hook crashed or exited non-zero), Blocked (exit code 2, the hook stopped the action on purpose), average and total duration, and Context (est.): tokens the hook added to the conversation (additionalContext, and a blocking hook's stderr), estimated from the text length and counted once, without re-reads. Successful runs are only logged by some Claude Code versions and hook types, so Runs can undercount hooks that succeed. -
Installed plugins – a table at the end of every report, not from the transcripts but from
plugins/installed_plugins.jsonnext to the projects directory: one row per install with marketplace, version, scope (user, project or local, with the project path), Enabled (theenabledPluginssetting of that scope's settings file; blank when not set) and last update. The usage columns count the plugin's skill calls (plugin:skill), slash commands (/plugin:cmd), subagent launches (plugin:agent), MCP calls (servers namedplugin_<plugin>_<server>) and runs of the hooks in itshooks.json, within the selected period. Usage is per plugin, so two installs of one plugin show the same numbers. Plugins that were never used sort last.--projectkeeps user-scope installs and those of matching projects. JSON output has them underplugins. -
Subagents –
<session>/subagents/*.jsonlis included and attributed to the parent session. The summary's Subagents table splits requests, tool calls, tokens and cost by subagent type (from each transcript's.meta.json), next to a(main session)row; Launches countsAgenttool calls by requestedsubagent_type. The Agents column in period reports is the number of launches. -
Usage limits – the error message Claude Code writes when a plan's usage limit stops a request (
isApiErrorMessage,error: "rate_limit",apiError: "usage_limit_reached"), deduplicated by uuid. The limit type (5-hour, weekly, weekly Opus / Sonnet, extra usage) and reset time come from itsrate_limit_info, or from the message text in versions that don't log them; older versions'Claude AI usage limit reached|<reset>and team or enterprise spend limits count too. Short capacity 429s that Claude Code retries on its own (apiErrorIsTransient) are not usage limits. When a limit was hit, the summary and period reports add a Usage limits table (hits, sessions, last hit, median time to reset) and a summary line; JSON output always hasusageLimits. For Copilot:session.errorevents of typequota(premium requests used up) andrate_limit. Cursor logs no errors. -
Cost – estimated per request at Claude API list prices, parsed from Anthropic's pricing page and cached for 24h in
%LOCALAPPDATA%\ccreports/~/.cache/ccreports; falls back to the cache, then a built-in snapshot of the page. Applied as the page describes:- 5-minute and 1-hour cache writes and cache reads at each model's own rate;
- Haiku 5.5's higher prices when a request's prompt (input + cache reads and writes) is over 100k tokens;
- fast-mode prices when
usage.speedisfast(cache multipliers on top); - 1.1× for US-only inference (
usage.inference_geo=us); - web searches at $10 per 1,000.
Models without a price count as $0 and are reported on stderr. These are API list prices, so on a subscription plan they show what the usage would cost, not what you pay; Batch discounts and Bedrock / Vertex pricing don't apply to Claude Code sessions and aren't modeled.
The transcript format is undocumented and changes between Claude Code versions;
the parser ignores line types it doesn't know. Claude Code deletes transcripts
older than cleanupPeriodDays (default 30), so history is limited to that window.
npm testnpm version patch # or minor / major: bumps package.json and .claude-plugin/plugin.json, commits, tags
git push --follow-tagsPushing the v* tag runs the Publish workflow, which checks the versions
match, runs the tests and publishes to npm with provenance via trusted
publishing (no token involved), then creates the GitHub release with
generated notes (edit them on GitHub to describe the release). Plugin users
get the new version from the marketplace on update.