copilot-session-usage 0.1.0__py3-none-any.whl

copilot_session_usage-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: copilot-session-usage
+Version: 0.1.0
+Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
+Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
+Project-URL: Documentation, https://copilot-session-usage.readthedocs.io
+Project-URL: Repository, https://github.com/gsemet/copilot-session-usage
+Project-URL: Issues, https://github.com/gsemet/copilot-session-usage/issues
+Author-email: Gaetan Semet <gaetan@xeberon.net>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Description-Content-Type: text/markdown
+
+# copilot-session-usage
+
+[![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)
+[![Coverage](https://img.shields.io/codecov/c/github/gsemet/copilot-session-usage)](https://codecov.io/gh/gsemet/copilot-session-usage)
+[![PyPI](https://img.shields.io/pypi/v/copilot-session-usage)](https://pypi.org/project/copilot-session-usage/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/copilot-session-usage)](https://pypi.org/project/copilot-session-usage/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Type checked](https://img.shields.io/badge/type%20checked-mypy%2Fty-blue.svg)](./)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
+
+## 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
+```
+
+## 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 detail levels** — `minimal`, `compact`, `full`
+- **JSON and table output** — machine-readable or human-friendly
+
+## 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 its debug-log directory |
+| `latest` | Analyze the most recently modified session |
+| `find TITLE` | Find and analyze a session by title (fuzzy match) |
+| `id SESSION_ID` | Analyze a session by exact UUID |
+| `list` | List recent sessions (metadata only, no cost) |
+| `batch N` | Analyze the N most recent sessions in one pass |
+
+### 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: `table`) |
+| `--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 "refactor" in the title
+$ copilot-session-usage find "refactor"
+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
+
+# Batch analyze last 5 sessions since July 1st
+copilot-session-usage batch 5 --since 2026-07-01
+
+# 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 copilot_session_usage.api import analyze_session, analyze_latest, batch_analyze
+
+# 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")
+```
+
+## 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).

copilot_session_usage-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+copilot_session_usage/__init__.py,sha256=fOVG3PXlOomI1QT7z5SyA746fpbdJTtr63wXE-r2R7s,281
+copilot_session_usage/api.py,sha256=fUXwJGlRpvqfkmHvXdfzcwp5VE5i24T_rUBVFwkO57I,6830
+copilot_session_usage/cli.py,sha256=TLY6Ab_mMLljhlxppvNfEQ4Xc29xZlGlA1W94yZJMVU,9498
+copilot_session_usage/_internal/__init__.py,sha256=sxn8qRXfsEyKyuiXTHuhYAM5fs42GF2m4Qm12EBeDxk,39
+copilot_session_usage/_internal/copilot_cli.py,sha256=y0-YyUKwP1dif0orb6cLQrt80eBfD9Sazy8me2gMT_g,704
+copilot_session_usage/_internal/core.py,sha256=OFMDRPGrGYe8Rr75MSvv45ZRI70N50lCypnhtAYht9s,38827
+copilot_session_usage/_internal/vscode.py,sha256=sVtnGFom3kRVNlqgMl_ylaZmApOQk1US7Nle0wrQxls,9210
+copilot_session_usage/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+copilot_session_usage/data/custom-models-pricing.yml,sha256=2s74LQxm4tmloEhb4Ha7gVoORYoxAIt9LVpiDsyVqug,842
+copilot_session_usage/data/models-and-pricing.lock,sha256=JXUq2FH4WnZrISWK4Q48R6oWEG0WuS3wAgUwG5umvIw,272
+copilot_session_usage/data/models-and-pricing.yml,sha256=DTmLXPRb-f-xl0My-uHy4OJGRCWrzH6UARkb3sEF0zg,5562
+copilot_session_usage-0.1.0.dist-info/METADATA,sha256=zh5SrFynEbD37XVbo3sbsistVD63yV8n293k0l1fIEg,6623
+copilot_session_usage-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+copilot_session_usage-0.1.0.dist-info/entry_points.txt,sha256=ZY4Km9tWEHBgVTCTpcL5EFod0sibUizMj7qKkWZKhMI,72
+copilot_session_usage-0.1.0.dist-info/licenses/LICENSE,sha256=QJiCkAnFtBdu7R1YVheQ4fmz2m5rR_KUMjI47zbSjyg,1069
+copilot_session_usage-0.1.0.dist-info/RECORD,,

copilot_session_usage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

copilot_session_usage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+copilot-session-usage = copilot_session_usage.cli:cli

copilot_session_usage-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaetan Semet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.