copilot-session-usage 0.2.0__tar.gz → 0.2.1__tar.gz

{copilot_session_usage-0.2.0 → copilot_session_usage-0.2.1}/CHANGELOG.md

@@ -1,9 +1,13 @@
 ## Unreleased
 
-### Feat
-
-- initial implementation
+## v0.2.0 (2026-07-02)
 
 ### Fix
 
 - bad cost compuation for Opus 4.8
+
+## v0.1.0 (2026-07-02)
+
+### Feat
+
+- initial implementation

{copilot_session_usage-0.2.0 → copilot_session_usage-0.2.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.0
+Version: 0.2.1
 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: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/
 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>
@@ -20,6 +20,7 @@ Description-Content-Type: text/markdown
 [![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/)
+[![Docs](https://readthedocs.org/projects/copilot-session-usage/badge/?version=stable)](https://copilot-session-usage.readthedocs.io/en/stable/)
 [![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)
@@ -182,6 +183,8 @@ just docs
 just docs-serve
 ```
 
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

{copilot_session_usage-0.2.0 → copilot_session_usage-0.2.1}/README.md

@@ -4,6 +4,7 @@
 [![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/)
+[![Docs](https://readthedocs.org/projects/copilot-session-usage/badge/?version=stable)](https://copilot-session-usage.readthedocs.io/en/stable/)
 [![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)
@@ -166,6 +167,8 @@ just docs
 just docs-serve
 ```
 
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

copilot_session_usage-0.2.1/docs/source/_static/changelog.js

@@ -0,0 +1,25 @@
+/* Rewrite changelog category headings */
+document.addEventListener('DOMContentLoaded', function () {
+    const map = {
+        'Feat': '✨ Features',
+        'Fix': '🔧 Bug Fixes',
+        'Docs': '📚 Documentation',
+        'Chore': '🧹 Chores',
+        'Refactor': '🛠 Refactors',
+        'Test': '🧪 Tests',
+        'CI': '🤖 CI',
+        'Perf': '⚡ Performance',
+        'Build': '🏗 Build',
+        'Style': '🎨 Styles',
+    };
+
+    document.querySelectorAll('h3').forEach(function (h3) {
+        const text = h3.childNodes[0];
+        if (text && text.nodeType === Node.TEXT_NODE) {
+            const trimmed = text.textContent.trim();
+            if (map[trimmed]) {
+                text.textContent = ' ' + map[trimmed] + ' ';
+            }
+        }
+    });
+});

copilot_session_usage-0.2.1/docs/source/_static/custom.css

@@ -0,0 +1,142 @@
+/* Custom styles for copilot-session-usage documentation */
+
+/* ── Changelog ── */
+#changelog h2 {
+    font-size: 1.4em;
+    font-weight: 600;
+    margin-top: 2.5em;
+    padding-bottom: 0.4em;
+    border-bottom: 1px solid var(--color-background-border);
+}
+
+#changelog h2:first-of-type {
+    margin-top: 0.5em;
+}
+
+#changelog h2#unreleased {
+    color: var(--color-brand-primary);
+}
+
+#changelog h3 {
+    font-size: 0.8em;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    margin: 1.5em 0 0.6em;
+    padding: 0.3rem 0.6rem;
+    display: inline-block;
+}
+
+/* Features */
+#changelog section[id="feat"] > h3,
+#changelog section[id="id1"] > h3,
+#changelog section[id="id4"] > h3,
+#changelog section[id="id6"] > h3,
+#changelog section[id="id8"] > h3,
+#changelog section[id="id10"] > h3 {
+    font-size: 0;
+    color: transparent;
+    background: rgba(26, 127, 55, 0.08);
+}
+
+#changelog section[id="feat"] > h3::before,
+#changelog section[id="id1"] > h3::before,
+#changelog section[id="id4"] > h3::before,
+#changelog section[id="id6"] > h3::before,
+#changelog section[id="id8"] > h3::before,
+#changelog section[id="id10"] > h3::before {
+    content: "✨ Features";
+    font-size: 0.8rem;
+    color: #1a7f37;
+}
+
+/* Bug Fixes */
+#changelog section[id="fix"] > h3,
+#changelog section[id="id2"] > h3,
+#changelog section[id="id3"] > h3,
+#changelog section[id="id5"] > h3,
+#changelog section[id="id7"] > h3,
+#changelog section[id="id9"] > h3 {
+    font-size: 0;
+    color: transparent;
+    background: rgba(154, 103, 0, 0.08);
+}
+
+#changelog section[id="fix"] > h3::before,
+#changelog section[id="id2"] > h3::before,
+#changelog section[id="id3"] > h3::before,
+#changelog section[id="id5"] > h3::before,
+#changelog section[id="id7"] > h3::before,
+#changelog section[id="id9"] > h3::before {
+    content: "🔧 Bug Fixes";
+    font-size: 0.8rem;
+    color: #9a6700;
+}
+
+#changelog ul {
+    margin-top: 0.5em;
+    padding-left: 1.2em;
+}
+
+#changelog li {
+    margin-bottom: 0.35em;
+    line-height: 1.6;
+}
+
+/* ── Landing page cards ── */
+.sd-card {
+    transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.sd-card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+/* ── Copy button ── */
+button.copybtn {
+    opacity: 0.6;
+    transition: opacity 0.2s;
+}
+
+button.copybtn:hover {
+    opacity: 1;
+}
+
+/* ── CLI tables ── */
+table.docutils {
+    font-size: 0.95em;
+}
+
+table.docutils th {
+    background: var(--color-background-secondary);
+}
+
+/* ── API signatures ── */
+dl.py.function,
+dl.py.class,
+dl.py.method {
+    margin: 1.5em 0;
+}
+
+dl.py.function > dd,
+dl.py.class > dd,
+dl.py.method > dd {
+    margin-left: 0;
+    padding-left: 1em;
+}
+
+dt.sig.sig-object.py {
+    background: var(--color-background-secondary);
+    border-left: 3px solid var(--color-brand-primary);
+    border-radius: 0;
+    margin-left: 0;
+    margin-right: 0;
+    padding: 0.6em 0.8em;
+    line-height: 1.6;
+    text-indent: 0;
+}
+
+dl.py.class > dt.sig.sig-object.py {
+    border-left-color: var(--color-brand-content);
+}

{copilot_session_usage-0.2.0 → copilot_session_usage-0.2.1}/docs/source/conf.py

@@ -17,6 +17,8 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx_click",
     "sphinx_autodoc_typehints",
+    "sphinx_design",
+    "sphinx_copybutton",
 ]
 
 myst_enable_extensions = ["colon_fence", "deflist"]
