# Session Trends

> Analyze trends across session metrics. Computes windowed aggregates, deltas, and compares against MEMORY.md findings. Use periodically for progress tracking.

- **Type:** Skill
- **Install:** `agentstack add skill-oliver-kriska-claude-elixir-phoenix-session-trends`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [oliver-kriska](https://agentstack.voostack.com/s/oliver-kriska)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [oliver-kriska](https://github.com/oliver-kriska)
- **Source:** https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/.claude/skills/session-trends
- **Website:** https://phxagents.dev

## Install

```sh
agentstack add skill-oliver-kriska-claude-elixir-phoenix-session-trends
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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`](https://github.com/earendil-works/pi/blob/main/scripts/session-context-stats.mjs).
Our pipeline's qualitative metrics (friction, fingerprint, plugin
opportunity, skill effectiveness) are additive on top.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [oliver-kriska](https://github.com/oliver-kriska)
- **Source:** [oliver-kriska/claude-elixir-phoenix](https://github.com/oliver-kriska/claude-elixir-phoenix)
- **License:** MIT
- **Homepage:** https://phxagents.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-oliver-kriska-claude-elixir-phoenix-session-trends
- Seller: https://agentstack.voostack.com/s/oliver-kriska
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.