Extract Copilot session cost KPIs (tokens, estimated USD, model, duration) from local VS Code Copilot debug logs and/or local Copilot CLI/Copilot App session logs.
Full documentation: copilot-session-usage.readthedocs.io
You can: the logs are local JSONL. But every ad-hoc script re-learns the log
formats, and the plausible-looking answer is often wrong. This tool encodes the
rules once, is tested against them, and proves its own result on every run
(reconciliation block). An agent calls one command instead of spending tokens
on re-deriving, and possibly mis-deriving, the calculation.
How hard it is depends on the provider:
VS Code (--agent vscode) |
Copilot CLI / App (--agent cli) |
|
|---|---|---|
| Where the billed cost is | One event type (llm_request) carries the billed copilotUsageNanoAiu per call |
Spread over several event types: session.usage_record per call, session.compaction_complete for compactions, and cumulative session.shutdown / session.usage_checkpoint snapshots |
| Obvious script | Sum the per-call nanoAIU | Read the last shutdown snapshot |
| Is the obvious script right? | Total: mostly yes. Breakdowns still need care | No. Snapshots miss everything after the last shutdown, sessions that never shut down, and (inconsistently) compactions |
| Traps the tool handles | Errored requests without usage, free utility models, subagent files (runSubagent-*.jsonl), no cache-write count logged |
Dedup by accounting.usageId, compaction calls and their nested requestCount, per-agent skill timeline, utility models, sessions resumed long after creation |
| Value of the tool | Convenience and reproducible breakdowns (model, subagent, skill, time window) | Correct totals in the first place, plus the same breakdowns |
Pitfalls that affect both providers:
input_tokensalready includes cached and cache-written tokens. Addinginput + cacheddoubles the token count and halves "cost per token".- A cache ratio averaged per session is not the real one. Weight it by tokens.
- A time window must select calls by timestamp. Selecting sessions by creation date drops long-running sessions and counts calls outside the window.
- Recomputing from a price table needs the cache-write premium and the long-context tier per call. The tool uses the billed amount whenever it is logged, and keeps the price table as a cross-check.
Errors measured on ten days of real usage before these rules were in place:
| Mistake | Impact |
|---|---|
| CLI cost from the last shutdown snapshot | ~32% of the cost not attributed to any model, ~28% of input tokens missing |
| CLI compactions ignored | ~3% of the CLI cost missing |
input + cached as total tokens |
Token count ~2× too high |
| Unweighted cache ratio | 0.80 reported instead of 0.95 |
With the per-call pipeline, totals match an independent sum of billed amounts
to the micro-dollar on both providers. The token-based recomputation stays
within 0.2% (reconciliation.delta_pct).
GitHub Copilot provides Chronicle session tools for conversational access to your Copilot history. Chronicle and this project are complementary, but they answer different questions.
Use Chronicle when you want to:
- Find a past session by its title or session ID.
- Search or summarize what happened in a session.
- Inspect conversational history, checkpoints, referenced files, and session metadata.
- Get a quick, conversational summary of aggregate session KPIs when cost analysis is available in the current Copilot environment.
Chronicle's session store is not a token-accounting database. Its stored session records contain history and metadata, but do not expose a standard set of per-request pricing fields. A Chronicle cost answer may therefore provide an aggregate estimate and a list of models without providing a reproducible split of tokens and dollars by model or subagent.
copilot-session-usage reads the original VS Code Copilot debug logs and local
Copilot CLI/App event logs and turns them into repeatable reports. It provides:
| Need | Chronicle | copilot-session-usage |
|---|---|---|
| Conversational search and summaries | ✅ | ✅ CLI reports are interpreted by your agent |
| Session discovery by title or ID | ✅ | ✅ |
| Aggregate tokens | ✅ | ✅ |
| Aggregate estimated cost | ✅ | |
| Tokens per model | ✅ | |
Estimated cost ($) per model |
❌ No accurate cost per breakdown | ✅ |
| Tokens per subagent | ✅ | |
Estimated cost ($) per subagent |
❌ No accurate cost per breakdown | ✅ |
| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ Limited timeline attribution |
| Tool-call counts by skill and subagent | ✅ | |
| Batch analysis, filtering, and aggregation | Limited/conversational | ✅ |
| Stable JSON, table, and detailed output | No stable contract | ✅ |
| Python API for embedding in third-party tools | ❌ | ✅ |
| Pricing provenance and custom model rates | ✅ | |
| Git commit cost trailers | ❌ | ✅ |
In the table, ⚠️ means that Chronicle may answer the question in a particular
environment or with additional analysis, but does not guarantee a stable, reproducible
breakdown for it.
Skill token and cost attribution is limited: requests (VS Code) and calls (CLI/App, per agent) are grouped under the latest explicit skill invocation, including the whole request context and later work until another invocation. This is not an isolated measurement of tokens or cost caused by the skill; automatically loaded and overlapping skills cannot be separated. See Skill attribution.
Use Chronicle for “What did I do?” and use this project for “How much did it cost, which model or subagent consumed it, and can I export the evidence?”
copilot-session-usage supports two local session sources, selected explicitly
with --agent (default vscode):
vscode(default) — VS Code Copilot Chat debug logs.cli— Copilot CLI and Copilot App local sessions, stored under~/.copilot/session-state/<session-id>/events.jsonl. The macOS Copilot App runs a bundled Copilot CLI runtime and uses the same session-state layout.all— an explicit, opt-in combined mode that discovers and aggregates sessions from both providers, deduplicated by session UUID. Commands never mix providers unless--agent allis passed. Missing provider roots are ignored, including when both roots are absent.
Both providers feed one per-call pipeline: every LLM call becomes a
normalized record, and all totals, model rows, subagent rows and skill rows are
sums of those records (export them with copilot-session-usage calls). They
share the same model catalog, pricing data, cache rules, and estimated-USD
calculation. JSON reports carry "schema_version": 2. Missing evidence is
never turned into a fabricated zero: a CLI/App session with no usage records
yields null totals and a diagnostics entry.
This tool is the reference calculation. Scripts that re-derive costs from token
counts routinely get these wrong, so rely on span, calls and the
reconciliation block instead:
input_tokensincludes cache reads and cache writes.cached_tokensandcache_write_tokensare subsets;uncached_input_tokensis the remainder. Adding them up double-counts (the oldtotal_tokensfield was removed).- Cache writes are billed at a premium over the base input rate.
- VS Code logs no cache-write count (
cache_write_tokensisnull). - CLI compactions are separate events (
session.compaction_complete); they are included askind: "compaction"calls. - CLI shutdown snapshots are incomplete; they are used only for the
snapshot_usd/snapshot_delta_usdreconciliation check. - Utility models are free (
gpt-4o*,gpt-4.1*,gpt-5.4-nano*) and excluded from totals on both providers. - The long-context tier is chosen per call, from that call's input size.
Billed nanoAIU is used whenever logged (cost_source: "billed"); the price
table is only a fallback ("estimated"). Every session and span carries
reconciliation (billed_usd, estimated_from_tokens_usd, delta_pct,
calls_without_billing) to verify the formula. See
Don't recompute costs yourself.
Analysis is offline: pricing is never refreshed automatically. Run
copilot-session-usage pricing refresh to update it, or pass
auto_refresh=True in the Python API.
--since, --until and --last select calls by their own timestamp; a
session is kept only if it has an in-window call, and its totals count only
those calls.
# Analyze the latest Copilot CLI/App session
copilot-session-usage --agent cli latest
# Analyze a specific Copilot CLI/App session by its session-state directory
copilot-session-usage --agent cli analyze ~/.copilot/session-state/<uuid>
# List and aggregate sessions from both VS Code and Copilot CLI/App
copilot-session-usage --agent all list --format tableuv tool install copilot-session-usage# Analyze the most recent session
copilot-session-usage latest
# Analyze a specific session by its debug-log directory
copilot-session-usage analyze /path/to/session/debug-logs
# List recent sessions (metadata only)
copilot-session-usage list
# Batch analyze the last 10 sessions
copilot-session-usage batch 10
# Compact total/model/session report for a date span
copilot-session-usage --agent all span \
--since 2026-07-01T00:00:00Z \
--until 2026-07-08T00:00:00Z \
--format table
# Export every priced LLM call as JSONL (the building block of all totals)
copilot-session-usage --agent cli calls --last 7d --output calls.jsonl
# Aggregate cost across all sessions matching a PRD path
copilot-session-usage analyze --name "PRD: /path/to/prd" --aggregate --format table
# List sessions in a debug-logs folder with cost columns
copilot-session-usage list --dir /path/to/debug-logs --format table- Token-level cost estimation — per-model pricing with cache-hit discounts
- Multi-model sessions — correctly handles sessions that call multiple models (e.g. Claude + Kimi)
- Threshold-aware pricing — long-context tier switching (e.g. GPT-5.4 > 272k tokens)
- Subagent cost attribution — tracks
runSubagentcalls and their token usage - VS Code and Copilot CLI/App providers —
--agent vscode(default),--agent cli, or the opt-in combined--agent all - Cross-platform — macOS, Linux, Windows, WSL2
- Three output formats —
json(default),table,detailed - Three detail levels —
minimal,compact,full - JSON and table output — machine-readable or human-friendly
- Session filtering — regex match by name, date-range filtering
- Aggregation — roll up costs across many sessions in one command
- Skill-aware cost attribution — detect skills, attribute LLM and tool calls to the active skill
- Skill-source detection — inspect slash commands, discovery events, system prompts, and skill tools
- Skill cost breakdown — per-skill token counts and estimated cost (both providers)
- Tool-call attribution — per-skill/per-subagent tool-call counts
- Title filtering — find sessions by title substring
- Metadata cache — reuse session indexes until the workspace database changes
- Efficiency summaries — token-weighted cache ratio, model split, reconciliation of billed vs. token-formula cost
- Per-call export —
callsemits normalized JSONL records;list_calls/iter_callsin the API - Field extraction — pull specific values with
--query
copilot-session-usage reads VS Code Copilot debug logs stored in
~/Library/Application Support/Code/User/workspaceStorage/ (macOS),
%APPDATA%\Code\User\workspaceStorage\ (Windows), or
~/.config/Code/User/workspaceStorage/ (Linux).
Each session directory contains a GitHub.copilot-chat/debug-logs/ folder with
JSONL files plus optional system_prompt_*.json and tools_*.json artifacts.
The tool parses the JSONL files, extracts token counts per model, applies
per-model pricing (including cache-hit discounts and long-context tier
switching), and estimates the session cost in USD. Skill detection also reads
the optional system-prompt skill list and skill tool definitions. Those artifacts
identify available skills; only timestamped slash-command user messages drive
the active-skill attribution timeline.
Session metadata from state.vscdb is cached in a small local index keyed by
workspace hash. The index stores metadata only, never raw logs or message
content, and is invalidated when the source database mtime changes.
Subagent calls (runSubagent) are tracked separately so you can see how much
token usage was delegated to helper agents.
Copilot CLI and the Copilot App store one directory per session under
~/.copilot/session-state/<session-id>/ (override with --session-root).
Each session directory has a structured events.jsonl event log — the
primary evidence source — plus an optional workspace.yaml sidecar with
title, working directory, git branch, and timestamps.
copilot-session-usage also accepts an explicit session directory or a
relocated/exported events.jsonl file directly (for example
copilot-session-usage --agent cli analyze /path/to/exported/events.jsonl),
without requiring auto-discovery. An explicit source is only analyzed when it
contains recognizable Copilot CLI event records and a canonical session UUID
can be determined (from the directory name or a session.start event) —
otherwise it is rejected with an actionable error instead of being analyzed
with a fabricated identity.
Per-model token totals and cost come from the session's per-call records:
session.usage_record (one per LLM call, de-duplicated by accounting.usageId)
plus session.compaction_complete events (compactions, kind: "compaction").
Each call uses its billed totalNanoAiu when present, else the shared
token-based pricing with the exact cache-write count. The cumulative
session.shutdown/session.usage_checkpoint snapshots are incomplete and used
only for the reconciliation diagnostic (snapshot_usd, snapshot_delta_usd).
A session that never shut down is therefore fully analyzed; only a session with
no usage records and no compaction usage has null totals, with diagnostics
explaining why. Calls are attributed to the subagent (agentId) and active
skill of their own agent, so the CLI/App provider has a costed skills
breakdown. provider_usage keeps informational counters such as
total_premium_requests and resume_count. Parsing
tolerates unrecognized event types and schema versions other than the one
currently validated, recording a diagnostic instead of failing.
This project includes an OKF knowledge bundle in knowledge/ with structured
guidelines for contributors. Validate it with:
just knowledge-validate| Command | Description |
|---|---|
analyze [PATH] |
Analyze one session by PATH, or many by --name regex |
latest |
Analyze the most recently modified session |
find TITLE |
Find and analyze a session by title (case-insensitive substring match) |
id SESSION_ID |
Analyze a session by exact UUID |
list |
List recent sessions (metadata only by default) |
batch N |
Analyze the N most recent sessions in one pass |
span |
Emit a compact total, per-model, and per-session report (calls in the window) |
calls |
Export every priced LLM call as JSONL (one object per line) |
skills |
List skills used across sessions with aggregated cost |
| Option | Description |
|---|---|
--name REGEX |
Filter sessions by title/ID regex (case-insensitive) |
--title SUBSTRING |
Filter sessions by title substring (case-insensitive) |
--since DATE |
Only calls at or after DATE (ISO 8601 with timezone); sessions with no in-window call are dropped |
--until DATE |
Only calls at or before DATE (ISO 8601 with timezone) |
--last DURATION |
Rolling call window such as 7d, 24h, or 30m (span, skills, calls) |
--workspace PATH |
Only sessions from this workspace folder |
--aggregate |
Aggregate all matching sessions into one summary |
--summary |
Output a cost-efficiency summary |
--minimal |
Alias for --detail minimal on analysis commands |
--skill-breakdown |
Emit a per-skill cost breakdown |
--tool-breakdown |
Emit a per-skill/per-subagent tool-call count breakdown |
--skill NAME |
Filter the report to a single skill |
--query PATH |
Extract a single field with dot notation |
--query-help |
Print all --query field paths |
| Option | Description |
|---|---|
--workspace-storage PATH |
Override workspaceStorage directory (auto-detected by default). Used by --agent vscode/all |
--session-root PATH |
Override the Copilot CLI/App session-state root (default: ~/.copilot/session-state). Used by --agent cli/all |
--agent {vscode,cli,all} |
Provider for session discovery: vscode (default), cli, or the explicit opt-in combined mode all |
--detail {minimal,compact,full} |
Detail level (default: compact) |
--format {json,table,detailed} |
Output format (default: json) |
--output PATH |
Write output to file instead of stdout |
# Full detail for the latest session
$ copilot-session-usage latest --detail full
{
"session_id": "f5cbde8a-ec40-466f-86e6-f95c343b6c58",
"session_dir": "/Users/az02065/Library/Application Support/Code/User/workspaceStorage/c016ff4fabbe9f918719a00c9c741058/GitHub.copilot-chat/debug-logs/f5cbde8a-ec40-466f-86e6-f95c343b6c58",
...
}
# JSON output for a specific session
$ copilot-session-usage analyze /path/to/debug-logs --format json --output report.json
# Find sessions containing "implem" in the title
$ copilot-session-usage find "implem"
Multiple sessions match 'implem':
2026-07-01T21:15:12Z 'Implement copilot-session-usage spec' (id: c890dd60-43d6-44f0-b57c-ab505dfa003b)
2026-06-26T18:21:21Z 'Resume PRD implementation' (id: 9368ab3e-1c93-4125-8271-d5bd024b057a)
2026-06-26T09:19:52Z 'Resume Workflow PRD implementation' (id: 1214eb3f-add0-41a5-84d4-88720218e60e)
...
# Get summary for a given session (found by `find`)
$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --format table
Session: 19e03be0-9cfa-4f21-a19a-4bdb754b3965
Title: Implementation of new feature X
Started: 2026-07-01T20:37:34Z
Duration: 40588s (active: 1083s)
Models: claude-sonnet-4.6, claude-haiku-4.5, Kimi-K2.6-azure
Input: 1,425,790 tokens (incl. cache)
Output: 22,166 tokens
Cached: 1,224,340 (86%)
Uncached: 201,450
LLM calls: 28
Cost: $1.0880 (billed)
# Per-skill cost breakdown
$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --skill-breakdown --format table
Per-Skill Breakdown:
Skill Input Cached Output Calls Cost
----------------------------------------------------------------------------
/compendium-generic get-session-costs 1,137,864 1,015,825 15,729 24 $0.3636
# Per-skill/per-subagent tool-call counts
$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --tool-breakdown --format table
Tool Breakdown:
Tool Calls Skill Subagent
---------------------------------------------------------------------------
read_file 25 /compendium-generic get-session-costs main
vscode_askQuestions 3 /compendium-generic get-session-costs main
runSubagent 1 /compendium-generic get-session-costs main
# Concise skill cost (great for scripts)
$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 \
--skill "/compendium-generic get-session-costs" \
--format json --detail minimal
{
"skill": "/compendium-generic get-session-costs",
"cost_usd": 0.3636,
"input_tokens": 1137864,
"output_tokens": 15729,
"cached_tokens": 1015825,
"llm_calls": 24
}
# List skills used across the last 7 days
$ copilot-session-usage skills --last 7d --format table
Skills across 23 sessions:
Skill Sessions Input Output Cached Calls Cost
---------------------------------------------------------------------------------------------------
/compendium-generic get-session-costs 3 1137864 15729 1015825 24 $0.3636
# Filter sessions by title substring
$ copilot-session-usage list --title "get-session-costs"
$ copilot-session-usage analyze --title "grill-me" --latest
# Batch analyze last 5 sessions since July 1st
copilot-session-usage batch 5 --since 2026-07-01
# Aggregate all PRD-related sessions from the last week
copilot-session-usage analyze \
--name "PRD: /path/to/prd" \
--since 2026-06-30T00:00:00Z \
--until 2026-07-07T00:00:00Z \
--aggregate \
--format table
# Cost-efficiency summary for a single session
copilot-session-usage analyze /path/to/debug-logs --summary --format table
# Extract just the total cost from a session
copilot-session-usage analyze /path/to/debug-logs --query .total.estimated_usd
# WSL2: point to Windows host workspaceStorage
copilot-session-usage latest \
--workspace-storage /mnt/c/Users/$USER/AppData/Roaming/Code/User/workspaceStoragefrom pathlib import Path
from copilot_session_usage.api import (
analyze_session,
analyze_latest,
batch_analyze,
aggregate_sessions,
list_sessions,
list_calls,
)
# Analyze a session by path
result = analyze_session(Path("/path/to/debug-logs"), detail="full")
# Analyze the most recent session
result = analyze_latest(detail="compact")
# Batch analyze the last 10 sessions
batch = batch_analyze(10, detail="minimal")
# Aggregate multiple full analyses into one efficiency summary
aggregate = aggregate_sessions([result1, result2])
# List sessions with regex and date-range filtering
sessions = list_sessions(
name_pattern=r"PRD",
since="2026-07-01T00:00:00Z",
until="2026-07-07T00:00:00Z",
)
# Analyze a Copilot CLI/App session, or discover/aggregate across all
# providers with the explicit opt-in agent="all"
cli_result = analyze_session(Path("~/.copilot/session-state/<uuid>"), agent="cli")
combined = list_sessions(agent="all")
# Normalized per-call records (calls filtered by timestamp)
calls = list_calls(agent="cli", since="2026-07-01T00:00:00Z")# Install dependencies
just dev
# Run tests
just test
# Run full validation
just preflight
# Build docs
just docs
# Serve docs with auto-reload
just docs-serveMIT — see LICENSE.