knowledge
Bundle OKF 0.1 · 8 conceitos · gsemet/copilot-session-usage
Open source Repository Open in the app JSON README (API)
About
# knowledge
- [concepts](./concepts/) — A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowled...
- [experiments](./experiments/) — A reusable, prepared procedure designed to test a Hypothesis and produce empirical Findings. Each execution yields on...
- [findings](./findings/) — A raw, dated, falsifiable observation recorded by an agent or human at a specific point in time. Findings are the ato...
- [guides](./guides/) — A reproducible, step-by-step workflow or procedure that produces a specific result given the current understanding of...
- [ideas](./ideas/) — A stable, well-understood idea that explains "what is this." Concepts are the semantic building blocks of the knowled...
- [principles](./principles/) — A durable, normative statement agreed upon by humans — "we always…", "never…", "must…". Principles include rules, con...
- [reference](./reference/) — An external source document — scientific papers, API specificat
Details
- Kind
- OKF bundles
- Topic
- Government & public data
- Publisher
- gsemet
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-09-05T19:06:05Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 22:08:51
- Updated
- 2026-09-08 22:08:51
- Origin id
gsemet/copilot-session-usage:knowledge/index.md
README
# copilot-session-usage
[](https://github.com/gsemet/copilot-session-usage/actions/workflows/ci.yml)
[](https://codecov.io/gh/gsemet/copilot-session-usage)
[](https://pypi.org/project/copilot-session-usage/)
[](https://pypi.org/project/copilot-session-usage/)
[](https://copilot-session-usage.readthedocs.io/en/stable/)
[](https://github.com/astral-sh/ruff)
[](./)
[](https://opensource.org/licenses/MIT)
Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)
## Chronicle and copilot-session-usage
GitHub Copilot provides **Chronicle** session tools for conversational access to your
Copilot history. Chronicle and this project are complementary, but they answer different
questions.
### What Chronicle is good at
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.
### What Chronicle is not designed to provide
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.
### What this project adds
`copilot-session-usage` reads the original VS Code Copilot debug 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 | ⚠️ When available; aggregate only | ✅ |
| Tokens **per model** | ⚠️ LLM digging each time; consumes tokens | ✅ |
| Estimated cost (`$`) **per model** | ❌ No accurate cost per breakdown | ✅ |
| Tokens **per subagent** | ⚠️ LLM digging each time; consumes tokens | ✅ |
| Estimated cost (`$`) **per subagent** | ❌ No accurate cost per breakdown | ✅ |
| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ |
| Tool-call counts by skill and subagent | ⚠️ LLM digging each time | ✅ |
| 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 | ⚠️ Only for aggregated costs | ✅ |
| 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.
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?”**
## Installation
```bash
uv tool install copilot-session-usage
```
## Quick start
```bash
# 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
# 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
```
## Features
- **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 `runSubagent` calls and their token usage
- **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 cost breakdown** — per-skill token counts and estimated cost
- **Tool-call attribution** — per-skill/per-subagent tool-call counts
- **Title filtering** — find sessions by title substring
- **Efficiency summaries** — cache ratio, model split, cost per 1M tokens
- **Field extraction** — pull specific values with `--query`
## How it works
`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. The tool parses these 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.
Subagent calls (`runSubagent`) are tracked separately so you can see how much
token usage was delegated to helper agents.
## Knowledge base
This project includes an OKF knowledge bundle in `knowledge/` with structured
guidelines for contributors. Validate it with:
```bash
just knowledge-validate
```
## Usage
### Commands
| 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 |
| `skills` | List skills used across sessions with aggregated cost |
### Analysis options
| Option | Description |
|--------|-------------|
| `--name REGEX` | Filter sessions by title/ID regex (case-insensitive) |
| `--title SUBSTRING` | Filter sessions by title substring (case-insensitive) |
| `--since DATE` | Only sessions created after DATE (ISO 8601 with timezone) |
| `--until DATE` | Only sessions created before DATE (ISO 8601 with timezone) |
| `--workspace PATH` | Only sessions from this workspace folder |
| `--aggregate` | Aggregate all matching sessions into one summary |
| `--summary` | Output a cost-efficiency summary |
| `--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 |
### Global options
| Option | Description |
|--------|-------------|
| `--workspace-storage PATH` | Override workspaceStorage directory (auto-detected by default) |
| `--agent {vscode,cli}` | Provider to use (`cli` not yet implemented) |
| `--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 |
### Examples
```bash
# 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
Output: 22,166 tokens
Cached: 1,224,340 (86%)
LLM calls: 28
Est. cost: $1.0880
# 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/workspaceStorage
```
## Python API
```python
from pathlib import Path
from copilot_session_usage.api import (
analyze_session,
analyze_latest,
batch_analyze,
aggregate_sessions,
list_sessions,
)
# 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",
)
```
## Development
```bash
# Install dependencies
just dev
# Run tests
just test
# Run full validation
just preflight
# Build docs
just docs
# Serve docs with auto-reload
just docs-serve
```
## License
MIT — see [LICENSE](LICENSE).