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

copilot_session_usage-0.5.0/.github/changes/requests/skill-breakdown/01-request.md

@@ -0,0 +1,163 @@
+# Skill-aware cost attribution and faster session lookup
+
+## Context
+
+`copilot-session-usage` extracts VS Code Copilot session cost KPIs from local debug logs. It already supports per-model pricing, subagent attribution, and multiple output formats.
+
+However, when a user invokes a skill (e.g. `/compendium-generic get-session-costs`), the CLI has no first-class way to report:
+
+- which skill(s) were active in a session,
+- how much each skill cost,
+- which tool calls each skill triggered,
+- or how to find a session by its title without manually scanning `copilot-session-usage list` output.
+
+Investigating a single skill's cost currently requires ad-hoc Python scripts that grep raw JSONL files for slash-command names, skill discovery events, and tool-call records. This is slow, token-heavy, error-prone, and not reproducible.
+
+## Problem
+
+1. **No skill cost attribution.** A session may be dominated by one skill, but the CLI only reports per-model and per-subagent totals.
+2. **Session lookup by title is manual.** Users must run `list`, visually scan titles, copy the UUID, then run `id <uuid>`.
+3. **Subagent names are often `unknown`.** The subagent spawned by `runSubagent` is reported as `unknown` even though its name appears in the debug-log filename.
+4. **No tool-call attribution.** It is impossible to see which tools a skill consumed tokens on.
+5. **No stable, concise report format.** Full JSON dumps are large; users often only need skill + cost + token counts.
+
+## Goals
+
+Make `copilot-session-usage` **faster, safer, cheaper, and more reproducible** for skill-centric cost analysis by:
+
+- detecting skills from system prompts, tool definitions, and user messages,
+- attributing LLM calls and tool calls to the active skill,
+- allowing users to filter sessions by title and skill,
+- fixing subagent name extraction,
+- providing a concise, stable output mode.
+
+## Proposed features
+
+### 1. Skill cost breakdown
+
+Add a `--skill-breakdown` flag to `id` and `analyze` that emits a per-skill table:
+
+```markdown
+| Skill | Input Tokens | Output Tokens | Cached Tokens | LLM Calls | Cost |
+|-------|--------------|---------------|---------------|-----------|------|
+| /compendium-generic get-session-costs | 1,137,864 | 15,729 | 1,015,825 | 24 | $0.3636 |
+```
+
+Implementation notes:
+
+- Parse `system_prompt_0.json` for loaded skill lists.
+- Parse `tools_0.json` for the `skill` tool definition and any skill-related slash commands.
+- Parse `user_message` events for slash-command invocations (`/<skill-name> ...`).
+- Parse `discovery` events of type `Skill Discovery` as a fallback.
+- Attribute each turn to the most recently invoked skill.
+
+### 2. Filter sessions by title
+
+Add `--title <substring>` to `list` and `analyze`:
+
+```bash
+copilot-session-usage list --title "get-session-costs"
+copilot-session-usage analyze --title "grill-me" --latest
+```
+
+This avoids analyzing irrelevant sessions and reduces token consumption.
+
+### 3. Filter analysis by skill
+
+Add `--skill <name>` to `id` and `analyze`:
+
+```bash
+copilot-session-usage id <uuid> --skill "/compendium-generic get-session-costs"
+```
+
+When combined with `--format json --minimal`, this returns only the numbers the user asked for.
+
+### 4. Tool-call attribution per skill
+
+Add `--tool-breakdown` to `id` and `analyze`:
+
+```markdown
+| Tool | Calls | Skill | Subagent |
+|------|-------|-------|----------|
+| read_file | 25 | /compendium-generic get-session-costs | main, Explore |
+| vscode_askQuestions | 3 | /compendium-generic get-session-costs | main |
+| runSubagent | 1 | /compendium-generic get-session-costs | main |
+```
+
+### 5. Fix subagent name extraction
+
+The subagent log file is named `runSubagent-Explore-functions.runSubagent:4.jsonl`. The CLI should extract `Explore` from the filename instead of reporting `unknown`.
+
+Also handle `child_session_ref` events in `main.jsonl` as an additional source of subagent metadata.
+
+### 6. Concise / minimal output mode
+
+Add `--minimal` (or extend `--detail minimal`) to return only essential fields:
+
+```bash
+copilot-session-usage id <uuid> --skill "/compendium-generic get-session-costs" --format json --minimal
+```
+
+```json
+{
+  "skill": "/compendium-generic get-session-costs",
+  "cost_usd": 0.3636,
+  "input_tokens": 1137864,
+  "output_tokens": 15729,
+  "llm_calls": 24
+}
+```
+
+### 7. Skill discovery across sessions
+
+Add a `skills` command to list skills used over a time window:
+
+```bash
+copilot-session-usage skills --last 7d
+```
+
+Output:
+
+```markdown
+| Skill | Sessions | LLM Calls | Cost |
+|-------|----------|-----------|------|
+| /compendium-generic get-session-costs | 3 | 42 | $0.89 |
+```
+
+### 8. Metadata cache for faster repeated queries
+
+Cache session metadata (title, created_at, has_debug_logs, debug_log_dir) in a small local index keyed by workspace hash. Invalidate when `state.vscdb` mtime changes. This makes `list --title` and `batch` operations near-instant.
+
+## Acceptance criteria
+
+- [ ] `copilot-session-usage id <uuid> --skill-breakdown` prints a per-skill cost table.
+- [ ] `copilot-session-usage list --title <substring>` returns only matching sessions.
+- [ ] `copilot-session-usage analyze --title <substring> --latest` analyzes the most recent matching session.
+- [ ] `copilot-session-usage id <uuid> --skill "<name>"` filters the report to that skill.
+- [ ] Subagents spawned by `runSubagent` show their real name, not `unknown`.
+- [ ] `copilot-session-usage id <uuid> --tool-breakdown` prints per-skill/per-subagent tool-call counts.
+- [ ] `copilot-session-usage id <uuid> --format json --minimal` returns a small, stable JSON object.
+- [ ] `copilot-session-usage skills --last 7d` lists skills with aggregated cost.
+- [ ] All new features are covered by unit tests.
+- [ ] `just preflight` passes.
+
+## Non-goals
+
+- Do not modify pricing data or model detection logic.
+- Do not add support for non-VS-Code providers (CLI provider remains planned).
+- Do not persist raw debug logs or user message content in the metadata cache.
+
+## Suggested first slice
+
+1. Add `--title` filter to `list` and `analyze`.
+2. Add `--skill-breakdown` to `id` / `analyze`.
+3. Fix subagent name extraction (`unknown` → real name).
+
+These three changes alone remove the most common manual steps and make skill-cost investigations reproducible from a single CLI command.
+
+## Reference session
+
+- Session ID: `44f6a978-243c-4115-aa90-d11c2ccf56e0`
+- Title: `/compendium-generic grill-me here are proposal of improvement in copilot-session-usage, to make its use even way more token efficient:`
+- Skill invoked: `/compendium-generic get-session-costs`
+- Total cost: $0.3636 | 1,137,864 input + 15,729 output tokens | 24 LLM calls

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.3.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.3.0 → copilot_session_usage-0.5.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## Unreleased
 
+### 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)
+
 ## v0.2.3 (2026-07-03)
 
 ## v0.2.2 (2026-07-03)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.3.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
 
@@ -49,6 +50,12 @@ copilot-session-usage list
 
 # Batch analyze the last 10 sessions
 copilot-session-usage batch 10
+
+# Aggregate cost across all sessions matching a PRD path
+copilot-session-usage analyze --name "PRD: /path/to/prd" --aggregate --format table
+
+# List sessions in a debug-logs folder with cost columns
+copilot-session-usage list --dir /path/to/debug-logs --format table
 ```
 
 ## Features
@@ -61,6 +68,14 @@ copilot-session-usage batch 10
 - **Three output formats** — `json` (default), `table`, `detailed`
 - **Three detail levels** — `minimal`, `compact`, `full`
 - **JSON and table output** — machine-readable or human-friendly
+- **Session filtering** — regex match by name, date-range filtering
+- **Aggregation** — roll up costs across many sessions in one command
+- **Skill-aware cost attribution** — detect skills, attribute LLM and tool calls to the active skill
+- **Skill cost breakdown** — per-skill token counts and estimated cost
+- **Tool-call attribution** — per-skill/per-subagent tool-call counts
+- **Title filtering** — find sessions by title substring
+- **Efficiency summaries** — cache ratio, model split, cost per 1M tokens
+- **Field extraction** — pull specific values with `--query`
 
 ## How it works
 
@@ -92,12 +107,30 @@ just knowledge-validate
 
 | Command | Description |
 |---------|-------------|
-| `analyze PATH` | Analyze one session by its debug-log directory |
+| `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) |
 | `id SESSION_ID` | Analyze a session by exact UUID |
-| `list` | List recent sessions (metadata only, no cost) |
+| `list` | List recent sessions (metadata only by default) |
 | `batch N` | Analyze the N most recent sessions in one pass |
