copilot-session-usage 0.7.2__tar.gz → 0.7.3__tar.gz

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/.github/skills/gh-release-notes/SKILL.md

@@ -10,7 +10,11 @@ user-invocable: true
 Generate **end-user-friendly, user-impact-only** release notes by analyzing the actual changes between releases.
 Interactive use requires no script; automated generation and validation use the bundled script described below.
 
-The output is meant to be **copy-pasted into a GitHub Release**. It must contain release-note sections only: never add a document title, preamble, file summary, commit summary, or closing separator.
+The output is meant to be **copy-pasted into a GitHub Release**. It must contain
+release-note sections only: never add a document title, version heading, preamble,
+file summary, commit summary, or closing separator. GitHub already displays the
+release title and version above the body, so do not repeat it in the generated
+Markdown.
 
 ## Non-negotiable output contract
 
@@ -24,6 +28,11 @@ The output is meant to be **copy-pasted into a GitHub Release**. It must contain
 - Never include `## Maintenance` together with any user-facing section. When a
 	user-facing change qualifies, omit Maintenance and discard all internal-only
 	candidates.
+- Start the output with a permitted `##` section heading. Never emit a `#` heading
+	for the version or release title, such as `# v0.7.2`, `# Release v0.7.2`, or
+	`# Release notes`.
+- For a maintenance-only release, emit exactly `## Maintenance` and its concise
+	maintenance statement. Do not add any title or version heading before it.
 - Before writing the file, inspect the final Markdown for these rules and remove
 	any violating bullet or section.
 
@@ -224,7 +233,7 @@ Breaking changes come from:
 
 ### Step 6: Categorize & Format
 
-Organize qualifying changes into buckets. **Only include sections that have content.** Omit empty sections entirely. Do not add a title heading.
+Organize qualifying changes into buckets. **Only include sections that have content.** Omit empty sections entirely. Do not add a title heading or version heading. The first line must be one of the permitted `##` section headings.
 
 The only permitted headings are `## New Features`, `## Enhancements`, `## Bug
 Fixes`, `## Breaking Changes`, `## Examples`, `## Documentation`, and
@@ -239,13 +248,13 @@ replace the missing URL with a repository path, an unlinked description, or a
 claim that documentation was updated.
 
 If no qualifying user-facing change exists, emit exactly one concise `## Maintenance`
-section. Explain generically that the release contains maintenance and internal
-improvements without naming CI, workflows, release automation, internal guidelines,
-tests, commits, pull requests, governance files, documentation files, or individual
-files. Do not invent a feature, user benefit, example, or documentation link. Never
-publish `Internal` or an empty maintenance section. If at least one user-facing
-change exists, omit Maintenance entirely; do not use it as a bucket for leftover
-internal changes.
+section as the first and only heading. Explain generically that the release contains
+maintenance and internal improvements without naming CI, workflows, release
+automation, internal guidelines, tests, commits, pull requests, governance files,
+documentation files, or individual files. Do not invent a feature, user benefit,
+example, or documentation link. Never publish `Internal` or an empty maintenance
+section. If at least one user-facing change exists, omit Maintenance entirely; do
+not use it as a bucket for leftover internal changes.
 
 `## Maintenance` and a user-facing section are mutually exclusive. If any
 Enhancements, New Features, Bug Fixes, Breaking Changes, Examples, or qualifying
@@ -317,6 +326,18 @@ Use absolute HTTPS URLs, and omit a documentation link when no public page can b
 
 **Clean markdown** for a GitHub Release body:
 
