copilot-session-usage 0.4.0__tar.gz → 0.5.0__tar.gz

copilot_session_usage-0.5.0/.github/guidelines/git-commit-message.guideline.md

@@ -0,0 +1,99 @@
+---
+name: Git Commit Message Guideline 1.0
+description: Guidelines for writing conventional commits that communicate intent and user impact
+metadata:
+  owner: Gaetan Semet <gaetan.semet@ampere.cars>
+  keywords: [git, commit, conventional, message, changelog]
+  guideline-id: 45c42e46-0781-4954-a410-1f380f5553f3
+---
+
+# Git Commit Message Guideline
+
+Write clear, focused commit messages following Conventional Commits format. Commit messages communicate *why* changes were made—enabling automated changelog generation, bug investigation, and decision-making during upgrades. Focus on user impact, not implementation details.
+
+## Core Rules
+
+### Rule 1: Use Conventional Commit Format
+
+**Apply:** Format every title as `type(scope): description`
+
+**Why:** Enables automated changelog generation and consistent pattern parsing.
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `chore`, `build`, `revert`
+
+**Examples:**
+```
+feat(auth): add two-factor authentication support
+fix(api): resolve request timeout in user endpoint
+docs(readme): update installation instructions
+perf(cache): optimize query performance by 40%
+test(validators): add email format validation tests
+```
+
+---
+
+### Rule 2: Keep Title Under 50 Characters, Body Under 72 Per Line
+
+**Apply:** Enforce character limits for scannability and terminal compatibility.
+
+**Why:** Short titles force clarity; wrapped body text maintains readability in terminals and email clients.
+
+**Example:**
+```
+feat(cache): implement LRU eviction policy
+
+Reduces memory usage in long-running processes by
+automatically removing least-recently-used items.
+
+Changes:
+- Cache drops oldest accessed items upon limit
+- Configurable cache size (default 1000)
+- < 2% performance overhead on reads
+
+Users can set CACHE_SIZE environment variable.
+```
+
+---
+
+### Rule 3: Focus Body on User Impact, Not Implementation Details
+
+**Apply:** Describe what users gain and must know; exclude refactoring details, internal functions, and test additions.
+
+**Why:** Users deciding whether to upgrade, developers integrating changes, and bug investigators need user-level context—not code structure details.
+
+**Example:**
+```
+fix(api): allow null values in optional response fields
+
+Optional fields now omitted from JSON when empty,
+reducing response payload by ~15% for sparse data.
+
+Migration:
+- Check `field in response` instead of `field != null`
+- Response schema updated in API reference
+```
+
+---
+
+### Rule 4: Include Breaking Changes with Migration Guidance
+
+**Apply:** Use `!` in title and `BREAKING CHANGE:` section. Provide explicit migration steps.
+
+**Why:** Breaking changes require user action; clear guidance reduces upgrade confusion.
+
+**Example:**
+```
+feat(api)!: change pagination to cursor-based tokens
+
+Cursors improve performance with large datasets.
+
+BREAKING CHANGE: Replaced `pagination_offset` and
+`pagination_limit` with `pagination.cursor`.
+
+Migration:
+Old: GET /users?limit=10&offset=20
+New: GET /users?limit=10&cursor=xyz123
+
+Update code to use `response.pagination.cursor`
+in next request instead of offset/limit.
+```

copilot_session_usage-0.5.0/.github/skills/gh-release-notes/SKILL.md