+| `skills` | List skills used across sessions with aggregated cost |
+
+### Analysis options
+
+| Option | Description |
+|--------|-------------|
+| `--name REGEX` | Filter sessions by title/ID regex (case-insensitive) |
+| `--title SUBSTRING` | Filter sessions by title substring (case-insensitive) |
+| `--since DATE` | Only sessions created after DATE (ISO 8601 with timezone) |
+| `--until DATE` | Only sessions created before DATE (ISO 8601 with timezone) |
+| `--workspace PATH` | Only sessions from this workspace folder |
+| `--aggregate` | Aggregate all matching sessions into one summary |
+| `--summary` | Output a cost-efficiency summary |
+| `--skill-breakdown` | Emit a per-skill cost breakdown |
+| `--tool-breakdown` | Emit a per-skill/per-subagent tool-call count breakdown |
+| `--skill NAME` | Filter the report to a single skill |
+| `--query PATH` | Extract a single field with dot notation |
+| `--query-help` | Print all `--query` field paths |
 
 ### Global options
 
@@ -143,10 +176,62 @@ Output:    22,166 tokens
 Cached:    1,224,340 (86%)
 LLM calls: 28
 Est. cost: $1.0880
+# Per-skill cost breakdown
+$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --skill-breakdown --format table
+Per-Skill Breakdown:
+  Skill                              Input      Cached  Output  Calls     Cost
+  ----------------------------------------------------------------------------
+  /compendium-generic get-session-costs  1,137,864  1,015,825  15,729     24  $0.3636
+
+# Per-skill/per-subagent tool-call counts
+$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 --tool-breakdown --format table
+Tool Breakdown:
+  Tool                          Calls  Skill                         Subagent
+  ---------------------------------------------------------------------------
+  read_file                        25  /compendium-generic get-session-costs  main
+  vscode_askQuestions               3  /compendium-generic get-session-costs  main
+  runSubagent                       1  /compendium-generic get-session-costs  main
+
+# Concise skill cost (great for scripts)
+$ copilot-session-usage id 19e03be0-9cfa-4f21-a19a-4bdb754b3965 \
+    --skill "/compendium-generic get-session-costs" \
+    --format json --detail minimal
+{
+  "skill": "/compendium-generic get-session-costs",
+  "cost_usd": 0.3636,
+  "input_tokens": 1137864,
+  "output_tokens": 15729,
+  "cached_tokens": 1015825,
+  "llm_calls": 24
+}
+
+# List skills used across the last 7 days
+$ copilot-session-usage skills --last 7d --format table
+Skills across 23 sessions:
+  Skill                              Sessions        Input     Output       Cached   Calls       Cost
+  ---------------------------------------------------------------------------------------------------
+  /compendium-generic get-session-costs       3    1137864      15729      1015825      24  $0.3636
 
+# Filter sessions by title substring
+$ copilot-session-usage list --title "get-session-costs"
+$ copilot-session-usage analyze --title "grill-me" --latest
 # Batch analyze last 5 sessions since July 1st
 copilot-session-usage batch 5 --since 2026-07-01
 
+# Aggregate all PRD-related sessions from the last week
+copilot-session-usage analyze \
+  --name "PRD: /path/to/prd" \
+  --since 2026-06-30T00:00:00Z \
+  --until 2026-07-07T00:00:00Z \
+  --aggregate \
+  --format table
+
+# Cost-efficiency summary for a single session
+copilot-session-usage analyze /path/to/debug-logs --summary --format table
+
+# Extract just the total cost from a session
+copilot-session-usage analyze /path/to/debug-logs --query .total.estimated_usd
+
 # WSL2: point to Windows host workspaceStorage
 copilot-session-usage latest \
   --workspace-storage /mnt/c/Users/$USER/AppData/Roaming/Code/User/workspaceStorage
@@ -155,7 +240,13 @@ copilot-session-usage latest \
 ## Python API
 
 ```python
-from copilot_session_usage.api import analyze_session, analyze_latest, batch_analyze
+from copilot_session_usage.api import (
+    analyze_session,
+    analyze_latest,
+    batch_analyze,
+    aggregate_sessions,
+    list_sessions,
+)
 
 # Analyze a session by path
 result = analyze_session(Path("/path/to/debug-logs"), detail="full")
@@ -165,6 +256,16 @@ result = analyze_latest(detail="compact")
 
 # Batch analyze the last 10 sessions
 batch = batch_analyze(10, detail="minimal")
+
+# Aggregate multiple full analyses into one efficiency summary
+aggregate = aggregate_sessions([result1, result2])
+
+# List sessions with regex and date-range filtering
+sessions = list_sessions(
+    name_pattern=r"PRD",
+    since="2026-07-01T00:00:00Z",
+    until="2026-07-07T00:00:00Z",
+)
 ```
 
 ## Development