Skip to content
ExpechoPublic

About

Report agentic coding tools lile Claude Code/GitHub Copilot tool, skill, slash-command, subagent, token and cost usage from local session logs

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

ccreports

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+.

Quick start

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).

Install as a Claude Code plugin

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.

Usage

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 agent42

Or 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

Adoption assessment

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:

  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:

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.

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.

Recommendations

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

Output formats

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.md

Warnings (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

GitHub Copilot

--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.html

How 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 named mcp__<server>__<tool>. task calls are subagent launches. -x breaks down powershell / bash commands.
  • 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 of gh pr create or a create_pull_request MCP call.
  • 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, 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.

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.

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.
  • 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

For Claude Code; GitHub Copilot and Cursor are described in their own sections above.

  • Tokens – usage from each assistant message, deduplicated per message.id + requestId. One API response is written as several lines, and resumed sessions copy earlier history, so naive summing overcounts. Totals match ccusage.

  • Tools – every tool_use block, deduplicated by tool-use id. MCP tools (mcp__<server>__<tool>) are also rolled up per server.

  • Skills – two sources, reported separately:

    • by model: Skill tool calls;
    • by user: a slash command followed by the skill's content (Base directory for this skill: …).

    Directory scopes like .claude/worktrees/x:plan are normalized to plan.

  • Shell commands (--shell) – the programs a Bash or PowerShell call 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; a cd / Set-Location prints nothing and only gets tokens when the call ran nothing else. The Commands column shows each program's calls and ~tokens. JSON output always includes shellCommands (per program, with its category) and shellCategories, both with tokens and cost.

  • Slash commands – user messages containing <command-name>, including built-ins like /clear and /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.json next to the projects directory: one row per install with marketplace, version, scope (user, project or local, with the project path), Enabled (the enabledPlugins setting 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 named plugin_<plugin>_<server>) and runs of the hooks in its hooks.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. --project keeps user-scope installs and those of matching projects. JSON output has them under plugins.

  • Subagents – <session>/subagents/*.jsonl is 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 counts Agent tool calls by requested subagent_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 its rate_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 has usageLimits. For Copilot: session.error events of type quota (premium requests used up) and rate_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.speed is fast (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.

Tests

npm test

Releasing

npm version patch          # or minor / major: bumps package.json and .claude-plugin/plugin.json, commits, tags
git push --follow-tags

Pushing 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.

About

Report agentic coding tools lile Claude Code/GitHub Copilot tool, skill, slash-command, subagent, token and cost usage from local session logs

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages