Claudoscope v1.0.0

🎉 One point oh. Claudoscope started as a menu bar readout for a single number and grew into a full lens on where Claude Code actually spends your time and money. This is the release where the data holds still: session summaries persist between launches instead of being re-parsed every time, cost estimates have been audited against real bills, and everything Claude touched in a session is one tab away.

Thanks to everyone who filed an issue, argued with a pricing table, or just left it running in the corner of a screen.

New Features

• Persistent session index (SQLite). Launch no longer re-parses every transcript: parsed session summaries persist in a GRDB-backed cache at ~/Library/Application Support/Claudoscope/cache.sqlite, keyed by file size and mtime (context-fork subagent files additionally fingerprint their parent transcript). The dashboard paints from the cache immediately, sub-second on a ~3,000-file corpus that previously took ~25 seconds, then a background reconcile re-parses only changed files, with the scan banner counting changed files only. Deleting a session file now removes it from the UI live (new watcher delete event) instead of at next launch. The cache is a pure derivative: a parser change (versioned via SessionParser.parserVersion, which MUST be bumped with any billing/parse-logic or SessionSummary field change), a pricing rate edit (tables are hashed into the cache key), a provider/region switch, or a timezone change wipes and rebuilds it in the background, and a corrupt or deleted cache file rebuilds silently. Pricing switches and FSEvents overflows reuse the same reconcile path, so neither blocks on a full re-parse anymore. Cost alerts are suppressed until the first reconcile completes and the spend ledger rebaselines, so a week of offline appends never reads as a spend spike.

• Cost alerts (optional, off by default). Settings > Cost Alerts adds four global rules with fixed thresholds in estimated dollars or tokens: single-session cap, rolling-window spend (5 minutes to 4 hours, doubling as runaway-burn detection), daily total, and monthly total. Alerts re-fire at each doubling of the threshold (X, 2X, 4X, ...), are delivered as a macOS notification plus a red menu bar dot, and stay in the popover until dismissed. Clicking a notification opens the dashboard. All figures are estimates; fired thresholds persist across relaunches so nothing alerts twice. Rolling spend is tracked by an in-memory delta ledger that rebaselines on rescans and pricing switches, so pricing changes and offline gaps never produce phantom alerts.

• Session lifecycle notifications (opt-in). Settings > Notifications installs Claude Code Notification and Stop hooks and delivers two independently toggleable native macOS notifications (both on once enabled): "Claude needs you" for a real block (permission, plan, or MCP prompt), and "Your turn" when Claude finishes a turn. Both are event-driven, so neither re-fires on its own. Includes per-project mute, daily quiet hours, and a sound toggle. Each notification is labeled with the project/repo folder name (a /rename or slug title appears as "Title (folder)"), taken from the hook payload so it reads the same across any terminal. An existing hand-rolled session-notify.sh is detected, and its Notification and Stop entries are backed up and disabled on enable, then restored on disable, so banners are never duplicated.

• Per-session Files tab. Session detail gains a Files tab listing every file Claude edited or wrote, with chronological per-edit diffs rendered from the structuredPatch payloads already in the transcript. Subagent edits are merged in with agent badges and anchored to the call that spawned them. Each edit offers open, reveal, copy-patch, and jump-to-chat, and a badge marks files modified on disk since the session touched them. A dedicated service re-streams the transcript when the tab opens, so the parser, the lite scan, and the summary cache are untouched.

• Canon rail. An opt-in, per-project store of settled engineering decisions that travels with the repo instead of living in per-machine memory. Enabling a project installs a protocol rule and a seeded records file into its working tree so Claude Code captures decisions in a file committed alongside the code. The rail displays records read-only as structured cards with a kind filter and a hide-superseded toggle: the app is installer and viewer, never a record writer. Includes bulk enable/disable in Settings and a CAN lint family (missing protocol, gitignored records, malformed record, outdated protocol, dangling supersede) surfaced in Config Health.

• Agent Routing rail. Installs a set of cost-aware, role-scoped Claude Code subagents (recon, Explore, routine, builder, checker, plus security-review and security-build) into ~/.claude/agents/, appends a marker-delimited orchestration policy to ~/.claude/CLAUDE.md, and sets a fallbackModel only when one is absent. Install, reinstall, revert, and uninstall mirror the Hardening rail, with timestamped owner-only backups before every write and a conservative uninstall that preserves agent files you have edited. An RTG lint family flags drift.

• Agents rail. A read-only inventory of every agent installed on the system: user-level, per-project, and plugin-provided. Core routing agents are grouped into a pinned section with a badge so it is obvious which ones Claudoscope installed. Building this also fixed a frontmatter parser bug that treated the opening --- fence as the closing one and silently dropped metadata, which restores frontmatter in the Skills rail and the Plugins drill-down too.