@@ -0,0 +1,234 @@
+# Release Notes Generator (Git Diff Based)
+
+Generate **end-user friendly** release notes by analyzing actual code changes between releases.
+No scripts required — uses git commands to understand what changed and why it matters.
+
+---
+
+## Quick Start
+
+Provide your repository and range:
+
+```
+Generate release notes from v1.0.0 to v1.1.0 in /path/to/repo
+```
+
+Or reference the last release:
+
+```
+What changed since the last release tag?
+```
+
+---
+
+## What It Does
+
+1. **Reads actual diffs** — examines code changes, not just commit messages
+2. **Interprets for end-users** — no technical jargon, functions, or variable names
+3. **Categorizes intelligently** — Features, Enhancements, Bug Fixes, Breaking Changes
+4. **Consolidates related changes** — groups related diffs, eliminates back-and-forth noise
+5. **Outputs clean markdown** — Slack-ready format suitable for announcements
+
+---
+
+## Input
+
+Accept either:
+
+- **Natural language**: "Show release notes from v1.2.0 to v1.3.0"
+- **Range spec**: `from_tag=v1.2.0 to_tag=v1.3.0 repo_path=/path/to/repo`
+- **Last release**: `since_tag=v1.2.0` (everything from tag to HEAD)
+
+Required:
+- Repository path (optional: defaults to current directory)
+- Range: `from_tag` + `to_tag`, OR `since_tag`, OR `last_n_commits`
+
+---
+
+## Analysis Process
+
+### Step 1: Collect Commits
+```bash
+git log v1.0.0..v1.1.0 --oneline --no-merges
+```
+Gather all commits in the specified range with their messages.
+
+### Step 2: Examine Diffs
+```bash
+git diff v1.0.0..v1.1.0 -- src/
+```
+Read actual code changes line-by-line to understand what changed.
+
+### Step 3: Interpret Changes
+
+Translate technical changes into user impact:
+
+| Code Change | User Impact |
+|-------------|------------|
+| `+ const darkMode = true` in settings | "Dark mode toggle now available in settings" |
+| Deleted login retry logic | "Removed automatic retry on login timeout" |
+| `+ validateEmail()` function | "Email validation improved during signup" |
+| Updated database schema version | "Database schema upgraded (run migration)" |
+| Added 10+ calls to cache layer | "Improved performance on large operations" |
+| Removed old CSV export code | "CSV export removed; use Excel or PDF instead" |
+
+**Key: Focus on the user's experience, not the code implementation.**
+
+### Step 4: Identify Breaking Changes
+
+Breaking changes come from:
+- **Commit messages** containing: "BREAKING", "Breaking", "!:"
+- **Diffs showing**: removed public APIs, changed file formats, data migrations
+- **Config changes**: renamed settings, changed defaults
+
+### Step 5: Consolidate
+- If a feature was added then removed → don't mention it
+- If something changed multiple times → only note the final state
+- If multiple commits fix the same issue → merge into one bullet
+
+### Step 6: Categorize & Format
+
+Organize changes into buckets:
+
+```markdown
+# Release Notes - v1.1.0
+
+## New Features
+- Added dark mode toggle in settings
+- New PDF export option
+
+## Enhancements
+- Improved search performance (now supports partial matches)
+- Faster file opening for large documents
+
+## Bug Fixes
+- Fixed login failures on slow connections
+- Resolved crash when uploading 10MB+ files
+
+## Breaking Changes
+- Database schema updated — run migration before upgrading
+- CSV export removed; use Excel or PDF instead
+
+---
+**Notes:**
+- Dark mode requires display driver update on Windows 7
+- Migration tool available at: docs/migrate-db.md
+```
+
+---
+
+## Workflow for Agent
+
+1. **Parse input** — extract `from_tag`, `to_tag`, `repo_path`, and optional filters
+2. **Fetch commits** — run `git log` with range, collect hashes & messages
+3. **Read diffs per file** — `git show <hash>` for each commit, examine changed files
+4. **Interpret impact** — what does each change mean to users?
+5. **Detect breaking changes** — scan for BREAKING markers, API removals, schema changes
+6. **Group by category** — assign each change to Features/Enhancements/Bug Fixes/Breaking/Other
+7. **Consolidate** — merge related items, remove duplicates and flip-flops
+8. **Format markdown** — generate clean bullet points with proper headings
+9. **Add footnotes** — include migration notes, setup requirements, important links
+
+---
+
+## Output Format
+
+**Ultra-concise markdown** (aim for 100-200 words total):
+
+```markdown
+# Release Notes - v1.1.0
+
+## New Features
+- Dark mode toggle in settings
+- PDF export option
+
+## Enhancements
+- Improved search performance (supports partial matches)
+- Faster file opening for large documents
+
+## Bug Fixes
+- Fixed login failures on slow connections
+- Resolved crash when uploading 10MB+ files
+
+## Breaking Changes
+- Database schema updated — run migration before upgrading
+
+**Learn more:**
+- [Dark Mode Guide](https://docs.example.com/settings#dark-mode)
+- [Upgrade Instructions](https://docs.example.com/upgrade#database)
+```
+
+**Key Rules:**
+- One line per bullet point
+- No sub-bullets or elaborate descriptions
+- Total length: <200 words
+- User impact only (not implementation details)
+- Use fragment identifiers (`#section-name`) to point to specific docs sections
+- Multiple links OK if they point to different topics (Skill Analysis, Aggregation, etc.)
+- Link from feature description → to exact readthedocs section where users will find details
+
+---
+
+## How to Use This Skill in a Session
+
+**User Query:**
+```
+Generate release notes from v2.1.0 to v2.2.0 for /path/to/my-app
+```
+
+**Agent Workflow:**
+1. Navigate to repo: `cd /path/to/my-app`
+2. Fetch commits: `git log v2.1.0..v2.2.0 --oneline --no-merges`
+3. For each commit, examine changes: `git show <hash>`
+4. Interpret: What's the user impact? (not the code details)
+5. Categorize: Feature? Bug fix? Breaking change?
+6. Consolidate: Merge similar items
+7. Format: Clean markdown with categories
+8. Output: Save to RELEASE_NOTES.md
+
+---
+
+## Best Practices
+
+✅ **Do:**
+- Read actual diffs to understand changes
+- Use end-user language ("improved performance" not "optimized O(n) loop")
+- Include breaking changes prominently
+- Group related changes
+- Add notes about migrations or setup
+
+❌ **Don't:**
+- Copy commit messages verbatim
+- Include function/variable names
+- Mention internal refactors users won't notice
+- Include secrets, passwords, or internal URLs
+- Make up changes not shown in diffs
+
+---
+
+## Common Patterns
+
+**Performance improvements:**
+> "Improved search speed when filtering 1000+ records"
+
+**New integrations:**
+> "Added support for OAuth login via GitHub"
+
+**Data format changes:**
+> "Settings file now uses JSON instead of YAML (auto-converted on first run)"
+
+**Removed features:**
+> "Removed IE 11 support to modernize codebase"
+
+**API changes:**
+> "Changed user profile endpoint response format (see migration guide)"
+
+---
+
+## Limitations
+
+- Requires git repository with proper tags
+- Complex changes may need human interpretation
+- Very large diffs (1000+ files) summarized by file count
+- Works best with semantic versioning (v1.0.0 format)
+- Needs meaningful commit messages for best results

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/AGENTS.md

