Feature: Session history and spike investigation

[symonbaikov]

Summary

Add a session history view that helps users understand where their AI/API usage went and quickly investigate cost or token spikes.

Today OpenUsage is useful for seeing current usage. The next high-value step is answering questions like:

• "Yesterday, 62% of my spend came from 3 Cursor sessions."
• "The most expensive model this week was o3."
• "The most expensive tool today was Claude Code."
• "Why did my usage suddenly jump at 14:00?"

Problem

Raw totals are useful, but they do not explain why usage changed. Users need a way to trace spend/tokens back to sessions, tools, models, and time windows so they can control costs and spot unexpected behavior.

Without this, a user can see that usage increased, but cannot easily answer:

• Which sessions caused the increase?
• Which model/provider was responsible?
• Which tool or app generated the spend?
• Was the spike normal work, a misconfigured automation, or an accidental expensive model choice?

Proposed feature

Introduce a session history and spike investigation experience.

Session history

Show historical usage grouped by session with at least:

• session start/end time
• tool/app name, for example Cursor, Claude Code, Codex, etc.
• provider/model when available
• total tokens, requests, or credits where available
• estimated cost where available
• share of daily/weekly usage

The view should support sorting by cost/tokens and filtering by time range, tool/app, provider, and model.

Spike investigation

Detect unusually expensive time windows and summarize the likely cause.

Example summaries:

• "Yesterday, 62% of spend came from 3 Cursor sessions."
• "Most expensive model: o3, 41% of today's cost."
• "Most expensive tool: Claude Code, 58% of weekly spend."
• "Usage spike at 14:00: 2 sessions, 1 model, 4.3x higher than the previous hourly average."

The first version can be deterministic and simple: compare a time bucket against nearby historical buckets and surface the top contributing sessions/models/tools.

Suggested implementation shape

This likely needs three pieces:

1. A normalized historical usage/session record that can represent multiple tools/providers.
2. Aggregation helpers for grouping by time range, session, model, provider, and tool.
3. A UI/TUI view that exposes history, top contributors, and spike explanations.

The spike logic does not need to be complex for v1. A practical first version could:

• bucket usage by hour/day
• flag a bucket when usage is significantly above the recent average
• rank contributors inside that bucket by cost/tokens
• generate a short human-readable explanation from those contributors

Acceptance criteria

• Users can view historical sessions for at least the currently supported usage sources.
• Users can sort sessions by most expensive / most token-heavy.
• Users can filter history by time range.
• Users can see top contributors by tool/app, model, and provider for a selected period.
• When a usage spike exists, OpenUsage shows the main contributing sessions/models/tools.
• The feature handles missing cost/model/session metadata gracefully instead of hiding the whole record.
• The implementation includes tests for aggregation and spike-detection logic.

Open questions

• What is the best persistent storage format for historical session records?
• Should session history be local-only by default?
• Should cost estimation use provider pricing tables, provider-reported costs, or both?
• How should OpenUsage map raw usage events to a "session" when a provider does not expose session IDs?

Why this matters

This turns OpenUsage from a passive usage meter into an investigation tool. It helps users understand cost drivers, identify accidental expensive usage, and make better decisions about which tools/models to use.

[Necmttn]

The spike view will be more useful if it keeps raw attribution next to rollups.

For each session row, store provider, model, tool/app origin, request/token buckets, cache/reasoning buckets when available, cost source (provider_reported|estimated|unknown), and missing-metadata flags. Then spike buckets can be deterministic: model switch, cache miss, retry loop, tool-output growth, background automation, or unknown.

That gives users a concrete first drilldown instead of only a large cost number.

---

Generated with ax.

[symonbaikov]

@Necmttn Great point this is exactly the right direction.
For v1 we should keep raw attribution alongside rollups so spike investigation gives actionable drill-down, not just a high cost total.

I agree we should store per-session metadata including:

provider, model, tool/app
request/token buckets
cache/reasoning buckets when available
cost source (provider_reported | estimated | unknown)
missing-metadata flags
That makes spikes explainable deterministically (model switch, cache miss, retry loop, tool-output growth, automation/background work, unknown), and gives users a concrete first step to investigate. Would you like to submit a PR? I will help you along the way.