{
  "markdown": "# copilot-session-usage\n\n[![CI](https://github.com/gsemet/copilot-session-usage/actions/workflows/ci.yml/badge.svg)](https://github.com/gsemet/copilot-session-usage/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/gsemet/copilot-session-usage)](https://codecov.io/gh/gsemet/copilot-session-usage)\n[![PyPI](https://img.shields.io/pypi/v/copilot-session-usage)](https://pypi.org/project/copilot-session-usage/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/copilot-session-usage)](https://pypi.org/project/copilot-session-usage/)\n[![Docs](https://readthedocs.org/projects/copilot-session-usage/badge/?version=stable)](https://copilot-session-usage.readthedocs.io/en/stable/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type checked](https://img.shields.io/badge/type%20checked-mypy%2Fty-blue.svg)](./)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nExtract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.\n\n**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)\n\n## Chronicle and copilot-session-usage\n\nGitHub Copilot provides **Chronicle** session tools for conversational access to your\nCopilot history. Chronicle and this project are complementary, but they answer different\nquestions.\n\n### What Chronicle is good at\n\nUse Chronicle when you want to:\n\n- Find a past session by its title or session ID.\n- Search or summarize what happened in a session.\n- Inspect conversational history, checkpoints, referenced files, and session metadata.\n- Get a quick, conversational summary of aggregate session KPIs when cost analysis is\n  available in the current Copilot environment.\n\n### What Chronicle is not designed to provide\n\nChronicle's session store is not a token-accounting database. Its stored session records\ncontain history and metadata, but do not expose a standard set of per-request pricing\nfields. A Chronicle cost answer may therefore provide an aggregate estimate and a list of\nmodels without providing a reproducible split of tokens and dollars by model or subagent.\n\n### What this project adds\n\n`copilot-session-usage` reads the original VS Code Copilot debug logs and turns them into\nrepeatable reports. It provides:\n\n| Need | Chronicle | `copilot-session-usage` |\n| --- | --- | --- |\n| Conversational search and summaries | ✅ | ✅ CLI reports are interpreted by your agent |\n| Session discovery by title or ID | ✅ | ✅ |\n| Aggregate tokens | ✅  | ✅ |\n| Aggregate estimated cost | ⚠️ When available; aggregate only | ✅ |\n| Tokens **per model** | ⚠️ LLM digging each time; consumes tokens | ✅ |\n| Estimated cost (`$`) **per model** | ❌ No accurate cost per breakdown | ✅ |\n| Tokens **per subagent** | ⚠️ LLM digging each time; consumes tokens | ✅ |\n| Estimated cost (`$`) **per subagent** | ❌ No accurate cost per breakdown | ✅ |\n| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ |\n| Tool-call counts by skill and subagent | ⚠️ LLM digging each time | ✅ |\n| Batch analysis, filtering, and aggregation | Limited/conversational | ✅ |\n| Stable JSON, table, and detailed output | No stable contract | ✅ |\n| Python API for embedding in third-party tools | ❌ | ✅ |\n| Pricing provenance and custom model rates | ⚠️ Only for aggregated costs | ✅ |\n| Git commit cost trailers | ❌ | ✅ |\n\nIn the table, `⚠️` means that Chronicle may answer the question in a particular\nenvironment or with additional analysis, but does not guarantee a stable, reproducible\nbreakdown for it.\n\nUse Chronicle for **“What did I do?”** and use this project for **“How much did it cost,\nwhich model or subagent consumed it, and can I export the evidence?”**\n\n## Installation\n\n```bash\nuv tool install copilot-session-usage\n```\n\n## Quick start\n\n```bash\n# Analyze the most recent session\ncopilot-session-usage latest\n\n# Analyze a specific session by its debug-log directory\ncopilot-session-usage analyze /path/to/session/debug-logs\n\n# List recent sessions (metadata only)\ncopilot-session-usage list\n\n# Batch analyze the last 10 sessions\ncopilot-session-usage batch 10\n\n# Aggregate cost across all sessions matching a PRD path\ncopilot-session-usage analyze --name \"PRD: /path/to/prd\" --aggregate --format table\n\n# List sessions in a debug-logs folder with cost columns\ncopilot-session-usage list --dir /path/to/debug-logs --format table\n```\n\n## Features\n\n- **Token-level cost estimation** — per-model pricing with cache-hit discounts\n- **Multi-model sessions** — correctly handles sessions that call multiple models (e.g. Claude + Kimi)\n- **Threshold-aware pricing** — long-context tier switching (e.g. GPT-5.4 > 272k tokens)\n- **Subagent cost attribution** — tracks `runSubagent` calls and their token usage\n- **Cross-platform** — macOS, Linux, Windows, WSL2\n- **Three output formats** — `json` (default), `table`, `detailed`\n- **Three detail levels** — `minimal`, `compact`, `full`\n- **JSON and table output** — machine-readable or human-friendly\n- **Session filtering** — regex match by name, date-range filtering\n- **Aggregation** — roll up costs across many sessions in one command\n- **Skill-aware cost attribution** — detect skills, attribute LLM and tool calls to the active skill\n- **Skill cost breakdown** — per-skill token counts and estimated cost\n- **Tool-call attribution** — per-skill/per-subagent tool-call counts\n- **Title filtering** — find sessions by title substring\n- **Efficiency summaries** — cache ratio, model split, cost per 1M tokens\n- **Field extraction** — pull specific values with `--query`\n\n## How it works\n\n`copilot-session-usage` reads VS Code Copilot debug logs stored in\n`~/Library/Application Support/Code/User/workspaceStorage/` (macOS),\n`%APPDATA%\\Code\\User\\workspaceStorage\\` (Windows), or\n`~/.config/Code/User/workspaceStorage/` (Linux).\n\nEach session directory contains a `GitHub.copilot-chat/debug-logs/` folder with\nJSONL files. The tool parses these files, extracts token counts per model,\napplies per-model pricing (including cache-hit discounts and long-context tier\nswitching), and estimates the session cost in USD.\n\nSubagent calls (`runSubagent`) are tracked separately so you can see how much\ntoken usage was delegated to helper agents.\n\n## Knowledge base\n\nThis project includes an OKF knowledge bundle in `knowledge/` with structured\nguidelines for contributors. Validate it with:\n\n```bash\njust knowledge-validate\n```\n\n## Usage\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `analyze [PATH]` | Analyze one session by PATH, or many by `--name` regex |\n| `latest` | Analyze the most recently modified session |\n| `find TITLE` | Find and analyze a session by title (case-insensitive substring match) |\n| `id SESSION_ID` | Analyze a session by exact UUID |\n| `list` | List recent sessions (metadata only by default) |\n| `batch N` | Analyze the N most recent sessions in one pass |\n| `skills` | List skills used across sessions with aggregated cost |\n\n### Analysis options\n\n| Option | Description |\n|--------|-------------|\n| `--name REGEX` | Filter sessions by title/ID regex (case-insensitive) |\n| `--title SUBSTRING` | Filter sessions by title substring (case-insensitive) |\n| `--since DATE` | Only sessions created after DATE (ISO 8601 with timezone) |\n| `--until DATE` | Only sessions created before DATE (ISO 8601 with timezone) |\n| `--workspace PATH` | Only sessions from this workspace folder |\n| `--aggregate` | Aggregate all matching sessions into one summary |\n| `--summary` | Output a cost-efficiency summary |\n| `--skill-breakdown` | Emit a per-skill cost breakdown |\n| `--tool-breakdown` | Emit a per-skill/per-subagent tool-call count breakdown |\n| `--skill NAME` | Filter the report to a single skill |\n| `--query PATH` | Extract a single field with dot notation |\n| `--query-help` | Print all `--query` field paths |\n\n### Global options\n\n| Option | Description |\n|--------|-------------|\n| `--workspace-storage PATH` | Override workspaceStorage directory (auto-detected by default) |\n| `--agent {vscode,cli}` | Provider to use (`cli` not yet implemented) |\n| `--detail {minimal,compact,full}` | Detail level (default: `compact`) |\n| `--format {json,table,detailed}` | Output format (default: `json`) |\n| `--output PATH` | Write output to file instead of stdout |\n\n### Examples\n\n```bash\n# Full detail for the latest session\n$ copilot-session-usage latest --detail full\n{\n  \"session_id\": \"f5cbde8a-ec40-466f-86e6-f95c343b6c58\",\n  \"session_dir\": \"/Users/az02065/Library/Application Support/Code/User/workspaceStorage/c016ff4fabbe9f918719a00c9c741058/GitHub.copilot-chat/debug-logs/f5cbde8a-ec40-466f-86e6-f95c343b6c58\",\n  ...\n}\n\n# JSON output for a specific session\n$ copilot-session-usage analyze /path/to/debug-logs --format json --output report.json\n\n# Find sessions containing \"implem\" in the title\n$ copilot-session-usage find \"implem\"\nMultiple sessions match 'implem':\n  2026-07-01T21:15:12Z  'Implement copilot-session-usage spec'  (id: c890dd60-43d6-44f0-b57c-ab505dfa003b)\n  2026-06-26T18:21:21Z  'Resume PRD implementation'  (id: 9368ab3e-1c93-4125-8271-d5bd024b057a)\n  2026-06-26T09:19:52Z  'Resume Workflow PRD implementation'  (id: 1214eb3f-add0-41a5-84d4-88720218e60e)\n...\n\n# Get summary for a given session (found by `find`)\n$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --format table\nSession:   19e03be0-9cfa-4f21-a19a-4bdb754b3965\nTitle:     Implementation of new feature X\nStarted:   2026-07-01T20:37:34Z\nDuration:  40588s  (active: 1083s)\nModels:    claude-sonnet-4.6, claude-haiku-4.5, Kimi-K2.6-azure\nInput:     1,425,790 tokens\nOutput:    22,166 tokens\nCached:    1,224,340 (86%)\nLLM calls: 28\nEst. cost: $1.0880\n# Per-skill cost breakdown\n$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --skill-breakdown --format table\nPer-Skill Breakdown:\n  Skill                              Input      Cached  Output  Calls     Cost\n  ----------------------------------------------------------------------------\n  /compendium-generic get-session-costs  1,137,864  1,015,825  15,729     24  $0.3636\n\n# Per-skill/per-subagent tool-call counts\n$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --tool-breakdown --format table\nTool Breakdown:\n  Tool                          Calls  Skill                         Subagent\n  ---------------------------------------------------------------------------\n  read_file                        25  /compendium-generic get-session-costs  main\n  vscode_askQuestions               3  /compendium-generic get-session-costs  main\n  runSubagent                       1  /compendium-generic get-session-costs  main\n\n# Concise skill cost (great for scripts)\n$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 \\\n    --skill \"/compendium-generic get-session-costs\" \\\n    --format json --detail minimal\n{\n  \"skill\": \"/compendium-generic get-session-costs\",\n  \"cost_usd\": 0.3636,\n  \"input_tokens\": 1137864,\n  \"output_tokens\": 15729,\n  \"cached_tokens\": 1015825,\n  \"llm_calls\": 24\n}\n\n# List skills used across the last 7 days\n$ copilot-session-usage skills --last 7d --format table\nSkills across 23 sessions:\n  Skill                              Sessions        Input     Output       Cached   Calls       Cost\n  ---------------------------------------------------------------------------------------------------\n  /compendium-generic get-session-costs       3    1137864      15729      1015825      24  $0.3636\n\n# Filter sessions by title substring\n$ copilot-session-usage list --title \"get-session-costs\"\n$ copilot-session-usage analyze --title \"grill-me\" --latest\n# Batch analyze last 5 sessions since July 1st\ncopilot-session-usage batch 5 --since 2026-07-01\n\n# Aggregate all PRD-related sessions from the last week\ncopilot-session-usage analyze \\\n  --name \"PRD: /path/to/prd\" \\\n  --since 2026-06-30T00:00:00Z \\\n  --until 2026-07-07T00:00:00Z \\\n  --aggregate \\\n  --format table\n\n# Cost-efficiency summary for a single session\ncopilot-session-usage analyze /path/to/debug-logs --summary --format table\n\n# Extract just the total cost from a session\ncopilot-session-usage analyze /path/to/debug-logs --query .total.estimated_usd\n\n# WSL2: point to Windows host workspaceStorage\ncopilot-session-usage latest \\\n  --workspace-storage /mnt/c/Users/$USER/AppData/Roaming/Code/User/workspaceStorage\n```\n\n## Python API\n\n```python\nfrom pathlib import Path\n\nfrom copilot_session_usage.api import (\n    analyze_session,\n    analyze_latest,\n    batch_analyze,\n    aggregate_sessions,\n    list_sessions,\n)\n\n# Analyze a session by path\nresult = analyze_session(Path(\"/path/to/debug-logs\"), detail=\"full\")\n\n# Analyze the most recent session\nresult = analyze_latest(detail=\"compact\")\n\n# Batch analyze the last 10 sessions\nbatch = batch_analyze(10, detail=\"minimal\")\n\n# Aggregate multiple full analyses into one efficiency summary\naggregate = aggregate_sessions([result1, result2])\n\n# List sessions with regex and date-range filtering\nsessions = list_sessions(\n    name_pattern=r\"PRD\",\n    since=\"2026-07-01T00:00:00Z\",\n    until=\"2026-07-07T00:00:00Z\",\n)\n```\n\n## Development\n\n```bash\n# Install dependencies\njust dev\n\n# Run tests\njust test\n\n# Run full validation\njust preflight\n\n# Build docs\njust docs\n\n# Serve docs with auto-reload\njust docs-serve\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 13442,
  "sha": "6fcc670abaf2d465a39b112e19839c35bc78fba5ba68fa2b0665f9f4a54de5e0",
  "repo_slug": "gsemet/copilot-session-usage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_gsemet_copilot_session_usage_knowledge_i_a39144e6/readme"
}