@@ -7,6 +7,7 @@
 - **[README](README.md)** — User-facing overview and quickstart
 - **[CONTRIBUTING](CONTRIBUTING.md)** — Developer setup and conventions
 - **[.github/guidelines/knowledge-base.guidelines.md](.github/guidelines/knowledge-base.guidelines.md)** - How to use, update and maintain the knowledge base
+- **[.github/guidelines/git-commit-message.guideline.md](.github/guidelines/git-commit-message.guideline.md)** — Commit message conventions
 
 ## Technology Stack
 

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ### Feat
 
+- **cli**: add amend-commit command to inject session cost trailers
+
+## v0.4.0 (2026-07-08)
+
+### Feat
+
+- skill-aware cost attribution and tool-call tracking
 - add session filtering/aggregation/summaries/field extraction
 
 ## v0.3.0 (2026-07-06)

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.4.0
+Version: 0.5.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/en/stable/
@@ -11,6 +11,7 @@ License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0
+Requires-Dist: gitpython>=3.1.0
 Requires-Dist: ruamel-yaml>=0.18.0
 Description-Content-Type: text/markdown
 

copilot_session_usage-0.5.0/docs/source/how-to/add-commit-trailer.md

@@ -0,0 +1,133 @@
+# Add a Session Cost Trailer to a Commit
+
+Use `amend-commit` to append per-model token usage to the current Git commit
+as machine-readable trailers. This is useful for attributing cost to a change
+after a Copilot coding session, without editing the commit message by hand.
+
+## What the trailer looks like
+
+One `Copilot-Session-Usage-Acc` trailer is added per model used in the
+session, followed by a single `Copilot-Session-Usage-AIC` total-cost trailer:
+
+```text
+Copilot-Session-Usage-Acc: Moonshot AI:Kimi K2.7 Code,in:24.90,out:0.06,cache:21.88,aic:2.31
+Copilot-Session-Usage-Acc: Anthropic:Claude Haiku 4.5,in:0.03,out:0,cache:0,aic:0.01
+Copilot-Session-Usage-AIC: 23
+```
+
+Beware, the costs are **accumulated** for the entire session, not just the current commit.
+If you commit multiple times during a session, the trailers will reflect the total usage
+up to that point.
+
+When a change spans several VS Code Copilot sessions, pass each session ID
+with a separate `--session-id` argument. The costs are merged before the
+trailers are written. Add `--with-session-id` to also burn one
+`Copilot-Session-Usage-Session-ID` trailer per session ID, which is useful
+when you later want to rewrite the commit chain with commit-accurate costs.
+
+The vendor and model name come from the bundled pricing data. Vendor names are
+rendered with human-readable casing (`Moonshot AI`, `Anthropic`, `OpenAI`, …),
+and model names keep the casing from `data/models-and-pricing.yml`.
+
+Token counts are expressed in millions of tokens with two decimals. The
+`aic` value and the `Copilot-Session-Usage-AIC` line show the cost in AI
+credits (USD) with two decimals. If the commit already contains
+`Copilot-Session-Usage-Acc` or `Copilot-Session-Usage-AIC` trailers, they are
+replaced so the values stay fresh. Other trailers, such as `Signed-off-by`,
+are preserved and kept at the end of the message.
+
+## From VS Code Copilot context
+
+When running inside a VS Code Copilot agent session, the session log is exposed
+as the context variable `VSCODE_TARGET_SESSION_LOG`. Its value looks like:
+
+```text
+# Mac:
+/Users/<you>/Library/Application Support/Code/User/workspaceStorage/<hash>/GitHub.copilot-chat/debug-logs/<session-id>
+```
+
+The session ID is the last path component. Extract it and pass it to
+`amend-commit`:
+
+```bash
+SESSION_ID=$(basename "{{VSCODE_TARGET_SESSION_LOG}}")
+copilot-session-usage amend-commit --session-id "$SESSION_ID"
+```
+
+`VSCODE_TARGET_SESSION_LOG` is provided by VS Code Copilot as a **context**
+variable, not as an environment variable. If it is not available, use one of
+the methods below to locate the session ID manually.
+
+## Find the session ID manually
+
+List recent sessions and pick the right one:
+
+```bash
+# Show recent sessions with IDs and titles
+copilot-session-usage list --format table
+
+# Search by title substring
+copilot-session-usage list --title "refactor auth" --format table
+```
+
+Then pass the UUID to `amend-commit`:
+
+```bash
+copilot-session-usage amend-commit --session-id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56
+```
+
+## Multiple sessions per commit
+
+If a single change spanned several VS Code Copilot sessions, provide all
+session IDs. The token counts and costs are accumulated and written as one
+trailer block:
+
+```bash
+copilot-session-usage amend-commit \
+  --session-id "abc-123" \
+  --session-id "def-456" \
+  --session-id "ghi-789"
+```
+
+Add `--with-session-id` to also record every contributing session ID:
+
+```bash
+copilot-session-usage amend-commit \
+  --session-id "abc-123" \
+  --session-id "def-456" \
+  --with-session-id
+```
+
+This produces:
+
+```text
+Copilot-Session-Usage-Session-ID: abc-123
+Copilot-Session-Usage-Session-ID: def-456
+Copilot-Session-Usage-Acc: Moonshot AI:Kimi K2.7 Code,in:24.90,out:0.06,cache:21.88,aic:2.31
+Copilot-Session-Usage-AIC: 23
+```
+
+This will allow another process, not done by Copilot-Session-Cost, to later rewrite
+the commit chain with commit-accurate costs.
+
+## Preview before amending
+
+Use `--dry-run` to see the trailers that would be injected without modifying
+the commit:
+
+```bash
+copilot-session-usage amend-commit --session-id "$SESSION_ID" --dry-run
+```
+
+## Work in a different repository
+
+By default the current working directory is used to locate the Git repository.
+Override it with `--repo`:
+
+```bash
+copilot-session-usage amend-commit --session-id "$SESSION_ID" --repo /path/to/repo
+```
+
+## Full command reference
+
+See [CLI reference](../reference/cli.md) for all options and exit codes.

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/docs/source/how-to/index.md

