claude-code-tracker 1.4.0-beta.3 → 1.4.0-beta.4

package/README.md

@@ -15,6 +15,11 @@ After every session, it parses the transcript, updates a `tokens.json` ledger, r
 - **Prompt efficiency**: ratio of key prompts to total human messages
 - **Per-agent cost breakdown**: SubagentStop hook captures each spawned agent's token usage
   separately — see which agent types (architect, quick-fixer, Explore, etc.) drive the most cost
+- **Context compaction tracking**: counts and metadata for every context compaction event —
+  auto/manual trigger, pre-compaction token count, session distribution
+- **Skill invocation tracking**: per-skill success/error rates, duration, and timeline
+- **Friction event tracking**: tool errors, permission denials, corrections, retries — with
+  category breakdown, rate trends, and error classification
 
 All data lives in `<project>/.claude/tracking/` alongside your code.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-tracker",
-  "version": "1.4.0-beta.3",
+  "version": "1.4.0-beta.4",
   "description": "Automatic token, cost, and prompt tracking for Claude Code sessions",
   "keywords": [
     "claude",

package/src/backfill.py

@@ -189,15 +189,14 @@ total_turns = len(new_entries)
 print(f"{sessions_processed} session{'s' if sessions_processed != 1 else ''} processed, {total_turns} turn{'s' if total_turns != 1 else ''} written.")
 
 # Backfill friction events from the same transcripts
-from parse_friction import parse_friction, upsert_friction
+from parse_friction import parse_friction
 
-friction_file = os.path.join(tracking_dir, "friction.json")
 friction_count = 0
 for jf in jsonl_files:
     session_id = os.path.splitext(os.path.basename(jf))[0]
     try:
         events = parse_friction(jf, session_id, project_name, "main")
-        upsert_friction(friction_file, session_id, events)
+        storage.replace_session_friction(tracking_dir, session_id, events)
         friction_count += len(events)
     except Exception:
         pass
@@ -205,8 +204,24 @@ for jf in jsonl_files:
 if friction_count:
     print(f"{friction_count} friction event{'s' if friction_count != 1 else ''} backfilled.")
 
+# Backfill compaction events from the same transcripts
+from parse_compactions import parse_compactions as parse_compact_events
+
+compaction_count = 0
+for jf in jsonl_files:
+    session_id = os.path.splitext(os.path.basename(jf))[0]
+    try:
+        events = parse_compact_events(jf, session_id, project_name)
+        storage.replace_session_compactions(tracking_dir, session_id, events)
+        compaction_count += len(events)
+    except Exception:
+        pass
+
+if compaction_count:
+    print(f"{compaction_count} compaction event{'s' if compaction_count != 1 else ''} backfilled.")
+
 # Regenerate charts if we added anything
-if new_entries or friction_count:
+if new_entries or friction_count or compaction_count:
     script_dir = os.path.dirname(os.path.abspath(__file__))
     charts_html = os.path.join(tracking_dir, "charts.html")
     os.system(f'python3 "{script_dir}/generate-charts.py" "{tracking_dir}" "{charts_html}" 2>/dev/null')

package/src/cost-summary.py

@@ -138,28 +138,37 @@ if days > 1:
     print(f"\n  Avg cost/day:      ${total_cost/days:>11.2f}  over {days} days")
 
 # --- Friction summary ---
-friction_file = os.path.join(tracking_dir, "friction.json")
-if os.path.exists(friction_file):
-    try:
-        with open(friction_file, encoding='utf-8') as f:
-            friction_data = json.load(f)
-        if friction_data:
-            print(f"\nFriction:")
-            friction_total = len(friction_data)
-            cat_counts = defaultdict(int)
-            tool_counts = defaultdict(int)
-            for fe in friction_data:
-                cat_counts[fe.get('category', 'unknown')] += 1
-                tn = fe.get('tool_name')
-                if tn:
-                    tool_counts[tn] += 1
-            top_cat = max(cat_counts, key=cat_counts.get)
-            print(f"  Total events:      {friction_total:>8}")
-            print(f"  Top category:      {top_cat:>8}  ({cat_counts[top_cat]} events)")
-            if tool_counts:
-                top_tool = max(tool_counts, key=tool_counts.get)
-                print(f"  Top tool:          {top_tool:>8}  ({tool_counts[top_tool]} events)")
-    except Exception:
-        pass
+friction_data = storage.get_all_friction(tracking_dir)
+if friction_data:
+    print(f"\nFriction:")
+    friction_total = len(friction_data)
+    cat_counts = defaultdict(int)
+    tool_counts = defaultdict(int)
+    for fe in friction_data:
+        cat_counts[fe.get('category', 'unknown')] += 1
+        tn = fe.get('tool_name')
+        if tn:
+            tool_counts[tn] += 1
+    top_cat = max(cat_counts, key=cat_counts.get)
+    print(f"  Total events:      {friction_total:>8}")
+    print(f"  Top category:      {top_cat:>8}  ({cat_counts[top_cat]} events)")
+    if tool_counts:
+        top_tool = max(tool_counts, key=tool_counts.get)
+        print(f"  Top tool:          {top_tool:>8}  ({tool_counts[top_tool]} events)")
+
+# --- Compaction summary ---
+compaction_data = storage.get_all_compactions(tracking_dir)
+if compaction_data:
+    total_compactions = len(compaction_data)
+    auto_count = sum(1 for c in compaction_data if c.get('trigger', 'auto') == 'auto')
+    manual_count = total_compactions - auto_count
+    avg_pre = round(sum(c.get('pre_tokens', 0) for c in compaction_data) / total_compactions) if total_compactions > 0 else 0
+    sessions_compacted = len({c.get('session_id') for c in compaction_data})
+    pct_compacted = round(sessions_compacted / total_sessions * 100, 1) if total_sessions > 0 else 0
+    print(f"\nCompaction:")
+    print(f"  Total events:      {total_compactions:>8}")
+    print(f"  Auto / manual:     {auto_count:>5} / {manual_count}")
+    print(f"  Avg pre-tokens:    {avg_pre:>12,}")
+    print(f"  Sessions affected: {pct_compacted:>9.1f}%  ({sessions_compacted} of {total_sessions})")
 
 print("=" * W)

package/src/generate-charts.py

@@ -25,15 +25,8 @@ data = storage.get_all_turns(tracking_dir)
 agent_data = storage.get_all_agents(tracking_dir)
 skill_data = storage.get_all_skills(tracking_dir)
 
-# Load friction data (optional — file may not exist on older installs)
-friction_file = os.path.join(tracking_dir, 'friction.json')
-friction_data = []
-if os.path.exists(friction_file):
-    try:
-        with open(friction_file, encoding='utf-8') as f:
-            friction_data = json.load(f)
-    except:
-        pass
+friction_data = storage.get_all_friction(tracking_dir)
+compaction_data = storage.get_all_compactions(tracking_dir)
 
 def format_duration(seconds):
     if seconds <= 0:
@@ -523,7 +516,7 @@ has_skill_data = bool(friction_by_skill)
 
 retry_events = [fe for fe in friction_data if fe.get('category') == 'retry']
 retry_total = len(retry_events)
-retry_resolved = sum(1 for fe in retry_events if fe.get('resolved') is True)
+retry_resolved = sum(1 for fe in retry_events if fe.get('resolved'))
 retry_rate = round(retry_resolved / retry_total * 100, 1) if retry_total > 0 else 0
 
 total_friction = len(friction_data)
@@ -793,6 +786,133 @@ else:
     error_js_constants = ''
     error_js_charts = ''
 
+# --- Compaction data aggregation ---
+compaction_by_date = defaultdict(lambda: {"auto": 0, "manual": 0})
+compaction_tokens = []
+compaction_per_session = defaultdict(int)
+for ce in compaction_data:
+    d = ce.get('date', 'unknown')
+    trig = ce.get('trigger', 'auto')
+    if trig == 'manual':
+        compaction_by_date[d]["manual"] += 1
+    else:
+        compaction_by_date[d]["auto"] += 1
+    pre_t = ce.get('pre_tokens', 0)
+    if pre_t > 0:
+        compaction_tokens.append({"x": ce.get('timestamp', '')[:10] if ce.get('timestamp') else 'unknown', "y": pre_t})
+    compaction_per_session[ce.get('session_id', '')] += 1
+
+total_compactions = len(compaction_data)
+total_auto = sum(1 for c in compaction_data if c.get('trigger', 'auto') == 'auto')
+total_manual = total_compactions - total_auto
+avg_pre_tokens = round(sum(c.get('pre_tokens', 0) for c in compaction_data) / total_compactions) if total_compactions > 0 else 0
+sessions_with_compaction = len([s for s in compaction_per_session if compaction_per_session[s] > 0])
+pct_sessions_compacted = round(sessions_with_compaction / total_sessions * 100, 1) if total_sessions > 0 else 0
+avg_per_session = round(total_compactions / total_sessions, 1) if total_sessions > 0 else 0
+
+compact_dates_sorted = sorted(compaction_by_date.keys())
+compact_dates_js = json.dumps(compact_dates_sorted)
+compact_auto_js = json.dumps([compaction_by_date[d]["auto"] for d in compact_dates_sorted])
+compact_manual_js = json.dumps([compaction_by_date[d]["manual"] for d in compact_dates_sorted])
+compact_scatter_js = json.dumps(compaction_tokens)
+
+compact_dist = {"0": 0, "1": 0, "2": 0, "3+": 0}
+all_session_ids = {e.get("session_id") for e in data}
+for sid in all_session_ids:
+    cnt = compaction_per_session.get(sid, 0)
+    if cnt == 0:
+        compact_dist["0"] += 1
+    elif cnt == 1:
+        compact_dist["1"] += 1
+    elif cnt == 2:
+        compact_dist["2"] += 1
+    else:
+        compact_dist["3+"] += 1
+compact_dist_labels_js = json.dumps(list(compact_dist.keys()))
+compact_dist_values_js = json.dumps(list(compact_dist.values()))
+
+if compaction_data:
+    compaction_stat_html = f'''  <div class="stat">
+    <div class="stat-label">Compactions</div>
+    <div class="stat-value">{total_compactions}</div>
+    <div class="stat-sub">{avg_per_session}/session, {pct_sessions_compacted}% of sessions</div>
+  </div>'''
+    compaction_section_html = f'''<div class="section">
+  <div class="section-header compaction">Context Compactions</div>
+  <div class="grid">
+    <div class="card">
+      <h2>Compactions per day</h2>
+      <canvas id="compactDay"></canvas>
+    </div>
+    <div class="card">
+      <h2>Pre-compaction token count</h2>
+      <canvas id="compactTokens"></canvas>
+    </div>
+    <div class="card">
+      <h2>Compactions per session</h2>
+      <canvas id="compactDist"></canvas>
+    </div>
+  </div>
+</div>
+
+'''
+    compaction_js_constants = f'''const COMPACT_DATES = {compact_dates_js};
+const COMPACT_AUTO = {compact_auto_js};
+const COMPACT_MANUAL = {compact_manual_js};
+const COMPACT_SCATTER = {compact_scatter_js};
+const COMPACT_DIST_LABELS = {compact_dist_labels_js};
+const COMPACT_DIST_VALUES = {compact_dist_values_js};'''
+    compaction_js_charts = '''
+// Compactions per day (stacked bar)
+new Chart(document.getElementById('compactDay'), {
+  type: 'bar',
+  data: {
+    labels: COMPACT_DATES,
+    datasets: [
+      { label: 'Auto', data: COMPACT_AUTO, backgroundColor: '#8b5cf6', borderRadius: 2 },
+      { label: 'Manual', data: COMPACT_MANUAL, backgroundColor: '#c084fc', borderRadius: 2 }
+    ]
+  },
+  options: { ...baseOpts, scales: { ...baseOpts.scales,
+    x: { ...baseOpts.scales.x, stacked: true },
+    y: { ...baseOpts.scales.y, stacked: true } } }
+});
+
+// Pre-compaction token count (scatter)
+new Chart(document.getElementById('compactTokens'), {
+  type: 'scatter',
+  data: {
+    datasets: [{ label: 'Pre-tokens', data: COMPACT_SCATTER,
+      backgroundColor: '#a78bfa', pointRadius: 5 }]
+  },
+  options: { ...baseOpts,
+    scales: {
+      x: { type: 'category', labels: [...new Set(COMPACT_SCATTER.map(p => p.x))],
+           ticks: { color: TEXT, font: { size: 10 } }, grid: { color: GRID } },
+      y: { ticks: { color: TEXT, font: { size: 10 },
+           callback: v => (v/1000).toFixed(0) + 'K' }, grid: { color: GRID } }
+    },
+    plugins: { ...baseOpts.plugins,
+      tooltip: { callbacks: { label: ctx => ' ' + ctx.parsed.y.toLocaleString() + ' tokens' } } }
+  }
+});
+
+// Compactions per session distribution
+new Chart(document.getElementById('compactDist'), {
+  type: 'bar',
+  data: {
+    labels: COMPACT_DIST_LABELS,
+    datasets: [{ label: 'Sessions', data: COMPACT_DIST_VALUES,
+      backgroundColor: '#8b5cf6', borderRadius: 4 }]
+  },
+  options: baseOpts
+});'''
+else:
+    compaction_stat_html = ''
+    compaction_section_html = ''
+    compaction_js_constants = ''
+    compaction_js_charts = ''
+
 html = f"""<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -826,6 +946,7 @@ html = f"""<!DOCTYPE html>
   .section-header.friction {{ border-left: 3px solid #ef4444; color: #f87171; }}
   .section-header.errors {{ border-left: 3px solid #e11d48; color: #fb7185; }}
   .section-header.skills {{ border-left: 3px solid #f59e0b; color: #fbbf24; }}
+  .section-header.compaction {{ border-left: 3px solid #8b5cf6; color: #a78bfa; }}
   .grid {{ display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }}
   .card {{ background: #1e2330; border: 1px solid #2d3748; border-radius: 10px;
            padding: 16px; }}
@@ -892,6 +1013,7 @@ html = f"""<!DOCTYPE html>
 {friction_stat_html}
 {retry_stat_html}
 {error_stat_html}
+{compaction_stat_html}
 </div>
 
 <div class="section">
@@ -926,7 +1048,7 @@ html = f"""<!DOCTYPE html>
   </div>
 </div>
 
-{agents_section_html}{skills_section_html}{friction_section_html}{error_section_html}<div class="section">
+{agents_section_html}{skills_section_html}{friction_section_html}{error_section_html}{compaction_section_html}<div class="section">
   <div class="section-header prompts">Key Prompts</div>
   <div class="grid">
 
@@ -1035,6 +1157,7 @@ const DUR_HIST_RANGES = {dur_hist_ranges_js};
 {skills_js_constants}
 {friction_js_constants}
 {error_js_constants}
+{compaction_js_constants}
 
 function formatDuration(s) {{
   if (s <= 0) return '0s';
@@ -1312,6 +1435,7 @@ new Chart(document.getElementById('promptStack'), {{
 {skills_js_charts}
 {friction_js_charts}
 {error_js_charts}
+{compaction_js_charts}
 </script>
 </body>
 </html>

package/src/parse_compactions.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Parse context compaction events from Claude Code JSONL transcripts.
+
+Usage:
+  python3 parse_compactions.py <transcript_path> <tracking_dir> <session_id> <project>
+"""
+import json
+import os
+import sys
+from datetime import date, datetime
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+import storage
+
+
+def make_date(timestamp):
+    try:
+        return datetime.fromisoformat(
+            timestamp.replace('Z', '+00:00')).strftime('%Y-%m-%d')
+    except Exception:
+        return date.today().isoformat()
+
+
+def parse_compactions(transcript_path, session_id, project):
+    """Parse JSONL transcript for compact_boundary system events.
+
+    Derives turn_index by counting user/assistant pairs before each event.
+    Returns list of dicts ready for storage.replace_session_compactions().
+    """
+    lines = []
+    with open(transcript_path, encoding='utf-8') as f:
+        for raw in f:
+            try:
+                obj = json.loads(raw)
+                lines.append(obj)
+            except Exception:
+                pass
+
+    # Build turn boundaries for turn_index calculation
+    msg_list = []
+    for obj in lines:
+        ts = obj.get('timestamp', '')
+        t = obj.get('type')
+        if t == 'user' and not obj.get('isSidechain') and ts:
+            msg_list.append(('user', ts))
+        elif t == 'assistant' and ts:
+            msg_list.append(('assistant', ts))
+
+    # Pair user->assistant for turn boundaries
+    turn_boundaries = []
+    idx = 0
+    while idx < len(msg_list):
+        if msg_list[idx][0] == 'user':
+            j = idx + 1
+            while j < len(msg_list) and msg_list[j][0] != 'assistant':
+                j += 1
+            if j < len(msg_list):
+                turn_boundaries.append((msg_list[idx][1], msg_list[j][1]))
+                idx = j + 1
+            else:
+                idx += 1
+        else:
+            idx += 1
+
+    def get_turn_index(timestamp):
+        if not timestamp:
+            return 0
+        for ti, (user_ts, asst_ts) in enumerate(turn_boundaries):
+            if timestamp <= asst_ts:
+                return ti
+            if ti + 1 < len(turn_boundaries):
+                next_user_ts = turn_boundaries[ti + 1][0]
+                if asst_ts < timestamp < next_user_ts:
+                    return ti
+        return max(0, len(turn_boundaries) - 1)
+
+    entries = []
+    for obj in lines:
+        if obj.get('type') != 'system':
+            continue
+        if obj.get('subtype') != 'compact_boundary':
+            continue
+
+        ts = obj.get('timestamp', '')
+        meta = obj.get('compactMetadata', {})
+        if not isinstance(meta, dict):
+            meta = {}
+
+        entries.append({
+            'session_id': session_id,
+            'date': make_date(ts),
+            'project': project,
+            'timestamp': ts,
+            'trigger': meta.get('trigger', 'auto'),
+            'pre_tokens': meta.get('preTokens', 0),
+            'turn_index': get_turn_index(ts),
+        })
+
+    return entries
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 5:
+        print(f"Usage: {sys.argv[0]} <transcript_path> <tracking_dir> <session_id> <project>",
+              file=sys.stderr)
+        sys.exit(1)
+
+    transcript_path, tracking_dir, session_id, project = sys.argv[1:5]
+    entries = parse_compactions(transcript_path, session_id, project)
+    storage.replace_session_compactions(tracking_dir, session_id, entries)

package/src/parse_friction.py

@@ -3,7 +3,7 @@
 Parse friction events from Claude Code JSONL transcripts.
 
 Usage:
-  python3 parse_friction.py <transcript_path> <friction_file> <session_id> <project> <source> \
+  python3 parse_friction.py <transcript_path> <tracking_dir> <session_id> <project> <source> \
     [--agent-type TYPE] [--agent-id ID]
 
 Friction categories (priority order, first match wins):
@@ -11,6 +11,10 @@ Friction categories (priority order, first match wins):
 """
 import sys, json, os, argparse
 
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+import storage
+
 
 def parse_friction(transcript_path, session_id, project, source,
                    agent_type=None, agent_id=None):
@@ -237,34 +241,23 @@ def parse_friction(transcript_path, session_id, project, source,
     return events
 
 
-def upsert_friction(friction_file, session_id, new_events):
-    """Load existing friction.json, remove events for session_id, add new, sort, write."""
-    data = []
-    if os.path.exists(friction_file):
-        try:
-            with open(friction_file, encoding='utf-8') as f:
-                data = json.load(f)
-        except Exception:
-            data = []
-
-    data = [e for e in data if e.get('session_id') != session_id]
-    data.extend(new_events)
-
-    data.sort(key=lambda x: (x.get('date', ''), x.get('session_id', ''),
-                              x.get('turn_index', 0)))
+def upsert_friction(tracking_dir, session_id, new_events):
+    """Write friction events to SQLite via storage module.
 
-    os.makedirs(os.path.dirname(os.path.abspath(friction_file)), exist_ok=True)
-    with open(friction_file, 'w', encoding='utf-8') as f:
-        json.dump(data, f, indent=2)
-        f.write('\n')
+    For backward compatibility, also accepts a friction.json path --
+    if tracking_dir ends with '.json', derive the tracking dir from it.
+    """
+    if tracking_dir.endswith('.json'):
+        tracking_dir = os.path.dirname(os.path.abspath(tracking_dir))
 
-    return data
+    storage.replace_session_friction(tracking_dir, session_id, new_events)
+    return new_events
 
 
 def main():
     parser = argparse.ArgumentParser(description='Parse friction events from JSONL transcript')
     parser.add_argument('transcript_path')
-    parser.add_argument('friction_file')
+    parser.add_argument('tracking_dir')
     parser.add_argument('session_id')
     parser.add_argument('project')
     parser.add_argument('source')
@@ -275,11 +268,9 @@ def main():
     events = parse_friction(args.transcript_path, args.session_id, args.project,
                             args.source, args.agent_type, args.agent_id)
 
+    upsert_friction(args.tracking_dir, args.session_id, events)
     if events:
-        upsert_friction(args.friction_file, args.session_id, events)
         print(f"{len(events)} friction event(s) recorded.")
-    else:
-        upsert_friction(args.friction_file, args.session_id, [])
 
 
 if __name__ == '__main__':

package/src/stop-hook.sh

@@ -54,13 +54,17 @@ fi
 python3 "$SCRIPT_DIR/write-turns.py" "$TRANSCRIPT" "$TRACKING_DIR" "$SESSION_ID" "$(basename "$PROJECT_ROOT")"
 
 # Parse friction events from JSONL
-python3 "$SCRIPT_DIR/parse_friction.py" "$TRANSCRIPT" "$TRACKING_DIR/friction.json" \
+python3 "$SCRIPT_DIR/parse_friction.py" "$TRANSCRIPT" "$TRACKING_DIR" \
   "$SESSION_ID" "$(basename "$PROJECT_ROOT")" "main" 2>/dev/null || true
 
 # Parse skill invocations from JSONL
 python3 "$SCRIPT_DIR/parse_skills.py" "$TRANSCRIPT" "$TRACKING_DIR" \
   "$SESSION_ID" "$(basename "$PROJECT_ROOT")" 2>/dev/null || true
 
+# Parse context compaction events from JSONL
+python3 "$SCRIPT_DIR/parse_compactions.py" "$TRANSCRIPT" "$TRACKING_DIR" \
+  "$SESSION_ID" "$(basename "$PROJECT_ROOT")" 2>/dev/null || true
+
 # Regenerate charts
 python3 "$SCRIPT_DIR/generate-charts.py" "$TRACKING_DIR" "$TRACKING_DIR/charts.html" 2>/dev/null || true
 

package/src/storage.py

@@ -67,6 +67,37 @@ SKILL_DEFAULTS = {
     "error_message": None,
 }
 
+COMPACTION_COLS = [
+    "session_id", "date", "project", "timestamp",
+    "trigger", "pre_tokens", "turn_index",
+]
+
+COMPACTION_DEFAULTS = {
+    "timestamp": None,
+    "trigger": "auto",
+    "pre_tokens": 0,
+    "turn_index": None,
+}
+
+FRICTION_COLS = [
+    "session_id", "date", "project", "timestamp", "turn_index",
+    "source", "agent_type", "agent_id", "category",
+    "tool_name", "skill", "model", "detail", "resolved",
+]
+
+FRICTION_DEFAULTS = {
+    "timestamp": None,
+    "turn_index": 0,
+    "source": None,
+    "agent_type": None,
+    "agent_id": None,
+    "tool_name": None,
+    "skill": None,
+    "model": None,
+    "detail": None,
+    "resolved": None,
+}
+
 SCHEMA_SQL = """\
 CREATE TABLE IF NOT EXISTS turns (
     session_id TEXT NOT NULL,
@@ -119,6 +150,40 @@ CREATE TABLE IF NOT EXISTS skills (
 CREATE INDEX IF NOT EXISTS idx_skills_session ON skills(session_id);
 CREATE INDEX IF NOT EXISTS idx_skills_name ON skills(skill_name);
 
+CREATE TABLE IF NOT EXISTS compactions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    date TEXT NOT NULL,
+    project TEXT NOT NULL,
+    timestamp TEXT,
+    trigger TEXT NOT NULL DEFAULT 'auto',
+    pre_tokens INTEGER NOT NULL DEFAULT 0,
+    turn_index INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_compactions_session ON compactions(session_id);
+CREATE INDEX IF NOT EXISTS idx_compactions_date ON compactions(date);
+
+CREATE TABLE IF NOT EXISTS friction (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    date TEXT NOT NULL,
+    project TEXT NOT NULL,
+    timestamp TEXT,
+    turn_index INTEGER DEFAULT 0,
+    source TEXT,
+    agent_type TEXT,
+    agent_id TEXT,
+    category TEXT NOT NULL,
+    tool_name TEXT,
+    skill TEXT,
+    model TEXT,
+    detail TEXT,
+    resolved INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_friction_session ON friction(session_id);
+CREATE INDEX IF NOT EXISTS idx_friction_date ON friction(date);
+CREATE INDEX IF NOT EXISTS idx_friction_category ON friction(category);
+
 CREATE TABLE IF NOT EXISTS metadata (
     key TEXT PRIMARY KEY,
     value TEXT
@@ -167,6 +232,28 @@ def _insert_skills(conn: sqlite3.Connection, entries: list[dict]) -> None:
         conn.executemany(sql, rows)
 
 
+def _insert_compactions(conn: sqlite3.Connection, entries: list[dict]) -> None:
+    """INSERT compactions via executemany (always appends — autoincrement id)."""
+    placeholders = ", ".join(["?"] * len(COMPACTION_COLS))
+    sql = f"INSERT INTO compactions ({', '.join(COMPACTION_COLS)}) VALUES ({placeholders})"
+    rows = []
+    for e in entries:
+        rows.append(tuple(e.get(col, COMPACTION_DEFAULTS.get(col)) for col in COMPACTION_COLS))
+    if rows:
+        conn.executemany(sql, rows)
+
+
+def _insert_friction(conn: sqlite3.Connection, entries: list[dict]) -> None:
+    """INSERT friction via executemany (always appends — autoincrement id)."""
+    placeholders = ", ".join(["?"] * len(FRICTION_COLS))
+    sql = f"INSERT INTO friction ({', '.join(FRICTION_COLS)}) VALUES ({placeholders})"
+    rows = []
+    for e in entries:
+        rows.append(tuple(e.get(col, FRICTION_DEFAULTS.get(col)) for col in FRICTION_COLS))
+    if rows:
+        conn.executemany(sql, rows)
+
+
 def _maybe_migrate(conn: sqlite3.Connection, tracking_dir: str) -> None:
     """One-time migration from JSON files to SQLite.
 
@@ -200,6 +287,16 @@ def _maybe_migrate(conn: sqlite3.Connection, tracking_dir: str) -> None:
         except (json.JSONDecodeError, OSError):
             pass
 
+    friction_path = os.path.join(tracking_dir, "friction.json")
+    if os.path.exists(friction_path):
+        try:
+            with open(friction_path, encoding="utf-8") as f:
+                data = json.load(f)
+            if data:
+                _insert_friction(conn, data)
+        except (json.JSONDecodeError, OSError):
+            pass
+
     now = datetime.now(timezone.utc).isoformat()
     conn.execute(
         "INSERT OR REPLACE INTO metadata (key, value) VALUES (?, ?)",
@@ -212,7 +309,7 @@ def _maybe_migrate(conn: sqlite3.Connection, tracking_dir: str) -> None:
     conn.commit()
 
     # Rename originals so migration won't re-run even without the metadata check
-    for path in (tokens_path, agents_path):
+    for path in (tokens_path, agents_path, friction_path):
         if os.path.exists(path):
             try:
                 os.rename(path, path + ".migrated")
@@ -324,6 +421,50 @@ def get_all_skills(tracking_dir: str) -> list[dict]:
     return result
 
 
+def replace_session_compactions(
+    tracking_dir: str, session_id: str, entries: list[dict]
+) -> None:
+    """Delete all compactions for a session and insert replacements atomically."""
+    with get_db(tracking_dir) as conn:
+        conn.execute("DELETE FROM compactions WHERE session_id = ?", (session_id,))
+        _insert_compactions(conn, entries)
+        conn.commit()
+
+
+def get_all_compactions(tracking_dir: str) -> list[dict]:
+    """Return all compaction rows as dicts (without the autoincrement id), ordered by id."""
+    with get_db(tracking_dir) as conn:
+        rows = conn.execute("SELECT * FROM compactions ORDER BY id").fetchall()
+    result = []
+    for r in rows:
+        d = dict(r)
+        d.pop("id", None)
+        result.append(d)
+    return result
+
+
+def replace_session_friction(
+    tracking_dir: str, session_id: str, entries: list[dict]
+) -> None:
+    """Delete all friction for a session and insert replacements atomically."""
+    with get_db(tracking_dir) as conn:
+        conn.execute("DELETE FROM friction WHERE session_id = ?", (session_id,))
+        _insert_friction(conn, entries)
+        conn.commit()
+
+
+def get_all_friction(tracking_dir: str) -> list[dict]:
+    """Return all friction rows as dicts (without the autoincrement id), ordered by id."""
+    with get_db(tracking_dir) as conn:
+        rows = conn.execute("SELECT * FROM friction ORDER BY id").fetchall()
+    result = []
+    for r in rows:
+        d = dict(r)
+        d.pop("id", None)
+        result.append(d)
+    return result
+
+
 def count_turns_for_session(tracking_dir: str, session_id: str) -> int:
     """Return the number of turns for a given session."""
     with get_db(tracking_dir) as conn: