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

copilot_session_usage-0.4.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.2.3 → copilot_session_usage-0.4.0}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ### Feat
 
+- 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)
+
+### Feat
+
 - accurate AIC cost computation using nanoAiu and cache_write
 
 ## v0.2.1 (2026-07-02)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.3
+Version: 0.4.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/
@@ -49,6 +49,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
@@ -58,8 +64,17 @@ copilot-session-usage batch 10
 - **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 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
 
@@ -91,12 +106,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
 
@@ -142,10 +175,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
@@ -154,7 +239,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")
@@ -164,6 +255,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

{copilot_session_usage-0.2.3 → copilot_session_usage-0.4.0}/README.md

@@ -33,6 +33,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
@@ -42,8 +48,17 @@ copilot-session-usage batch 10
 - **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 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
 
@@ -75,12 +90,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
 
@@ -126,10 +159,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
@@ -138,7 +223,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")
@@ -148,6 +239,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

{copilot_session_usage-0.2.3 → copilot_session_usage-0.4.0}/docs/source/explanation/how-cost-estimation-works.md

@@ -103,6 +103,24 @@ VS Code AIC panel at **0.000% error** for Claude models.
 tracks them separately so `--detail full` can show which fraction of tokens
 was consumed by subagents vs. the main conversation.
 
+Subagent names are extracted from the JSONL filename
+(`runSubagent-<Name>-functions.runSubagent:<id>.jsonl`) and from
+`child_session_ref` events in `main.jsonl`.
+
+## Skill attribution
+
+Skills are detected from three sources in the debug logs:
+
+- `user_message` events containing slash commands such as `/skill-name` or
+  `/namespace skill-name`.
+- `discovery` events of type `Skill Discovery` that list loaded skills.
+- `generic` events named `Custom Instructions` that enumerate on-demand skills.
+
+Each `llm_request` and `tool_call` is attributed to the most recently invoked
+skill at that timestamp. The result is included in the session report under the
+`skills` key and can be surfaced with `--skill-breakdown`, `--tool-breakdown`,
+or `--skill <name>`.
+
 ---
 
 ## Accuracy

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

@@ -0,0 +1,101 @@
+# 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 name regex across all sessions
+
+When you want to analyze several related sessions at once, use `analyze --name`
+with a case-insensitive regex. This is more efficient than running `find` or
+`list` and then analyzing each session separately.
+
+```bash
+# Analyze all sessions whose title matches a PRD or feature
+copilot-session-usage analyze --name "feature-x" --format table
+
+# Aggregate them into a single summary
+copilot-session-usage analyze --name "feature-x" --aggregate --format table
+
+# Cost-efficiency summary for each matching session
+copilot-session-usage analyze --name "feature-x" --summary --format table
+```
+
+Add `--since` and `--until` to narrow the date range, or `--workspace` to
+restrict to one workspace folder.
+
+## 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.
+
+You can also filter `list` and `analyze` by title substring with `--title`:
+
+```bash
+# List only sessions whose title contains "get-session-costs"
+copilot-session-usage list --title "get-session-costs"
+
+# Analyze the most recent matching session
+copilot-session-usage analyze --title "grill-me" --latest --format table
+```
+
+## Skill-aware analysis
+
+When a session invokes a skill (for example `/compendium-generic get-session-costs`),
+you can attribute costs and tool calls to that skill.
+
+```bash
+# Per-skill cost breakdown for a session
+copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56 --skill-breakdown
+
+# Per-skill/per-subagent tool-call counts
+copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56 --tool-breakdown
+
+# Concise cost for a single skill
+copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56 \
+  --skill "/compendium-generic get-session-costs" \
+  --format json --detail minimal
+```
+
+## List skills across sessions
+
+```bash
+# Skills used in the last 7 days, with aggregated cost
+copilot-session-usage skills --last 7d --format table
+```
+
+## 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.3 → copilot_session_usage-0.4.0}/docs/source/how-to/batch-and-spending.md

@@ -2,6 +2,14 @@
 
 Use `batch` with `--since` to aggregate costs for a time window.
 
+For a specific set of related sessions (for example, all sessions whose title
+matches a PRD or feature), prefer `analyze --name ... --aggregate`. It reads
+only matching sessions and returns a single summary in one command.
+
+```bash
+copilot-session-usage analyze --name "feature-x" --aggregate --format table
+```
+
 ## Daily cost report
 
 ```bash
@@ -53,6 +61,28 @@ copilot-session-usage batch 50 \
 `--workspace-filter` matches against the workspace folder name (substring,
 case-insensitive).
 
+## Skill spending report
+
+Use the `skills` command to see which skills drove the most cost over a time
+window:
+
+```bash
+# Skills used in the last 7 days
+copilot-session-usage skills --last 7d --format table
+
+# Skills used since a specific date
+copilot-session-usage skills --since 2026-07-01 --format table
+```
+
+Output:
+
+```
+Skills across 23 sessions:
+  Skill                              Sessions        Input     Output       Cached   Calls       Cost
+  ---------------------------------------------------------------------------------------------------
+  /compendium-generic get-session-costs       3    1137864      15729      1015825      24  $0.3636
+```
+
 ## Automate with cron (macOS/Linux)
 
 ```bash