@@ -6,6 +6,7 @@ Task-oriented recipes for common workflows.
 :maxdepth: 1
 
 analyze-specific-session
+add-commit-trailer
 export-json
 batch-and-spending
 wsl2

copilot_session_usage-0.5.0/docs/source/reference/cli.md

@@ -0,0 +1,11 @@
+# CLI Reference
+
+This page is auto-generated from the Click command definitions. For a
+step-by-step guide on using `amend-commit` to inject session cost trailers
+into Git commits, see [How to add a session cost trailer](../how-to/add-commit-trailer.md).
+
+```{eval-rst}
+.. click:: copilot_session_usage.cli:cli
+   :prog: copilot-session-usage
+   :nested: full
+```

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/justfile

@@ -129,3 +129,6 @@ clean:
 run-cli:
 	uv run -- copilot-session-usage batch 6 --format table
 	uv run -- copilot-session-usage batch 6 --format detailed
+
+run-amend-commit SESSION_ID:
+    uv run copilot-session-usage amend-commit --session-id {{SESSION_ID}}

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/pyproject.toml

@@ -9,6 +9,7 @@ license = "MIT"
 dependencies = [
     "click>=8.0",
     "ruamel.yaml>=0.18.0",
+    "GitPython>=3.1.0",
 ]
 
 [project.scripts]

