# Implementation Plan: Session Insights (session_insights_20260306)

> **Reference:** [Spec](./spec.md) | [Architecture Guide](../../../docs/guide_architecture.md)

## Phase 1: Token Timeline Data
Focus: Collect token usage over session

- [ ] Task 1.1: Initialize MMA Environment
- [ ] Task 1.2: Add token history state
    - WHERE: `src/gui_2.py` or `src/app_controller.py`
    - WHAT: Track tokens per API call
    - HOW:
      ```python
      self._token_history: list[dict] = []  # [{"time": t, "input": n, "output": n, "model": s}, ...]
      ```

- [ ] Task 1.3: Record on each API response
    - WHERE: `src/gui_2.py` in response handler
    - WHAT: Append to history
    - HOW:
      ```python
      # After API call
      self._token_history.append({
       "time": time.time(), "input": input_tokens, "output": output_tokens, "model": model
      })
      ```

## Phase 2: Token Timeline Visualization
Focus: Render token usage graph

- [ ] Task 2.1: Extract cumulative tokens
    - WHERE: `src/gui_2.py`
    - WHAT: Calculate running totals
    - HOW:
      ```python
      cumulative_input = 0
      cumulative_output = 0
      input_values = []
      output_values = []
      for entry in self._token_history:
       cumulative_input += entry["input"]
       cumulative_output += entry["output"]
       input_values.append(cumulative_input)
       output_values.append(cumulative_output)
      ```

- [ ] Task 2.2: Render timeline
    - WHERE: `src/gui_2.py` session insights panel
    - HOW:
      ```python
      if imgui.collapsing_header("Token Timeline"):
       imgui.plot_lines("Input", input_values)
       imgui.plot_lines("Output", output_values)
       imgui.text(f"Total: {cumulative_input + cumulative_output:,} tokens")
      ```

## Phase 3: Cost Projection
Focus: Estimate remaining cost

- [ ] Task 3.1: Calculate burn rate
    - WHERE: `src/gui_2.py`
    - WHAT: Tokens per minute
    - HOW:
      ```python
      if len(self._token_history) >= 2:
       elapsed = self._token_history[-1]["time"] - self._token_history[0]["time"]
       total_tokens = sum(e["input"] + e["output"] for e in self._token_history)
       burn_rate = total_tokens / (elapsed / 60) if elapsed > 0 else 0
      ```

- [ ] Task 3.2: Display projection
    - WHERE: `src/gui_2.py`
    - HOW:
      ```python
      imgui.text(f"Burn rate: {burn_rate:.0f} tokens/min")
      imgui.text(f"Session cost: ${session_cost:.4f}")
      ```

## Phase 4: Efficiency Score
Focus: Calculate tokens per useful change

- [ ] Task 4.1: Define efficiency metric
    - WHERE: `src/gui_2.py`
    - WHAT: Ratio of tokens to completed tickets
    - HOW:
      ```python
      completed_tickets = sum(1 for t in self.track.tickets if t.status == "completed")
      total_tokens = sum(e["input"] + e["output"] for e in self._token_history)
      efficiency = total_tokens / completed_tickets if completed_tickets > 0 else 0
      ```

## Phase 5: Testing
- [ ] Task 5.1: Write unit tests
- [ ] Task 5.2: Conductor - Phase Verification