session-trends

Analyze trends from the metrics ledger. Computes windowed aggregates, fingerprint distributions, and compares against MEMORY.md baselines.

Requirements

Requires .claude/session-metrics/metrics.jsonl from /session-scan.

Usage

/session-trends                          # All windows (7d, 30d, all)
/session-trends --window 30d             # Specific window only
/session-trends --project enaia          # Filter by project
/session-trends --compare MEMORY.md      # Compare against memory baseline
/session-trends --html out.html          # Write HTML report with ASCII bars

For pure context-window stats (max prompt tokens, ctx %, compaction rate) across raw Claude Code JSONL files, see the --scan-jsonl mode of compute-metrics.py (inspired by badlogic / earendil-works/pi).

Pipeline

Step 1: Parse Arguments

Extract from $ARGUMENTS:

• --window WINDOW: Time window — 7d, 30d, or all (default: show all three)
• --project NAME: Filter metrics by project name
• --compare PATH: Path to MEMORY.md for baseline comparison (default: auto-detect from .claude/ project memory)

Step 2: Read Metrics Ledger

Read .claude/session-metrics/metrics.jsonl.

If empty or missing:

No metrics found. Run /session-scan first.

If --project specified, filter entries by project field.

Step 3: Compute Trends via Python

python3 .claude/skills/session-scan/references/compute-metrics.py \
  --trends .claude/session-metrics/metrics.jsonl \
  --memory {MEMORY_PATH}

Capture the JSON output.

Step 4: Display Trend Report

Format the JSON output as a readable report:

Overview

Total sessions: {N} ({backfilled} backfilled from v1)
Date range: {earliest} to {latest}

Window Comparison

| Metric                  | 7 days | 30 days | All time |
|-------------------------|--------|---------|----------|
| Sessions                | 12     | 45      | 165      |
| Avg friction            | 0.28   | 0.24    | 0.22     |
| Max friction            | 0.72   | 0.72    | 0.89     |
| Avg opportunity         | 0.35   | 0.30    | 0.28     |
| Tier 2 eligible         | 40%    | 33%     | 30%      |
| Plugin adoption         | 12%    | 10%     | 8%       |

Fingerprint Distribution

| Type          | 7d  | 30d | All  |
|---------------|-----|-----|------|
| bug-fix       | 4   | 15  | 52   |
| feature       | 3   | 12  | 48   |
| exploration   | 2   | 8   | 30   |
| maintenance   | 1   | 5   | 18   |
| review        | 1   | 3   | 10   |
| refactoring   | 1   | 2   | 7    |

MEMORY.md Comparison (if --compare)

Compare measured values against MEMORY.md claims:

| MEMORY.md Claim              | Measured    | Match? |
|------------------------------|-------------|--------|
| Plugin adoption: 8-12%       | 10.2%       | Yes    |
| Minimal friction in 40+ of 74| 68% smooth  | Yes    |

Step 5: Write trends.json

Write computed trends to .claude/session-metrics/trends.json.

Step 6: Suggest Actions

Based on trends:

• If friction is increasing: "Friction trending up — run /session-deep-dive --from-scan to investigate"
• If plugin adoption is growing: "Plugin adoption growing — check which commands drive value"
• If many Tier 2 eligible: "{N} sessions need deep analysis"

Output Files

File	Purpose
.claude/session-metrics/trends.json	Computed trend data

Common Queries

See references/trend-queries.md for interpreting specific trend patterns.

Iron Laws

1. ALWAYS use Python for computation — no manual aggregation
2. NEVER modify metrics.jsonl — read-only for trends
3. ALWAYS show window comparison — single numbers lack context

Acknowledgements

The HTML report layout (preformatted text + ASCII bar charts via █/░) and per-model + threshold-bucket breakdown (>=80%, >=90%, >=100%, compaction_rate) were borrowed from badlogic / earendil-works/pi session-context-stats.mjs. Our pipeline's qualitative metrics (friction, fingerprint, plugin opportunity, skill effectiveness) are additive on top.