• Embedded MCP server (off by default). An optional read-only MCP server runs inside the app so Claude Code can query your own usage data. Nine tools cover usage totals (reusing the same analytics engine as the dashboard, so the numbers match), project and session listing and search, config linting, plans, and canon. It is served over a 0600 unix socket via a bundled stdio shim, secrets are always masked, and enabling it registers the shim through the claude CLI rather than editing ~/.claude.json directly.

• Focus filter in the chat view. A Focus toggle with separate Thinking and Tool/MCP switches hides the machinery so you can read just the conversation. Filtering is render-time only, so tokens, cost, and analytics stay computed on the full transcript. Assistant records that render nothing (empty streaming fragments, blank tool-result rows) are now dropped everywhere, and in-conversation search matches only what is visible.

• Monochrome menu bar icon. Settings > Appearance can switch the menu bar icon to a template-rendered glyph that adapts to light, dark, and tinted menu bars. The color icon's alpha channel is too soft for template rendering, so this uses a separate crisp silhouette asset rather than a desaturated copy.

Improvements

• Persistent project and date filter. A global lens above the sidebar scopes the sessions, tools, timeline, and plans rails at once and survives switching between them, unlike the per-rail text filter. It reuses the Analytics date-window semantics but keeps its own state, so the Analytics controls are unaffected.

• Session notifications focus the terminal. Tapping a "Claude needs you" or "your turn" banner now focuses the terminal tab running that session, restoring the click behavior of the hand-rolled script it replaced. Supports Ghostty, iTerm2, and Terminal.app by title-matching the project folder. This requires the Apple Events entitlement, so the app asks for automation permission the first time you tap a banner.

• Settings button in the menu bar popover, so the popover no longer has to route through the dashboard window to reach preferences.

• Redesigned About screen as a proper standalone window.

• Recent sessions no longer mirror Active. The popover's Recent list was sorted purely by recency and took the top three, so active sessions (the most recent by definition) always duplicated the Active Sessions card above them. Active sessions are now excluded before the cut, so Recent complements Active instead of repeating it.

Bug Fixes

• Opus 5 priced at 3x the real rate. claude-opus-5 is the first opus id with a one-part version, and the version parser only matched two-part ids such as opus-4-8. Detection fell through to the pre-4.5 opus4 family, so every Opus 5 session was billed at $15/$75 per MTok instead of $5/$25, inflating session, project, and analytics totals threefold (one 82M-cache-read session read as $151.80 instead of $50.60). Model-family detection has been inverted to fix the underlying fragility, not just this instance: instead of parsing a version and treating anything unparseable as legacy, it now matches an explicit closed list of the generations that actually billed at the older rate (Claude 3 Opus, Opus 4 and 4.1, Haiku 3 and 3.5). An unrecognized model id therefore prices at the current rate rather than silently inheriting a 3x legacy one. Requires one full reparse, which happens in the background on first launch.

• Web-search request fee was never billed. Claudoscope under-counted cost against /usage on turns that used web search. The fee is $0.01 per search, but Claude Code records the count in toolUseResult.searchCount on the tool-result record rather than in usage.server_tool_use.web_search_requests, which is always zero in transcripts. The fee is now billed per search, deduped by record, and attributed to the day and model that issued it, with the popover and Cowork totals kept at parity.

• Sidebar froze at 100% CPU on large corpora. The global filter checked each project for surviving sessions by calling a getter that recomputed the entire projects-by-sessions map from scratch every time it was accessed. At real scale (74 projects, ~3,000 sessions) a single sidebar render performed roughly 230,000 timestamp parses and hung the UI. Both accessors now share one per-project helper, taking that render from an 80-second freeze to 0.3 seconds, with a regression test sized to the same corpus.

• Canon enable no longer pollutes nested projects. "Enable Canon for all projects" wrote .claude/rules/canon.md into every tracked project directory, including ones that are not real project roots: a parent folder that was once a session cwd (e.g. ~/projects), or a subdirectory of a repo. Because Claude Code loads .claude/rules/*.md hierarchically, a rule at an ancestor directory reappears inside every descendant project as a duplicate. Canon now installs only at eligible targets: git repository roots and standalone non-git folders. A directory that contains other tracked projects (a container) is skipped, and a repo subdirectory folds into its repository root, so canon lands once per repo and never cascades. Bulk enable reports how many projects were skipped as ineligible, per-project enable refuses containers and subdirs with an explanatory message, and the Canon rail lists only eligible projects. Opt-in state left by the old behavior self-heals: a project that is now classified as a container or subdir has its stale opt-in dropped on the next Canon refresh.