feat: real-time context window tracking & session status bar

README.md

@@ -17,6 +17,7 @@
 <p align="center">
   <a href="#install">Install</a> |
   <a href="#features">Features</a> |
+  <a href="#context-window-tracking-optional">Context Tracking</a> |
   <a href="#configuration">Configuration</a> |
   <a href="#docker">Docker</a> |
   <a href="#troubleshooting">Troubleshooting</a>
@@ -33,7 +34,7 @@
 ## Install
 
 ```bash
-curl -fsSL https://quickcall.dev/supertrace/install.sh | sh
+curl -fsSL https://quickcall.dev/supertrace/install.sh | bash
 ```
 
 Then run:
@@ -55,6 +56,46 @@ Open http://localhost:7845 in your browser.
 - **Full-text search** - Find anything across all sessions
 - **Export** - Download sessions as JSON or Markdown
 - **WebSocket updates** - Live updates without page refresh
+- **Context window tracking** - Real-time context usage with color-coded progress bar
+
+## Context Window Tracking
+
+Real-time context window tracking is **automatically enabled** when you run SuperTrace.
+
+### How It Works
+
+1. When `quickcall-supertrace` starts, it automatically configures Claude Code hooks
+2. After each Claude response, the hook captures token usage
+3. Context data is sent to the SuperTrace server
+4. The UI displays a real-time progress bar:
+   - **Green** - Under 50% usage
+   - **Yellow** - 50-75% usage
+   - **Red** - Over 75% usage
+
+### Setup
+
+Just run SuperTrace - hooks are configured automatically:
+
+```bash
+quickcall-supertrace
+```
+
+Then **restart Claude Code** to load the hooks.
+
+### Disable Auto-Registration
+
+If you don't want automatic hook registration:
+
+```bash
+QUICKCALL_SUPERTRACE_AUTO_HOOKS=false quickcall-supertrace
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `QUICKCALL_SUPERTRACE_AUTO_HOOKS` | true | Auto-register Claude Code hooks |
+| `QUICKCALL_SUPERTRACE_DEBUG` | false | Enable debug logging for hooks |
 
 ## Dashboard Metrics
 

docs/concepts/architecture.md

@@ -6,6 +6,11 @@ How QuickCall SuperTrace captures and displays Claude Code sessions.
 
 ```mermaid
 flowchart TB
+    subgraph "Real-time (Hooks)"
+        H1[Claude Code] -->|Stop event| H2[Hook CLI]
+        H2 -->|POST /context| API
+    end
+
     subgraph Ingestion
         A[~/.claude/projects/] --> B[Scanner]
         B --> C[Parser]
@@ -14,6 +19,7 @@ flowchart TB
 
     subgraph Storage
         D --> E[(SQLite WAL)]
+        API --> E
     end
 
     subgraph API
