feat: Improve some designs and sense

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 ## Summary
 
-<!-- Briefly describe what this PR does and why. Link the related issue if one exists. -->
+<!-- Briefly describe what this PR changes and why. Link the related issue if one exists. -->
 
 Closes #
 
@@ -20,6 +20,20 @@ Closes #
 - [ ] Documentation
 - [ ] Chore / dependency update
 
+## Commit / PR title
+
+<!--
+Use Conventional Commits. The PR title should match the final squash/rebase title.
+Examples:
+- feat(dashboard): add weekly token comparison
+- fix(parser): handle missing session metadata
+- docs: update release workflow notes
+- chore(ci): enforce conventional commit messages
+-->
+
+- [ ] PR title follows Conventional Commits (`type(scope): description` or `type: description`)
+- [ ] All commit messages in this PR follow Conventional Commits
+
 ## Testing
 
 <!-- Describe how you tested this change. -->
@@ -38,7 +52,9 @@ Closes #
 
 ## Checklist
 
+- [ ] This PR targets `dev` (feature/fix work should not target `main`)
 - [ ] My code follows the project's coding conventions
 - [ ] I have read the [CONTRIBUTING guide](../CONTRIBUTING.md)
 - [ ] No new dependencies added without discussion
 - [ ] No `console.log` or debug statements left in
+- [ ] If this PR will be merged to `main`, it will use **Squash and merge** or **Rebase and merge** instead of **Create a merge commit**

CLAUDE.md

@@ -104,7 +104,7 @@ Data flows one way: `JSONL files → FileWatcher → DashboardStore → Panel.bu
 | View | File | Description |
 |---|---|---|
 | Dashboard | `views/Dashboard.tsx` | 3 tabs: Overview (recap, stats, projects), Charts (usage, cost), Insights (heatmap, efficiency, tools, hot files) |
-| ProjectDetail | `views/ProjectDetail.tsx` | 8 tabs: Sessions, Weekly, CLAUDE.md, Commands, Tools, MCP Servers, Subagents, Files |
+| ProjectDetail | `views/ProjectDetail.tsx` | 12 tabs: Sessions, Weekly, CLAUDE.md, Commands, Tools, MCP Servers, Subagents, Files, Memory, Todos, Commits, Settings |
 | Sidebar | `views/Sidebar.tsx` | Compact project list grouped by Active/Recent/Older with stats |
 
 **Components (all in `components/`):**
@@ -149,12 +149,16 @@ Session turns are **lazy-loaded**: initial state ships sessions with `turns: []`
 ### Key Data Types (in `webview-ui/src/types.ts`)
 
 - **Project** — `{ id, name, path, lastActive, isActive, sessionCount, totalTokens, totalCostUsd, techStack[] }`
-- **Session** — `{ id, projectId, parentSessionId, startTime, endTime, durationMs, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, totalTokens, costUsd, promptCount, toolCallCount, filesModified[], filesCreated[], turns[], sessionSummary, hasThinking, thinkingTokens, cacheHitRate, subagentCostUsd, idleTimeMs, activeTimeMs, activityRatio }`
+- **Session** — `{ id, projectId, parentSessionId, startTime, endTime, durationMs, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, totalTokens, costUsd, promptCount, toolCallCount, filesModified[], filesCreated[], turns[], sessionSummary, hasThinking, thinkingTokens, cacheHitRate, subagentCostUsd, idleTimeMs, activeTimeMs, activityRatio, model }`
 - **Turn** — `{ id, role, content, inputTokens, outputTokens, toolCalls[], timestamp }`
 - **ToolCall** — `{ id, name, input, output?, mcpServer? }`
-- **ProjectConfig** — `{ claudeMd, mcpServers, projectSettings, commands[] }`
+- **ProjectConfig** — `{ claudeMd, mcpServers, projectSettings, commands[], memory, hooks[] }`
 - **ProjectStats** — `{ usageOverTime[], toolUsage[], promptPatterns[], efficiency, recentToolCalls[], weeklyStats }`
 - **DashboardStats** — `{ totalProjects, activeSessionCount, tokensTodayTotal, costTodayUsd, tokensWeekTotal, costWeekUsd }`
+- **ProjectMemory** — `{ index, files: MemoryFile[] }` where `MemoryFile` = `{ name, description, type, content }`
+- **SessionTodoSnapshot** — `{ sessionId, sessionDate, sessionSummary, todos: { content, status }[], timestamp }`
+- **ClaudeCommit** — `{ hash, shortHash, author, date, subject, filesChanged }`
+- **HookConfig** — `{ event, matcher?, command }`
 
 Other types: `DailyUsage`, `ProjectUsage`, `HeatmapCell`, `PatternCount`, `ToolUsageStat`, `HotFile`, `ProjectedCost`, `StreakData`, `EfficiencyStats`, `WeeklyRecap`, `RecentFileChange`, `ProductivityHour`, `BudgetStatus`, `ProjectFile`, `ProjectToolCall`, `WeeklyProjectStats`, `McpServer`, `PromptSearchResult`
 
@@ -190,12 +194,8 @@ Other types: `DailyUsage`, `ProjectUsage`, `HeatmapCell`, `PatternCount`, `ToolU
 ### Not Yet Implemented
 
 These Claude Code features are **not captured or displayed** by the dashboard:
-- **Memory** — `~/.claude/projects/{path}/memory/MEMORY.md` + individual memory files
-- **Todos/Tasks** — `TodoWrite` tool calls within sessions
-- **Plans** — Implementation plans created during sessions
-- **Git commits by Claude** — commits with `Co-Authored-By: Claude` signature
-- **Scheduled triggers** — cron-based remote agents
-- **Worktrees** — isolated git worktrees created by subagents
-- **Model per session** — parsed for cost calc but not shown in UI
-- **Project settings** — parsed but not surfaced in webview
-- **Hook configuration** — used internally but not visualized
+- **Plans** — Implementation plans created during sessions (conversational, no persistent data)
+- **Scheduled triggers** — cron-based remote agents (no local data source)
+- **Worktrees** — isolated git worktrees created by subagents (visible in Tools tab as tool calls)
+- **Session diff viewer** — `~/.claude/file-history/` before/after file changes
+- **Prompt library** — starred/saved prompts and pattern detection

DATA_SOURCES.md

@@ -175,7 +175,7 @@ Expressed as a percentage and shown in green in the session detail bar. A high r
 
 ## 4. Cost Calculation
 
-Cost is calculated accurately using all 4 token types at their correct rates per model:
+Cost is estimated locally using all 4 token types, a bundled pricing table, and a heuristic model-family mapping. It is intended to be directionally useful inside the dashboard and may not exactly match Anthropic billing.
 
 ### Pricing rates (per 1M tokens)
 
@@ -207,11 +207,13 @@ Note: cache read is the dominant cost driver in long sessions, even at 0.1× the
 
 ### Model detection
 
-The model name is read from `message.model` on each assistant turn (e.g. `"claude-sonnet-4-6"`). We match it to a pricing tier:
+The model name is read from `message.model` on each assistant turn (e.g. `"claude-sonnet-4-6"`). We map it to a pricing tier heuristically:
 - Contains `"opus"` → claude-opus-4 rates
 - Contains `"haiku"` → claude-haiku-4 rates
 - Everything else → claude-sonnet-4 rates (default)
 
+This means unknown or future model names currently fall back to Sonnet pricing unless they contain `opus` or `haiku`.
+
 ---
 
 ## 5. Session Metadata
@@ -375,19 +377,19 @@ All analytics are computed in-memory from the parsed session data. Nothing is st
 | Metric | How it's computed |
 |---|---|
 | **Tokens today** | Sum `totalTokens` for sessions where `startTime` > midnight today |
-| **Cost today** | Sum `costUsd` for sessions where `startTime` > midnight today |
-| **Usage over time** | Group sessions by calendar day, sum tokens and cost per day |
+| **Cost today** | Sum estimated session cost for sessions where `startTime` > midnight today, including attributed `subagentCostUsd` |
+| **Usage over time** | Group sessions by calendar day, sum tokens and estimated cost per day |
 | **Hot files** | Count occurrences of each path across all sessions' `filesModified` arrays, across all projects |
 | **Tool usage** | Count each `toolCall.name` across all turns in all sessions |
 | **Streak** | Build a set of unique calendar dates with any session activity, walk backwards from today |
 | **Efficiency — avg tokens/prompt** | `totalTokens / promptCount` across all sessions |
 | **Efficiency — first-turn resolution** | % of sessions where `promptCount === 1` |
-| **Projected monthly cost** | `(currentMonthCost / daysElapsed) × daysInMonth` |
+| **Projected monthly cost** | `(currentMonthCost / daysElapsed) × daysInMonth`, using estimated cost including attributed `subagentCostUsd` |
 | **Productivity by hour** | Group sessions by `new Date(startTime).getHours()`, average tool calls and files modified |
 | **Heatmap** | Group sessions by `[dayOfWeek, hour]`, sum tokens per cell |
 | **Prompt patterns** | Classify each user turn by keyword regex into: Fix/Bug, Explain, Refactor, Feature, Test, Other |
 | **Cache hit rate** | Per session: `cacheRead / (input + cacheCreation + cacheRead) × 100` |
-| **Monthly usage** | Sum `totalTokens` and `costUsd` (including `subagentCostUsd`) for sessions since the 1st of the current month |
+| **Monthly usage** | Sum `totalTokens` and estimated session cost (including `subagentCostUsd`) for sessions since the 1st of the current month |
 
 ### Per-project
 

PRODUCT.md

@@ -2,7 +2,7 @@
 
 ## What It Is
 
-Claude Code Dashboard is a VS Code extension that turns the raw session data Claude Code writes to `~/.claude/` into a living analytics layer for developers. Every time you run a Claude session — asking it to fix a bug, build a feature, refactor a module — Claude records the conversation in a JSONL file on disk. The dashboard reads those files and surfaces the things developers actually want to know: what did I spend today, what sessions cost the most, which files does Claude keep touching, how efficient are my prompts, and is Claude running right now?
+Claude Code Dashboard is a VS Code extension that turns the raw session data Claude Code writes to `~/.claude/` into a living analytics layer for developers. Every time you run a Claude session — asking it to fix a bug, build a feature, refactor a module — Claude records the conversation in a JSONL file on disk. The dashboard reads those files and surfaces the things developers actually want to know: what is my token usage today, what is my estimated spend, which sessions seem most expensive, which files does Claude keep touching, how efficient are my prompts, and is Claude running right now?
 
 It is not a SaaS product. It does not send any data anywhere. It reads files that already exist on your machine and presents them inside VS Code.
 
@@ -25,16 +25,16 @@ The data to answer all of these questions is sitting in `~/.claude/projects/` 
 
 ## Who It Is For
 
-**Primary user:** A developer who uses Claude Code every day across multiple projects and wants visibility into their usage, costs, and patterns. They are comfortable with VS Code extensions and are not looking for a web dashboard — they want this information where they already work.
+**Primary user:** A developer who uses Claude Code every day across multiple projects and wants visibility into their usage, estimated costs, and patterns. They are comfortable with VS Code extensions and are not looking for a web dashboard — they want this information where they already work.
 
-**Secondary user:** A team lead or freelancer who bills clients by AI-assisted work and needs accurate records of which projects consumed what.
+**Secondary user:** A team lead or freelancer who wants project-level usage allocation for AI-assisted work and needs a fast local approximation of which projects consumed what. This is operational visibility, not billing-grade reporting.
 
 ---
 
 ## Core Value Propositions
 
 ### 1. Cost awareness in real time
-The status bar shows today's token count and dollar cost at a glance, updated whenever a session file changes. No waiting for a monthly bill. You know what you spent before you close your laptop.
+The status bar shows today's token count and estimated dollar cost at a glance, updated whenever a session file changes. No waiting for a monthly bill. You get a fast local approximation of spend before you close your laptop.
 
 ### 2. Session-level accountability
 Every session is a record: when it started, how long it ran, how many prompts it took, which files it touched, and exactly what the first prompt was. The session summary line (the first user prompt shown as a preview) answers "what was I doing in this session?" without having to open it.