+The following is invalid because the GitHub Release page already supplies the
+version title:
+
+```markdown
+# v0.7.2
+
+## Bug Fixes
+- Fixed an issue with session discovery
+```
+
+Start directly with the release-note section instead:
+
 ```markdown
 ## New Features
 - Added dark mode toggle in settings
@@ -348,7 +369,9 @@ Use absolute HTTPS URLs, and omit a documentation link when no public page can b
 - User impact only (not implementation details, changed-file summaries, CI, internal process, or contributor guidance)
 - Every bullet must describe a benefit or changed capability for ordinary users of the published product
 - Do not include release tooling, Git evidence, validation behavior, governance files, contributor guidance, agent instructions, CI, workflows, or repository housekeeping
-- Do not include a title heading; the GitHub Release supplies the title
+- Do not include a title or version heading; the GitHub Release supplies the title
+- The first line must be a permitted `##` section heading, including `## Maintenance`
+	for maintenance-only releases
 - Use public documentation URLs; never use repo-relative paths like `docs/...` or `README.md`
 - For each user-facing bullet, search existing documentation for the closest page about the impacted behavior and link it inline with descriptive Markdown text when available, even when the documentation file was unchanged
 - Use fragment identifiers (`#section-name`) to point to specific docs sections

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
               bump_args+=(--allow-no-commit)
             fi
             if ! next_version_output="$(uv run --no-sync cz bump "${bump_args[@]}" 2>&1)"; then
-              echo "::error::No eligible conventional commits were found for an automatic release."
+              echo "::error::No eligible conventional commits were found for an automatic release. You can either wait for a user-impacting feature or bug fix and start a new release, or enable 'Force a patch release when auto finds no eligible commit' when triggering the 'Release' Action."
               printf '%s\n' "$next_version_output"
               exit 1
             fi

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/CONTRIBUTING.md

@@ -48,6 +48,9 @@ just docs-serve
 2. Run it from the default branch, choosing `auto` to derive the major, minor, or
 	patch bump from conventional commits, or choose an explicit bump. Enable
 	`force` to create a patch release when `auto` finds no eligible commit.
+	If `auto` finds no eligible commit, you can either wait for a user-impacting
+	feature or bug fix and start a new release, or enable **Force a patch release
+	when auto finds no eligible commit** when triggering the **Release** Action.
 3. The workflow uses Commitizen to calculate the next version, prepares a local
 	`vX.Y.Z` tag on the existing default-branch commit, generates notes with the
 	`gh-release-notes` skill through `gh copilot`, writes the final Markdown to

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.7.2
+Version: 0.7.3
 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/en/stable/
@@ -31,6 +31,59 @@ Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duratio
 
 **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
@@ -110,7 +163,7 @@ just knowledge-validate
 |---------|-------------|
 | `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 (fuzzy match) |
+| `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 |
@@ -140,7 +193,7 @@ just knowledge-validate
 | `--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`) |
+| `--format {json,table,detailed}` | Output format (default: `json`) |
 | `--output PATH` | Write output to file instead of stdout |
 
 ### Examples
@@ -157,8 +210,8 @@ $ copilot-session-usage latest --detail full
 # 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"
+# 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)
@@ -241,6 +294,8 @@ copilot-session-usage latest \
 ## Python API
 
 ```python
+from pathlib import Path
+
 from copilot_session_usage.api import (
     analyze_session,
     analyze_latest,

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/README.md

@@ -13,6 +13,59 @@ Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duratio
 
 **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
@@ -92,7 +145,7 @@ just knowledge-validate
 |---------|-------------|
 | `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 (fuzzy match) |
+| `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 |
@@ -122,7 +175,7 @@ just knowledge-validate
 | `--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`) |
+| `--format {json,table,detailed}` | Output format (default: `json`) |
 | `--output PATH` | Write output to file instead of stdout |
 
 ### Examples
@@ -139,8 +192,8 @@ $ copilot-session-usage latest --detail full
 # 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"
+# 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)
@@ -223,6 +276,8 @@ copilot-session-usage latest \
 ## Python API
 
 ```python