{copilot_session_usage-0.4.0 → copilot_session_usage-0.5.0}/skills/copilot-session-usage/SKILL.md

@@ -9,6 +9,10 @@ Extract VS Code Copilot session cost KPIs from local debug logs.
 If you do not have information about which session to use, use `VSCODE_TARGET_SESSION_LOG`
 to find the current session ID.
 
+`VSCODE_TARGET_SESSION_LOG` is provided by VS Code Copilot as a **context/template variable**,
+not as an environment variable. Extract the session UUID from the last path component and
+pass it to the CLI with `--session-id`.
+
 Beware of `latest` session ID when several sessions are running in parallel.
 
 ## When to use
@@ -101,6 +105,13 @@ copilot-session-usage batch 10
 
 # Full detail JSON output
 copilot-session-usage latest --detail full --format json
+
+# Amend the current HEAD commit with accumulated session cost trailers.
+# Extract <session-id> from VSCODE_TARGET_SESSION_LOG in the Copilot context.
+copilot-session-usage amend-commit --session-id <session-id>
+
+# Preview trailers without amending
+copilot-session-usage amend-commit --session-id <session-id> --dry-run
 ```
 
 ## Skill-Aware Analysis
@@ -175,6 +186,50 @@ copilot-session-usage analyze --title "feature" --aggregate --skill-breakdown --
 - **Single-skill filtering** — focus analysis on one skill with `--skill SKILL`
 - **Skill aggregation** — list all skills and their costs across sessions with `skills` command
 - **Field extraction** with dot notation (`--query`)
+- **Commit amendment** with accumulated per-model cost trailers (`amend-commit`)
+
+## Injecting cost trailers into commits
+
+Use `amend-commit` to update the HEAD commit with accumulated session usage
+as Git commit-message trailers. One line is emitted per model, plus a total
+AIC (AI credits) summary line:
+
+```
+Copilot-Session-Usage-Acc: Moonshot AI:Kimi K2.7 Code,in:24.90,out:0.06,cache:21.88,aic:2.31
+Copilot-Session-Usage-AIC: 23
+```
+
+The vendor and model name come from the actual session context (debug-log
+`llm_request` events and bundled pricing data). Vendor names are rendered with
+human-readable casing (for example, `Moonshot AI` instead of `moonshot_ai`), and
+model names keep the casing from the pricing data (for example, `Kimi K2.7 Code`
+instead of the lower-cased log identifier `kimi-k2.7-code`). Token counts are in
+millions of tokens with two decimals; AIC values are rounded to two decimals.
+
+When a change spans several VS Code Copilot sessions, pass each session ID
+with a separate `--session-id` argument. The costs are accumulated and written
+as one trailer block. Add `--with-session-id` to also burn one
+`Copilot-Session-Usage-Session-ID` trailer per session ID, which makes it
+possible to rewrite the commit chain with commit-accurate costs later.
+
+### Finding the current session ID
+
+`VSCODE_TARGET_SESSION_LOG` is provided in the Copilot agent context as a
+template variable, **not** an environment variable. Extract the session UUID
+from the last path component:
+
+```bash
+# VSCODE_TARGET_SESSION_LOG looks like:
+# /.../workspaceStorage/<hash>/GitHub.copilot-chat/debug-logs/<session-id>
+SESSION_ID=$(basename "{{VSCODE_TARGET_SESSION_LOG}}")
+copilot-session-usage amend-commit --session-id "$SESSION_ID"
+```
+
+If the context does not expose the variable, fall back to `copilot-session-usage latest`
+or `copilot-session-usage list` to identify the session manually.
+
+`amend-commit` preserves any existing `Signed-off-by` trailer by placing the
+new cost trailers immediately before it, not after it.
 
 ## Pricing Data