@@ -24,6 +26,8 @@ myst_enable_extensions = ["colon_fence", "deflist"]
 html_theme = "furo"
 html_title = f"copilot-session-usage {version}"
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_js_files = ["changelog.js"]
 
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"

copilot_session_usage-0.2.1/docs/source/explanation/how-cost-estimation-works.md

@@ -0,0 +1,96 @@
+# How Cost Estimation Works
+
+`copilot-session-usage` estimates session costs from VS Code debug logs.
+This page explains each step.
+
+---
+
+## Where the logs live
+
+VS Code stores one directory per workspace under `workspaceStorage`. Inside
+each workspace directory, the Copilot extension writes debug logs:
+
+```
+workspaceStorage/
+└── <workspace-hash>/
+    └── GitHub.copilot-chat/
+        └── debug-logs/
+            └── <session-uuid>/
+                ├── *.jsonl      ← token events
+                └── ...
+```
+
+Default locations by platform:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Code/User/workspaceStorage/` |
+| Linux | `~/.config/Code/User/workspaceStorage/` |
+| Windows | `%APPDATA%\Code\User\workspaceStorage\` |
+| WSL2 (remote) | `~/.vscode-server/data/User/workspaceStorage/` |
+
+The tool also checks `Code - Insiders` variants automatically.
+
+---
+
+## How sessions are discovered
+
+The tool reads the session title from VS Code's SQLite workspace database
+(`state.vscdb`). Sessions are sorted by the last-modified time of their
+debug-log directory, most recent first.
+
+The `list` command reads only metadata (no JSONL parsing). The `analyze`,
+`id`, and `batch` commands parse the full JSONL files.
+
+---
+
+## Parsing JSONL logs
+
+Each `.jsonl` file contains one JSON object per line. The tool extracts
+token-count events emitted by the Copilot extension for each LLM call:
+
+- `input_tokens` — tokens sent to the model
+- `output_tokens` — tokens generated by the model
+- `cached_tokens` — input tokens served from the provider's prompt cache
+- `model` — the model name as reported by the provider
+
+A single session may call multiple models (e.g., Claude Sonnet for the main
+request and Claude Haiku for a subagent). Each model's tokens are summed
+separately, then costs are computed per model and aggregated.
+
+---
+
+## Cost calculation
+
+For each model, cost is computed as:
+
+```
+cost = (input_tokens - cached_tokens) / 1_000_000 × input_price
+     + cached_tokens / 1_000_000 × cached_input_price
+     + output_tokens / 1_000_000 × output_price
+```
+
+Prices come from the bundled `models-and-pricing.yml`. For models with
+long-context tier switching (e.g., GPT-5.4 above 272K tokens), the tool
+selects the correct price row automatically.
+
+---
+
+## Subagent attribution
+
+`runSubagent` calls appear in the JSONL as a distinct event type. The tool
+tracks them separately so `--detail full` can show which fraction of tokens
+was consumed by subagents vs. the main conversation.
+
+---
+
+## Accuracy
+
+Prices match the published GitHub Copilot per-token rates for each model.
+The tool applies the same formula GitHub uses: input tokens (minus cached)
+at the full input rate, cached tokens at the cache-hit rate, output tokens
+at the output rate. Long-context tier switching is automatic.
+
+The main source of variance is pricing lag: the bundled table is updated
+manually with each release. Run `just refresh-pricing` to pull the latest
+rates.

copilot_session_usage-0.2.1/docs/source/explanation/index.md

@@ -0,0 +1,9 @@
+# How It Works
+
+Background and design notes.
+
+```{toctree}
+:maxdepth: 1
+
+how-cost-estimation-works
+```

copilot_session_usage-0.2.1/docs/source/how-to/analyze-specific-session.md

@@ -0,0 +1,46 @@
+# Analyze a Specific Session
+
+Use this when you know the path to a session's debug-log directory or its UUID,
+and `latest` would pick the wrong session.
+
+## By debug-log path
+
+Each session is a directory inside VS Code's `workspaceStorage`:
+
+```bash
+copilot-session-usage analyze \
+  "/path/to/workspaceStorage/<hash>/GitHub.copilot-chat/debug-logs/<session-uuid>"
+```
+
+The path always ends in a UUID directory. Use `list` to find the right one if
+you're unsure.
+
+## By UUID
+
+If you have a session ID from a previous `list` or `find` run:
+
+```bash
+copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56
+```
+
+The tool searches all workspaceStorage roots automatically.
+
+## By title substring
+
+```bash
+copilot-session-usage find "CI pipeline"
+```
+
+Matching is case-insensitive substring search. If multiple sessions match,
+the tool lists them and exits without analyzing — then use `id` to pick one.
+
+## Locating workspaceStorage manually
+
+| Platform | Default path |
+|----------|-------------|
+| macOS | `~/Library/Application Support/Code/User/workspaceStorage/` |
+| Linux | `~/.config/Code/User/workspaceStorage/` |
+| Windows | `%APPDATA%\Code\User\workspaceStorage\` |
+
+Each subdirectory under `workspaceStorage/` corresponds to one VS Code workspace.
+Inside it, `GitHub.copilot-chat/debug-logs/` contains one directory per session.

copilot_session_usage-0.2.1/docs/source/how-to/batch-and-spending.md

@@ -0,0 +1,64 @@
+# Track Spending Over Time
+
+Use `batch` with `--since` to aggregate costs for a time window.
+
+## Daily cost report
+
+```bash
+# All sessions today
+copilot-session-usage batch 50 --since $(date +%Y-%m-%d)
+```
+
+## Weekly report
+
+```bash
+copilot-session-usage batch 100 --since 2026-06-25
+```
+
+Sample output:
+
+```
+Sessions analyzed: 23
+Total input:       8,412,304 tokens
+Total output:      142,887 tokens
+Total cached:      7,103,220 (84%)
+Total LLM calls:   312
+Est. total cost:   $11.74
+
+Session                            Started              Cost
+Implement new feature X            2026-07-02 09:14Z   $0.42
+Debug failing CI pipeline          2026-07-01 18:03Z   $1.87
+...
+```
+
+## Save to a file and diff
+
+```bash
+copilot-session-usage batch 100 --since 2026-07-01 \
+  --format json --output july-costs.json
+```
+
+Then open `july-costs.json` in any tool that understands JSON arrays.
+
+## Filter by workspace
+
+If you work in multiple repositories, limit the report to one workspace:
+
+```bash
+copilot-session-usage batch 50 \
+  --since 2026-07-01 \
+  --workspace-filter myproject
+```
+
+`--workspace-filter` matches against the workspace folder name (substring,
+case-insensitive).
+
+## Automate with cron (macOS/Linux)
+
+```bash
+# ~/.zshrc or crontab -e
+# Run every Sunday at 23:55, append weekly cost to a log
+55 23 * * 0 copilot-session-usage batch 200 \
+  --since $(date -v-7d +%Y-%m-%d) \
+  --format json >> ~/copilot-costs.jsonl
+```

copilot_session_usage-0.2.1/docs/source/how-to/export-json.md

@@ -0,0 +1,65 @@
+# Export to JSON
+
+Use `--format json` to get machine-readable output for scripting, dashboards,
+or storage.
+
+## Write to stdout
+
+```bash
+copilot-session-usage latest --format json
+```
+
+## Write to a file
+
+```bash
+copilot-session-usage latest --format json --output session.json
+```
+
+## Extract a single field with jq
+
+```bash
+# Estimated cost
+copilot-session-usage latest --format json | jq '.estimated_cost_usd'
+
+# All model names called in the session
+copilot-session-usage latest --format json | jq '[.models[].model]'
+
+# Total cached tokens
+copilot-session-usage latest --format json | jq '.total_cached_tokens'
+```
+
+## Batch export
+
+Export the last 20 sessions as a single JSON document:
+
+```bash
+copilot-session-usage batch 20 --format json --output week.json
+```
+
+The document has two top-level keys: `summary` (aggregate) and `sessions`
+(per-session list).
+
+```bash
+# Total cost across all sessions
+cat week.json | jq '.summary.estimated_cost_usd'
+
+# Cost per session, sorted descending
+cat week.json | jq '[.sessions[] | {title, cost: .estimated_cost_usd}] | sort_by(-.cost)'
+```
+
+## Use with the Python API
+
+```python
+from pathlib import Path
+from copilot_session_usage.api import analyze_latest, batch_analyze
+import json
+
+# Latest session as a dict
+result = analyze_latest(detail="full")
+print(json.dumps(result, indent=2))
+
+# Last 10 sessions
+batch = batch_analyze(10, detail="compact")
+for s in batch["sessions"]:
+    print(f"{s['title']}: ${s['estimated_cost_usd']:.4f}")
+```

copilot_session_usage-0.2.1/docs/source/how-to/index.md

@@ -0,0 +1,12 @@
+# How-To Guides
+
+Task-oriented recipes for common workflows.
+
+```{toctree}
+:maxdepth: 1
+
+analyze-specific-session
+export-json
+batch-and-spending
+wsl2
+```

copilot_session_usage-0.2.1/docs/source/how-to/wsl2.md

@@ -0,0 +1,37 @@
+# Use from WSL2
+
+On WSL2, VS Code runs on Windows and stores debug logs in the Windows filesystem.
+Point the tool at the Windows path via `/mnt/c/`.
+
+## Basic usage
+
+```bash
+copilot-session-usage latest \
+  --workspace-storage "/mnt/c/Users/$USER/AppData/Roaming/Code/User/workspaceStorage"
+```
+
+## Make it permanent
+
+Add an alias to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+alias copilot-session-usage='copilot-session-usage \
+  --workspace-storage "/mnt/c/Users/$USER/AppData/Roaming/Code/User/workspaceStorage"'
+```
+
+## Verify the path
+
+If the Windows username differs from your WSL username, substitute it directly:
+
+```bash
+ls "/mnt/c/Users/MyWindowsName/AppData/Roaming/Code/User/workspaceStorage"
+```
+
+You should see directories named with long hex hashes.
+
+## VS Code Server (Remote - WSL extension)
+
+When using the VS Code Remote - WSL extension, VS Code runs in WSL and stores
+logs in the Linux filesystem at the default location
+(`~/.config/Code/User/workspaceStorage/`). No `--workspace-storage` override
+is needed in this case.