@@ -41,7 +47,51 @@ Each line is a JSON object representing a message:
 {"type":"assistant","message":{"content":[...],"usage":{...}},"timestamp":"2026-01-14T10:00:10Z"}
 ```
 
-### 2. Ingestion Pipeline
+### 2. Hooks System (Real-time Context Tracking)
+
+Claude Code supports hooks that fire on specific events. SuperTrace uses the **Stop hook** to track context window usage in real-time.
+
+**How it works:**
+1. On server startup, SuperTrace registers hooks in `~/.claude/settings.json`
+2. When Claude finishes responding, the Stop hook fires
+3. Hook CLI reads the transcript and extracts token usage
+4. Context data is POSTed to SuperTrace server
+5. Server broadcasts via WebSocket to update UI instantly
+
+**Components:**
+
+| File | Purpose |
+|------|---------|
+| `hooks/setup.py` | Auto-registers hooks on server startup |
+| `hooks/cli.py` | CLI entry point (`quickcall-supertrace-hook`) |
+| `hooks/handlers.py` | Processes hook events, extracts context data |
+| `hooks/models.py` | Pydantic models for hook input/output |
+
+**Context Calculation:**
+```
+Total Context = input_tokens + cache_read_tokens + cache_create_tokens
+Context % = (Total Context / Model Context Window) × 100
+```
+
+Note: Output tokens are NOT included in context window calculation.
+
+**Hook Registration** (in `~/.claude/settings.json`):
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "/path/to/quickcall-supertrace-hook stop",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+### 3. Ingestion Pipeline (Batch Import)
 
 **Scanner** (`packages/server/quickcall_supertrace/ingest/scanner.py`)
 - Finds all JSONL files in `~/.claude/projects/`
@@ -64,7 +114,7 @@ Each line is a JSON object representing a message:
 - Triggers incremental imports
 - Broadcasts updates via WebSocket
 
-### 3. Database (SQLite)
+### 4. Database (SQLite)
 
 Location: `~/.quickcall-supertrace/data.db`
 
@@ -75,6 +125,7 @@ Location: `~/.quickcall-supertrace/data.db`
 | `sessions` | Session metadata (id, project_path, timestamps) |
 | `messages` | Parsed JSONL messages with extracted fields |
 | `transcript_files` | Tracks ingested files (mtime, byte offset) |
+| `session_context` | Context window snapshots (from hooks) |
 | `session_metrics` | Pre-computed aggregates |
 | `messages_fts` | Full-text search index |
 
@@ -83,21 +134,23 @@ Location: `~/.quickcall-supertrace/data.db`
 - Denormalized fields in `messages` for query performance
 - FTS5 for full-text search across content
 
-### 4. REST API (FastAPI)
+### 5. REST API (FastAPI)
 
 **Routes:**
 
 | Endpoint | Purpose |
 |----------|---------|
 | `GET /api/sessions` | List sessions (paginated) |
 | `GET /api/sessions/{id}` | Get session with events |
+| `GET /api/sessions/{id}/context` | Get context window snapshots |
+| `POST /api/sessions/{id}/context` | Store context update (from hooks) |
 | `GET /api/sessions/{id}/export` | Export as JSON/Markdown |
 | `GET /api/metrics/session/{id}` | Compute session metrics |
 | `POST /api/ingest` | Trigger manual import |
 | `GET /api/ingest/status` | Show tracked files |
 | `WS /ws` | Real-time updates |
 
-### 5. Metrics System
+### 6. Metrics System
 
 **Architecture:** Decorator-based plugin system
 
@@ -116,7 +169,7 @@ def estimated_cost(events: PreprocessedEvents) -> float:
 
 **Preprocessing:** Single-pass extraction of commonly-needed data for efficiency.
 
-### 6. React Frontend
+### 7. React Frontend
 
 **Tech Stack:** React 19, TypeScript, Tailwind CSS, Vite
 
@@ -139,7 +192,29 @@ def estimated_cost(events: PreprocessedEvents) -> float:
 
 ## Data Flow
 
-### Import Flow
+### Context Tracking Flow (Real-time)
+
+```mermaid
+sequenceDiagram
+    participant CC as Claude Code
+    participant Hook as Hook CLI
+    participant API as SuperTrace API
+    participant WS as WebSocket
+    participant UI as Frontend
+
+    CC->>CC: User sends prompt
+    CC->>CC: Claude responds
+    CC->>Hook: Stop event (stdin JSON)
+    Hook->>Hook: Read transcript JSONL
+    Hook->>Hook: Extract token usage
+    Hook->>Hook: Calculate context %
+    Hook->>API: POST /sessions/{id}/context
+    API->>API: Store snapshot
+    API->>WS: Broadcast context_updated
+    WS->>UI: Update status bar
+```
+
+### Import Flow (Batch)
 
 ```mermaid
 sequenceDiagram

