Observatory

Observatory is a session monitoring dashboard that reads directly from Claude Code's local data files. It requires no configuration — open it and your usage history is already there.

Data Sources

Observatory merges two data sources:

• Stats cache (~/.claude/stats-cache.json) — pre-computed aggregates for all-time totals, daily token breakdowns by model, and hourly distribution
• Live JSONL scan — a real-time pass over ~/.claude/projects/ that counts messages, sessions, and tool calls from raw conversation transcripts

The cache covers historical data up to its lastComputedDate. The live scan covers everything after that date. Both are merged before display so there are no gaps.

Stat Cards

Six summary cards appear at the top of the dashboard:

• Sessions — total unique Claude Code sessions
• Messages — total user messages across all sessions
• Tool Calls — total Read, Edit, Bash, and other tool invocations
• Output Tokens — total tokens generated by Claude across all models
• Cache Hit — cache read tokens as a percentage of total input tokens
• Est. Cost — estimated cost based on Anthropic public pricing

Hover over a card label to see the exact definition.

Date Range

A global date range control filters the message, session, and tool call charts. Choose from presets (1h, 6h, 12h, 1d, 7d, 30d, 1y, all) or set a custom range. Each chart can also have its own range override — click the range button on any chart card to set an independent window. Use Reset overrides to clear all per-chart overrides and return to the global range.

Charts

• Messages per Day — area chart of daily message volume
• Sessions per Day — daily session count
• Tool Calls per Day — daily tool invocation count
• Daily Tokens by Model — stacked area chart showing token consumption per model per day; click legend items to show/hide individual models
• Daily Cost by Model — estimated daily spend per model using a blended rate derived from all-time input/output ratios; sums to the all-time cost total
• Token Type Breakdown — horizontal stacked bar per model showing input, output, cache read, and cache creation token splits
• Activity by Hour of Day — bar chart of when you use Claude, aggregated across all time

Budget Guard

Set a daily token or cost limit in Preferences. When today's usage exceeds the limit, a red alert banner appears above the stat cards.

Refresh

Click Refresh to re-scan the JSONL files and update all charts. The last-updated time is shown in the header. A spinner plays during the scan; the scan duration and file count are shown as a tooltip on the Refresh button.