+from pathlib import Path
+
 from copilot_session_usage.api import (
     analyze_session,
     analyze_latest,

copilot_session_usage-0.7.3/docs/articles/presentation.md

@@ -0,0 +1,90 @@
+## Title
+
+I built `copilot-session-usage`: inspect the token usage and estimated cost of VS Code Copilot sessions
+
+## Post
+
+I’ve released [`copilot-session-usage`](https://github.com/gsemet/copilot-session-usage), an open-source Python CLI for analyzing VS Code Copilot sessions.
+
+VS Code’s UI does not provide a detailed per-session cost report. This tool reads the local Copilot debug logs and reports:
+
+- Input, output, and cached token counts
+- Models used during a session
+- Estimated cost in USD
+- Main-conversation versus subagent usage
+- Cost and tool-call attribution by skill
+- Aggregate spending across sessions, workspaces, dates, or features
+- JSON output for scripts and a Python API for integration
+- Optional Git commit trailers containing session usage
+
+It supports multi-model sessions, cache-aware pricing, long-context pricing tiers, macOS, Linux, Windows, and WSL2. For Copilot-plan models, it uses the usage value recorded by VS Code when available. For externally billed Azure-hosted models, it falls back to token-based pricing, so reports should be treated as estimates.
+
+
+## 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 | ❌ | ✅ |
+
+## Example
+
+A typical workflow is simply:
+
+`uv tool install copilot-session-usage`
+
+Then search for a session ID:
+
+`copilot-session-usage find "Get execution costs with Chronicle"`
+
+And get details:
+
+```bash
+$ copilot-session-usage id "31c51cee-cb1c-4aa5-8c55-83479bcf54da" --format detailed
+Session:   31c51cee-cb1c-4aa5-8c55-83479bcf54da
+Title:     Get execution costs with Chronicle
+Started:   2026-08-08T09:16:00Z
+Duration:  1588s  (active: 916s)
+Models:    claude-opus-4.8, gpt-5.6-luna
+Input:     7,463,752 tokens
+Output:    39,243 tokens
+Cached:    7,050,320 (94%)
+LLM calls: 76
+Est. cost: $1.8836
+
+Per-Model Breakdown:
+  Model                Input     Cached  Output  Calls   Cost
+  -----------------------------------------------------------
+  claude-opus-4.8  1,411,792  1,289,047   9,955     13  $1.66
+  gpt-5.6-luna     6,051,960  5,761,273  29,288     63  $0.22
+
+Subagents:
+  Name                                                      Model                Input     Cached  Output   Cost
+  --------------------------------------------------------------------------------------------------------------
+  main                                                      gpt-5.6-luna     6,051,960  5,761,273  29,288  $0.22
+  Subagent — Claude Opus 4.8-call_CgcUaex8Erf1nChCvxHJtT01  claude-opus-4.8  1,411,792  1,289,047   9,955  $1.66
+```
+
+Default output is json, perfect for an agent.
+
+You can also analyze several sessions together or filter them by title, date, workspace, or skill.
+
+This is useful if you use Copilot for substantial agentic work and want a clearer record of what different sessions, models, subagents, or skills actually consumed. It can help with budgeting, comparing workflows, investigating cache usage, and building an auditable usage history without manually inspecting JSONL logs.
+
+It is MIT-licensed and available on [GitHub](https://github.com/gsemet/copilot-session-usage) and [PyPI](https://pypi.org/project/copilot-session-usage/).

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/docs/internal/automated_release_proces.md

@@ -243,6 +243,10 @@ If automatic detection reports no eligible commits and `force` is disabled, the
 workflow stops before creating a tag. This is expected for
 changes such as a standalone `ci:` or `chore:` commit.
 
+At that point, you can either wait for a user-impacting feature or bug fix and
+start a new release, or enable **Force a patch release when auto finds no
+eligible commit** when triggering the **Release** Action.
+
 If `force` is enabled, the workflow intentionally falls back to a patch bump:
 
 ```text

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/src/copilot_session_usage/data/models-and-pricing.lock

@@ -1,7 +1,7 @@
 {
-  "_captured": "2026-08-04T05:25:32.319897+00:00",
+  "_captured": "2026-08-08T03:44:16.696767+00:00",
   "_source": "https://raw.githubusercontent.com/github/docs/main/data/tables/copilot/models-and-pricing.yml",
   "_yaml_path": "/home/runner/work/copilot-session-usage/copilot-session-usage/src/copilot_session_usage/data/models-and-pricing.yml",
-  "model_count": 35,
-  "checksum": "4d0edb1c05af21c5"
+  "model_count": 36,
+  "checksum": "a23f8c498f40aff7"
 }

{copilot_session_usage-0.7.2 → copilot_session_usage-0.7.3}/src/copilot_session_usage/data/models-and-pricing.yml

@@ -372,3 +372,11 @@
   input: $0.95
   cached_input: $0.19
   output: $4.00
+
+- model: 'Kimi K3'
+  provider: moonshot_ai
+  release_status: GA
+  category: Powerful
+  input: $3.00
+  cached_input: $0.30
+  output: $15.00