install/hooks/context-tracker.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+#
+# SuperTrace Context Tracker Hook for Claude Code
+#
+# This hook captures context window usage data from Claude Code sessions
+# and sends it to the SuperTrace backend for real-time tracking.
+#
+# Hook Event: PostToolUse (fires after each tool call)
+#
+# Installation:
+#   1. Copy hooks directory to ~/.claude/plugins/supertrace/
+#   2. Claude Code will automatically load hooks from the plugin
+#
+# Environment:
+#   SUPERTRACE_URL      - SuperTrace backend URL (default: http://localhost:7845)
+#   SUPERTRACE_DEBUG    - Enable debug logging (set to "true")
+#   SUPERTRACE_TIMEOUT  - Request timeout in seconds (default: 2)
+#
+
+set -euo pipefail
+
+# Configuration with defaults
+SUPERTRACE_URL="${SUPERTRACE_URL:-http://localhost:7845}"
+SUPERTRACE_DEBUG="${SUPERTRACE_DEBUG:-false}"
+SUPERTRACE_TIMEOUT="${SUPERTRACE_TIMEOUT:-2}"
+
+# Debug logging function
+debug() {
+    if [ "$SUPERTRACE_DEBUG" = "true" ]; then
+        echo "[SuperTrace Debug] $*" >&2
+    fi
+}
+
+# Log errors but don't fail - hooks must be non-blocking
+log_error() {
+    echo "[SuperTrace Error] $*" >&2
+}
+
+# Read stdin (Claude Code passes JSON input)
+input=$(cat 2>/dev/null || echo "{}")
+
+debug "Received hook input"
+
+# Extract session_id from hook input
+session_id=$(echo "$input" | jq -r '.session_id // empty' 2>/dev/null || true)
+
+if [ -z "$session_id" ]; then
+    debug "No session_id found in hook input, skipping"
+    exit 0
+fi
+
+debug "Session ID: $session_id"
+
+# Get transcript path from hook input
+transcript_path=$(echo "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)
+
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+    debug "No valid transcript_path found, skipping"
+    exit 0
+fi
+
+debug "Transcript path: $transcript_path"
+
+# Parse the latest API response from transcript to get token usage
+# The transcript is JSONL format with API responses containing usage data
+# Look for the most recent entry with usage data
+
+# Get the last line with usage data from transcript
+latest_usage=$(tail -100 "$transcript_path" 2>/dev/null | \
+    grep -o '"usage":{[^}]*}' 2>/dev/null | \
+    tail -1 || true)
+
+if [ -z "$latest_usage" ]; then
+    debug "No usage data found in recent transcript entries"
+    exit 0
+fi
+
+debug "Found usage data: $latest_usage"
+
+# Extract token counts from usage data
+# Format: "usage":{"input_tokens":1234,"output_tokens":567,"cache_creation_input_tokens":0,"cache_read_input_tokens":890}
+input_tokens=$(echo "{$latest_usage}" | jq -r '.usage.input_tokens // 0' 2>/dev/null || echo "0")
+output_tokens=$(echo "{$latest_usage}" | jq -r '.usage.output_tokens // 0' 2>/dev/null || echo "0")
+cache_read_tokens=$(echo "{$latest_usage}" | jq -r '.usage.cache_read_input_tokens // 0' 2>/dev/null || echo "0")
+cache_creation_tokens=$(echo "{$latest_usage}" | jq -r '.usage.cache_creation_input_tokens // 0' 2>/dev/null || echo "0")
+
+# Calculate totals
+total_input_tokens=$((input_tokens + cache_read_tokens + cache_creation_tokens))
+total_output_tokens=$output_tokens
+total_tokens=$((total_input_tokens + total_output_tokens))
+
+debug "Input tokens: $total_input_tokens, Output tokens: $total_output_tokens"
+
+# Estimate context window size (default to 200k for Claude)
+# This could be enhanced to detect model type from transcript
+context_window_size=200000
+
+# Calculate percentages
+used_percentage=$(echo "scale=2; ($total_tokens * 100) / $context_window_size" | bc 2>/dev/null || echo "0")
+remaining_percentage=$(echo "scale=2; 100 - $used_percentage" | bc 2>/dev/null || echo "100")
+
+debug "Used: ${used_percentage}%, Remaining: ${remaining_percentage}%"
+
+# Build the payload for SuperTrace API
+payload=$(jq -n \
+    --argjson used_percentage "$used_percentage" \
+    --argjson remaining_percentage "$remaining_percentage" \
+    --argjson context_window_size "$context_window_size" \
+    --argjson total_input_tokens "$total_input_tokens" \
+    --argjson total_output_tokens "$total_output_tokens" \
+    --argjson cache_read_tokens "$cache_read_tokens" \
+    --argjson cache_creation_tokens "$cache_creation_tokens" \
+    '{
+        used_percentage: $used_percentage,
+        remaining_percentage: $remaining_percentage,
+        context_window_size: $context_window_size,
+        total_input_tokens: $total_input_tokens,
+        total_output_tokens: $total_output_tokens,
+        cache_read_tokens: $cache_read_tokens,
+        cache_creation_tokens: $cache_creation_tokens
+    }' 2>/dev/null || true)
+
+if [ -z "$payload" ]; then
+    log_error "Failed to build payload"
+    exit 0
+fi
+
+debug "Payload: $payload"
+
+# POST to SuperTrace API with timeout
+# Use || true to ensure hook never blocks Claude Code
+api_url="${SUPERTRACE_URL}/api/sessions/${session_id}/context"
+
+debug "POSTing to: $api_url"
+
+response=$(curl -s -X POST "$api_url" \
+    -H "Content-Type: application/json" \
+    -d "$payload" \
+    --connect-timeout "$SUPERTRACE_TIMEOUT" \
+    --max-time "$SUPERTRACE_TIMEOUT" \
+    2>/dev/null || true)
+
+if [ -n "$response" ]; then
+    debug "Response: $response"
+fi
+
+# Always exit successfully - hooks must be non-blocking
+exit 0

install/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "SuperTrace context tracking hook - sends context window usage to SuperTrace backend",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/context-tracker.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}