copilot_session_usage-0.2.1/docs/source/index.md

@@ -0,0 +1,66 @@
+# copilot-session-usage
+
+**copilot-session-usage** reads VS Code Copilot debug logs and tells you
+how much each AI coding session cost in USD.
+
+VS Code does not show session costs in its UI. The debug logs contain
+token counts per model. This tool reads those logs, applies the real
+published pricing (with cache discounts and long-context tiers), and
+prints a cost report in seconds.
+
+The most common use: after a heavy agentic session, run
+`copilot-session-usage latest` to see what it cost.
+
+::::{grid} 1 1 2 2
+:gutter: 3
+
+:::{grid-item-card} 📦 Installation
+:link: installation
+:link-type: doc
+
+Install `copilot-session-usage` with uv or pip.
+:::
+
+:::{grid-item-card} 🚀 Getting Started
+:link: tutorials/getting-started
+:link-type: doc
+
+Analyze your first session and understand the output in under 5 minutes.
+:::
+
+:::{grid-item-card} 📖 How-To Guides
+:link: how-to/index
+:link-type: doc
+
+Export to JSON, track spending over time, integrate in scripts,
+and configure WSL2.
+:::
+
+:::{grid-item-card} 📚 Reference
+:link: reference/index
+:link-type: doc
+
+Complete CLI and Python API documentation.
+:::
+
+:::{grid-item-card} 💡 How It Works
+:link: explanation/how-cost-estimation-works
+:link-type: doc
+
+Where the logs live, how tokens are counted,
+and how pricing tiers are applied.
+:::
+
+::::
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+Installation <installation>
+Tutorials <tutorials/index>
+How-To <how-to/index>
+Reference <reference/index>
+How It Works <explanation/index>
+Changelog <changelog>
+```

copilot_session_usage-0.2.1/docs/source/installation.md

@@ -0,0 +1,42 @@
+# Installation
+
+**copilot-session-usage** is published to PyPI and works on macOS, Linux, and Windows.
+
+## With uv (recommended)
+
+```bash
+uv tool install copilot-session-usage
+```
+
+## With pip
+
+```bash
+pip install copilot-session-usage
+```
+
+## Verify
+
+```bash
+copilot-session-usage --version
+```
+
+## Upgrade (uv)
+
+```bash
+uv tool install --upgrade copilot-session-usage
+```
+
+## As a library
+
+Install as a Python library for use in scripts or notebooks:
+
+```bash
+uv add copilot-session-usage
+# or
+pip install copilot-session-usage
+```
+
+## Next steps
+
+- [Getting Started](tutorials/getting-started) — analyze your first session
+- [How-To Guides](how-to/index) — export to JSON, track spending over time