--- title: "Claudoscope 1.0: from a menu bar readout to a lens on Claude Code" description: "Claudoscope 1.0 adds Claude Code notifications, cost alerts, an MCP server for your own usage data, and a session index that loads in under a second instead of 25." canonical: https://claudoscope.com/blog/claudoscope-1-0-from-a-menu-bar-readout-to-a-lens author: Liran Baba datePublished: 2026-07-27 last_updated: 2026-07-27 --- # Claudoscope 1.0: from a menu bar readout to a lens on Claude Code *July 27, 2026 · Liran Baba · 11 min read* The first version of Claudoscope displayed one number. It sat in my menu bar and told me roughly what I had spent in Claude Code that day. That was the entire product, and for about a week it was enough. Then I wanted to know which session the number came from. Then which project. Then whether the expensive one was expensive because it did a lot, or because it got stuck in a loop and burned cache on the same context forty times. Every feature since has been a version of the same question: what is Claude Code actually doing when I'm not watching it? Today that question has enough answers to call it 1.0. ## What's new in 1.0 - Notifications when Claude needs you or finishes a turn, with terminal-tab focus on tap. - Cost alerts on four rules, from a single-session cap to a monthly total. - A read-only MCP server so Claude Code can query your own usage data. - A Files tab listing every file Claude edited, with per-edit diffs. - A SQLite session index that cuts launch on a 3,000-session corpus from 25 seconds to sub-second. - Cost estimates reconciled against real Anthropic bills, including web search, which was not being billed at all. ## The dashboard I kept not opening Here is the uncomfortable thing I noticed somewhere around version 0.7. I had built a genuinely nice session browser, with charts and search and a config linter, and I was opening it maybe twice a week. Meanwhile the things I actually needed to know were all time-sensitive. A session going sideways is worth knowing about while it's going sideways. A leaked credential in a transcript matters most in the minutes after it lands, not at the end of the month. Claude sitting there waiting on a permission prompt while I read something in another window is pure dead time, and I would find it three minutes later every time. A dashboard you have to remember to open is a dashboard that has already failed at the part that mattered. So the bulk of 1.0 went into making the app come to you. ## Claude Code notifications, so the session finds you Claudoscope can now install Claude Code `Notification` and `Stop` hooks and turn them into two native macOS notifications, each independently toggleable. - **Claude needs you** fires on a real block: a permission prompt, a plan approval, an MCP prompt. - **Your turn** fires when Claude finishes a turn and is waiting on you. Both are event-driven, which is the part that took the longest to get right. Neither one re-fires on its own, so you don't get the slow drip of repeat banners that makes people turn notifications off within a day. There's per-project mute, daily quiet hours, and a sound toggle. Each notification is labeled with the project folder name, pulled from the hook payload rather than the terminal title, so it reads the same whether you renamed the session with `/rename` or not. The detail I'm most pleased with: tapping a banner focuses the terminal tab running that session. Ghostty, iTerm2, and Terminal.app, matched by project folder. This is the behavior everyone's hand-rolled notify script has, and losing it would have made the built-in version a downgrade. On that note, if you already have a `session-notify.sh` wired into your hooks, Claudoscope detects it, backs it up, and disables its `Notification` and `Stop` entries when you enable notifications, then restores them if you turn the feature off. No duplicate banners, no silently clobbered config. ## Claude Code cost alerts, before the bill instead of after Cost alerts are optional and off by default. Four rules, with thresholds you set in estimated dollars or tokens: - A single-session cap. - Rolling-window spend, anywhere from 5 minutes to 4 hours, which doubles as runaway-burn detection. - A daily total. - A monthly total. They arrive as a macOS notification plus a red dot on the menu bar icon, and they stay in the popover until you dismiss them. Alerts re-fire at each doubling rather than continuously, so crossing a threshold gets you a notification at the threshold, then at 2x, then at 4x, instead of a stream of increasingly ignorable ones. The fiddly part of shipping this was making sure alerts never lie. Rolling spend is tracked by an in-memory delta ledger that rebaselines whenever the app rescans or you switch pricing providers. Without that, changing a pricing setting or leaving the app closed for a week would replay old spend as if it happened just now, and you'd open your laptop to a wall of phantom alerts. Alerts also stay suppressed until the first reconcile finishes on launch, for the same reason. ## Querying your own Claude Code usage over MCP This is the one I didn't plan and now use constantly. Claudoscope can run a read-only MCP server inside the app, off by default, so that Claude Code can ask questions about your own Claude Code usage. Nine tools cover usage totals, project and session listing and search, config linting, plans, and canon records. In practice it means you can type things like "what did I spend on this project last week, broken down by model" or "find the session where I set up the deploy pipeline" and get a real answer from your own local data, in the terminal, without opening the dashboard at all. The usage tools reuse the exact analytics engine the dashboard uses, so the numbers match rather than approximately agreeing. It's served over a `0600` unix socket through a bundled stdio shim, secrets are always masked in tool output, and enabling it registers the shim through the `claude` CLI rather than reaching into `~/.claude.json` and editing it behind your back. The masking is not decorative: [a database password sitting in a session file](https://claudoscope.com/blog/found-database-password-in-claude-code-session.md) is the reason this project exists at all. ## Every file Claude touched, with the diffs Session detail gained a Files tab. It lists every file Claude edited or wrote during a session, with chronological per-edit diffs rendered from the `structuredPatch` payloads that were already sitting in the transcript unused. Subagent edits are merged in with agent badges and anchored to the call that spawned them, which turns out to be the only practical way to answer "which of the five agents changed this file" after the fact. Each edit gives you open, reveal in Finder, copy patch, and jump to the point in the chat where it happened. Files modified on disk since the session touched them get a badge, so you can tell at a glance whether you're looking at history or at something still live. ## Why the session index moved to SQLite Less glamorous, most felt. Claudoscope used to re-parse every transcript on launch. On my machine, roughly 3,000 session files across 74 projects, that was about 25 seconds of staring at a scan banner before the dashboard was usable. Everyone who tried the app on a large corpus hit this, and it's the single most common thing people wrote to me about. Parsed session summaries now persist in a GRDB-backed SQLite cache, keyed by file size and modification time. The dashboard paints from the cache immediately, sub-second on that same corpus, and a background reconcile re-parses only the files that actually changed. The design rule I held to is that the cache is a pure derivative and never a source of truth. A parser change, a pricing table edit, a provider or region switch, or a timezone change all wipe and rebuild it in the background. Delete the file and it rebuilds silently. Corrupt it and it rebuilds silently. Nothing you can do to that cache should ever produce a wrong number, because a stale cost figure that looks plausible is worse than no figure at all. ## Getting the cost numbers right Cost estimates in 1.0 have been reconciled against real Anthropic bills, and two things came out of that work. The first is that web search was not being billed at all. The fee is a cent per search, and 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. If you parse the documented field, as I did, you get nothing. It's now billed per search, deduped by record, and attributed to the day and model that issued it. The second is structural. Model family detection used to work by parsing a version number out of the model id and treating anything it could not parse as an older generation. That's exactly backwards: it means every new model Anthropic ships is guessed at, and guessed conservatively in the direction of the higher legacy rate. 1.0 inverts it. Claudoscope now matches an explicit closed list of the generations that actually billed at older rates, and anything unrecognized prices at the current rate. A model id it's never seen before is far more likely to be new than ancient. ## Canon and agent routing Two opt-in rails that come at the problem from the other direction, shaping what Claude Code does rather than reporting on it. **Canon** is a per-project store of settled engineering decisions that lives in the repo instead of in per-machine memory. Enabling it for a project installs a protocol rule and a records file into the working tree, so decisions get captured in a file that is committed alongside the code and travels to everyone who clones it. Claudoscope is the installer and the viewer, never the writer: it renders records read-only as structured cards. The reason for that boundary is that a decision log an app can silently edit is not a decision log. **Agent Routing** installs a set of cost-aware, role-scoped subagents into `~/.claude/agents/`, along with an orchestration policy appended to your global `CLAUDE.md` between markers. The idea is simple economics: a "where is this function defined" lookup should not run on the same model as a design-sensitive refactor. Install, reinstall, revert, and uninstall all mirror the Hardening rail, with timestamped backups before every write, and uninstall deliberately preserves agent files you have edited yourself. There's also a read-only Agents rail listing every agent installed on the system, user-level, per-project, and plugin-provided. Building it surfaced a frontmatter parser bug that treated the opening `---` fence as the closing one and quietly dropped metadata, which had been degrading the Skills rail and the plugin drill-down too. ## The smaller things A partial list, because the full changelog is long: - A Focus filter in the chat view, with separate Thinking and Tool/MCP switches, for reading just the conversation. Filtering is render-time only, so cost and analytics stay computed on the full transcript. - A persistent project and date filter above the sidebar that scopes sessions, tools, timeline, and plans at once. - Blocked and denied actions in chat, classified into destructive git, IaC destroy, permission-setting, and user-rejected. - MCP auth status for remote servers, derived from file hints only, since OAuth tokens live in the Keychain and Claudoscope does not read secrets. - A hook-matcher linter that catches matchers silently broken by recent Claude Code changes, plus governance rules for the newer `settings.json` keys. - A colorblind-safe chart palette, because the old one put green, orange, and red in the same chart. - Launch at login, a monochrome menu bar icon for tinted menu bars, and a redesigned About window. - Two bad performance bugs fixed: a chat view that pegged a core re-parsing markdown on every render, and a sidebar that performed roughly 230,000 timestamp parses per render on a large corpus and froze the UI for 80 seconds. ## Questions people asked about 1.0 ### Do I need to remove my existing notify script before enabling Claudoscope notifications? No. If you already have a `session-notify.sh` wired into your hooks, Claudoscope detects it, backs it up, and disables only its `Notification` and `Stop` entries when you turn notifications on. Turn the feature off and it restores them. No duplicate banners, no silently clobbered config. ### Why was my first launch after upgrading to 1.0 slow? Upgrading runs one full reparse in the background to build the new SQLite cache. After that the dashboard paints from cache immediately, sub-second on a corpus of roughly 3,000 sessions across 74 projects, and a background reconcile re-parses only the files that actually changed. ### How accurate are the Claude Code cost estimates in 1.0? Estimates were reconciled against real Anthropic bills. Web search is now billed at a cent per search, read from `toolUseResult.searchCount`, and a model id Claudoscope has never seen prices at the current rate rather than a legacy one. Figures remain estimates computed locally from your transcripts. ### What does Claudoscope 1.0 require? macOS 14 (Sonoma) or later on Apple Silicon. Claudoscope is free and MIT licensed, runs entirely on your machine with zero telemetry, and reads session files from local disk. Install it with Homebrew or take the DMG from the 1.0.0 release page. ## Install Free, MIT licensed, macOS 14 or later, Apple Silicon. Zero telemetry, and it never sends your session data anywhere, because it never sends anything anywhere. ```bash brew tap cordwainersmith/claudoscope brew install --cask claudoscope ``` Or take the DMG from the [1.0.0 release](https://github.com/cordwainersmith/Claudoscope/releases/tag/v1.0.0). If you're upgrading, the first launch does one full reparse in the background to build the new cache, and then launches are fast from there. ## Thanks A real amount of 1.0 exists because people filed issues about it. The SQLite index is there because several of you told me, politely and then less politely, that a 25 second launch was not acceptable. The terminal-focus behavior is there because someone pointed out that replacing their notify script with mine would lose the one feature they used it for. More than one pricing table row got fixed because somebody checked my numbers against their actual bill and told me I was off. That's a better feedback loop than I expected to get from a menu bar app that started out displaying a single number. Thank you. Keep arguing with the pricing tables. ## About the author Liran Baba builds and maintains Claudoscope, and has been running Claude Code daily across roughly 74 projects since well before there was anything to measure it with. More at [liranbaba.dev](https://liranbaba.dev) and [GitHub](https://github.com/cordwainersmith). --- Claudoscope is an independent open-source project and is not affiliated with or endorsed by Anthropic. ## Sitemap - [All pages](https://claudoscope.com/sitemap.md)