@@ -53,7 +53,7 @@ Knowing whether Claude is actually running right now (not just "was active 20 mi
 ## Feature Inventory
 
 ### Status Bar
-- Live token count and cost for today
+- Live token count and estimated cost for today
 - Session count indicator (pulses when a session is active)
 - Clicks open the full dashboard
 
@@ -65,16 +65,16 @@ Knowing whether Claude is actually running right now (not just "was active 20 mi
 
 ### Dashboard — Overview Tab
 - Budget alert banner (yellow at 80%, red at 100%)
-- Weekly recap card: sessions, projects, tokens, cost, files modified, top project, streak
-- Stats strip: tokens today / cost today / tokens this week / cost this week
+- Weekly recap card: sessions, projects, tokens, estimated cost, files modified, top project, streak
+- Stats strip: tokens today / estimated cost today / tokens this week / estimated cost this week
 - Active project cards with live pulse animation
-- Filterable, sortable project list (filter by name; sort by last active, cost, or session count)
+- Filterable, sortable project list (filter by name; sort by last active, estimated cost, or session count)
 
 ### Dashboard — Charts Tab
 - Token usage over the last 30 days (line chart)
 - Token usage by project (bar chart)
-- Projected monthly cost with progress bar
-- Cost by project this month (horizontal bar chart)
+- Projected monthly estimated cost with progress bar
+- Estimated cost by project this month (horizontal bar chart)
 
 ### Dashboard — Search Tab
 - Full-text search across every user prompt ever written
@@ -92,7 +92,7 @@ Knowing whether Claude is actually running right now (not just "was active 20 mi
 
 ### Project Detail View
 - Project header with tech stack badges, path, and live indicator
-- Stats: total tokens, total cost, session count
+- Stats: total tokens, estimated cost, session count
 - Sessions tab: chronological session list with:
   - Session summary line (first user prompt as italic preview)
   - Extended thinking badge (⚡) for sessions that used thinking mode
@@ -106,7 +106,7 @@ Knowing whether Claude is actually running right now (not just "was active 20 mi
 
 ### Alert System
 - Monthly token budget: alert when monthly token count exceeds configured limit
-- Monthly cost budget: alert at 80% and 100% of configured USD amount
+- Monthly estimated cost budget: alert at 80% and 100% of configured USD amount
 - Weekly digest: Monday morning recap (sessions, projects, tokens, top project)
 - All alerts fire as VS Code notifications; max once per day to avoid spam
 
@@ -134,6 +134,17 @@ The extension never writes to any of these files except `settings.json` (to inje
 
 ---
 
+## Token And Cost Semantics
+
+- Token counts come from Claude's local JSONL session logs.
+- Displayed `totalTokens` exclude cache-read tokens, because cache reads can dwarf the meaningful token count in long sessions.
+- Estimated cost is computed locally from parsed token usage, detected model family, and a static pricing table bundled with the extension.
+- Model detection is heuristic: `opus` maps to Opus pricing, `haiku` maps to Haiku pricing, and everything else falls back to Sonnet pricing.
+- Aggregate estimated cost includes subagent-attributed cost when Claude spawns subagents.
+- These numbers are helpful operational estimates, but they are not guaranteed to match Anthropic billing, invoices, or future price changes exactly.
+
+---
+
 ## What It Does Not Do
 
 - It does not intercept Claude's network calls or modify Claude's behaviour.

README.md

@@ -1,6 +1,6 @@
 # Claude Code Dashboard
 
-A VS Code extension that shows you exactly what Claude is doing — tokens, costs, sessions, and insights across all your projects, right inside VS Code.
+A VS Code extension that shows you what Claude is doing on your machine — token usage, estimated costs, sessions, and insights across all your projects, right inside VS Code.
 
 **No API key required. No data leaves your machine.**
 
@@ -14,10 +14,10 @@ A VS Code extension that shows you exactly what Claude is doing — tokens, cost
 ## Screenshots
 
 ![Dashboard Overview](https://raw.githubusercontent.com/jspw/Claude-Code-Dashboard/main/images/screenshots/dashboard.png)
-*Main dashboard — projects, stats, weekly recap, and cost overview*
+*Main dashboard — projects, stats, weekly recap, and estimated cost overview*
 
 ![Dashboard Charts](https://raw.githubusercontent.com/jspw/Claude-Code-Dashboard/main/images/screenshots/dashboard-chart.png)
-*Charts tab — 30-day token trend, usage by project, projected monthly cost*
+*Charts tab — 30-day token trend, usage by project, projected monthly estimated cost*
 
 ![Dashboard Insights](https://raw.githubusercontent.com/jspw/Claude-Code-Dashboard/main/images/screenshots/dashbpard-insights.png)
 *Insights tab — heatmap, tool usage, productivity by hour, hot files*
@@ -52,12 +52,20 @@ Search for **Claude Code Dashboard** in the VS Code Extensions panel, or install
 
 | Tab | What you see |
 |---|---|
-| **Overview** | Weekly recap, today's tokens & cost, active sessions, full project list |
-| **Charts** | 30-day token trend, usage by project, projected monthly cost |
+| **Overview** | Weekly recap, today's tokens & estimated cost, active sessions, full project list |
+| **Charts** | 30-day token trend, usage by project, projected monthly estimated cost |
 | **Search** | Full-text search across every prompt you've ever sent to Claude |
 | **Insights** | Usage heatmap, tool breakdown, productivity by hour, hot files |
 
-**Project detail view** — click any project to see its full session history, turn-by-turn conversation, token breakdown, files touched, CLAUDE.md, and MCP servers. Export to JSON or CSV any time.
+**Project detail view** — click any project to see its full session history, turn-by-turn conversation, token breakdown, estimated cost, files touched, CLAUDE.md, and MCP servers. Export to JSON or CSV any time.
+
+## Token and cost notes
+
+- Token counts come from local Claude session logs in `~/.claude/projects/`.
+- Displayed `totalTokens` exclude cache-read tokens, which Claude may reuse heavily across long sessions.
+- Cost is a local estimate based on detected model family, a static pricing table, and parsed token usage.
+- Aggregate cost views include subagent-attributed cost when Claude spawns subagents.
+- Estimated cost may differ from Anthropic billing, invoices, or future pricing changes.
 
 ---
 
@@ -68,7 +76,7 @@ Search for **Claude Code Dashboard** in VS Code settings (`Cmd+,` / `Ctrl+,`).
 | Setting | Default | Description |
 |---|---|---|
 | `claudeDashboard.monthlyTokenBudget` | `0` | Monthly token cap. Set to `0` to disable. |
-| `claudeDashboard.monthlyBudgetUsd` | `0` | Monthly cost cap in USD. Alerts at 80% and 100%. Set to `0` to disable. |
+| `claudeDashboard.monthlyBudgetUsd` | `0` | Monthly estimated cost cap in USD. Alerts at 80% and 100%. Set to `0` to disable. |
 
 ---
 
@@ -81,7 +89,7 @@ Search for **Claude Code Dashboard** in VS Code settings (`Cmd+,` / `Ctrl+,`).
 — Confirm hooks were configured at first run. Check `~/.claude/settings.json` for entries referencing `.dashboard-events.jsonl`. The file watcher fallback still updates within ~300ms.
 
 **Cost numbers look off**
-— Costs are estimated from Anthropic's published per-model token rates. Cache read tokens are tracked separately and excluded from `totalTokens` (they bill at ~10% of regular input tokens).
+— Cost is estimated locally from parsed token usage, detected model family, and a static pricing table. Cache read tokens are tracked separately and excluded from `totalTokens`, but still contribute to estimated cost.
 
 **Corrupted `settings.json` after hook injection**
 — Restore the backup: `cp ~/.claude/settings.json.bak ~/.claude/settings.json`