# Session Analysis Report — Design Document

**Date:** 2026-02-21
**Status:** Approved

## Overview

Port the `scripts/analyze-session.py` analysis logic to TypeScript and display results as a beautifully formatted report in a new tab. An Activity icon button in the session toolbar triggers the analysis.

## Decisions

- **TypeScript port** — no Python dependency; runs in-process in the renderer
- **New tab** — opens a dedicated report tab (consistent with Settings/Notifications pattern)
- **Activity icon** — in the toolbar next to the Export dropdown
- **Full port** — all ~30 analysis sections from the Python script
- **Renderer-only** — no new IPC; `SessionDetail.messages` already has all raw data

## Architecture

```
TabBar.tsx (Activity button click)
  → store action: openSessionReport(sourceTabId)
    → creates tab { type: 'report', projectId, sessionId, sourceTabId }
    → SessionReportTab mounts
      → analyzeSession(sessionDetail) from sessionAnalyzer.ts
      → renders report sections
```

## New Files

### Types
- `src/renderer/types/sessionReport.ts` — `SessionReport` interface with all section types

### Analysis Engine
- `src/renderer/utils/sessionAnalyzer.ts` — `analyzeSession(detail: SessionDetail): SessionReport`
  - Single-pass over `detail.messages` (mirrors the Python script's accumulator pattern)
  - Post-pass aggregation for derived metrics
  - Uses `detail.session` for metadata, `detail.processes` for subagent data

### Report UI
- `src/renderer/components/report/SessionReportTab.tsx` — Main report tab
- `src/renderer/components/report/sections/` — Section components:
  - `OverviewSection` — Session ID, project, duration, message count, context assessment
  - `CostSection` — Cost by model, total, per-commit, per-line
  - `TokenSection` — Token usage by model, cache economics, density timeline
  - `ToolSection` — Tool counts, success rates
  - `SubagentSection` — Subagent metrics, cost, token usage
  - `ErrorSection` — Tool errors, permission denials
  - `GitSection` — Commits, pushes, branches, lines changed
  - `FrictionSection` — User corrections, thrashing signals
  - `TimelineSection` — Idle gaps, model switches, key events
  - `ConversationTreeSection` — Tree depth, branching, sidechains
  - `QualitySection` — Prompt quality, startup overhead, test progression

### Integration Points (modified files)
- `src/renderer/types/tabs.ts` — Add `'report'` tab type
- `src/renderer/store/slices/tabSlice.ts` — Add `openSessionReport` action
- `src/renderer/components/layout/TabBar.tsx` — Add Activity icon button
- `src/renderer/App.tsx` (or routing equivalent) — Route `report` tabs to `SessionReportTab`

## Report Visual Design

- Each section is a card with `bg-surface-raised` background and `border-border` border
- Section headers with lucide-react icons and bold titles
- Data in tables and stat grids using theme-aware CSS variables
- Color-coded assessments: green (healthy), amber (warning), red (critical)
- Collapsible detail sections for verbose data (thinking blocks, error details, idle gaps)
- Scrollable report body with sticky section navigation

## Data Flow

The `SessionDetail` already contains:
- `messages: ParsedMessage[]` — raw messages with toolCalls, toolResults, usage, model, timestamp, uuid/parentUuid, isMeta, cwd, gitBranch, agentId, isSidechain
- `session: Session` — metadata (contextConsumption, compactionCount, phaseBreakdown, etc.)
- `processes: Process[]` — subagent executions with nested messages and metrics
- `metrics: SessionMetrics` — pre-computed aggregates

The analyzer works directly with these types — no JSON serialization or IPC needed.

## Analysis Sections (ported from Python)

| Section | Key Metrics |
|---------|------------|
| Overview | Duration, message count, context consumption, compaction count |
| Cost Analysis | Parent + subagent cost, cost by model, per-commit, per-line |
| Token Usage | By model (input/output/cache), totals, cache read % |
| Cache Economics | Creation 5m/1h, read/write ratio, cold start, efficiency % |
| Tool Usage | Counts, success rates per tool |
| Subagent Metrics | Count, tokens, duration, cost per agent |
| Errors | Tool errors, permission denials, affected tools |
| Git Activity | Commits, pushes, branch creations, lines changed |
| Friction Signals | Correction count, friction rate, keyword matches |
| Thrashing | Bash near-duplicates, file edit rework |
| Conversation Tree | Max depth, sidechain count, branch points |
| Idle Analysis | Gap count, total idle time, active working time |
| Model Switches | Switch count, models used |
| Working Directories | Unique dirs, change count |
| Test Progression | Snapshots, trajectory (improving/regressing/stable) |
| Startup Overhead | Messages/tokens before first work tool |
| Token Density Timeline | Quartile averages |
| Prompt Quality | First message length, friction rate, assessment |
| Thinking Blocks | Count, signal analysis (alternatives, uncertainty, planning) |
| Key Events | Timestamped skill invocations, task launches |
| Service Tiers | API tier usage distribution |
| File Read Redundancy | Reads per unique file, redundant files |
| Compact Summaries | Count of context compaction events |
| Out-of-scope Findings | Keywords detected in assistant responses |