# Claudoscope: complete site content > Claudoscope is a free, open-source (MIT) native macOS menu bar app that reads Claude Code and > Claude Cowork session files from local disk and turns them into session history, cost analytics, > secret detection, config linting, notifications, cost alerts, and a one-click security hardening > baseline for ~/.claude/. It runs 100% locally with zero telemetry and never sends data anywhere. > > This file inlines every page on claudoscope.com. For a shorter index with links instead of full > text, fetch https://claudoscope.com/llms.txt Source: https://claudoscope.com Repository: https://github.com/cordwainersmith/Claudoscope License: MIT Generated: 2026-07-29 --- --- title: "Claudoscope: Claude Code Session Viewer & Cost Analytics for macOS" description: "Free open-source macOS menu bar app for Claude Code and Cowork. Browse sessions, track costs, catch leaked secrets, and harden your ~/.claude/ setup in one click. Works with Enterprise API. Zero telemetry, 100% local." canonical: https://claudoscope.com/ doc_version: "1.0.0" last_updated: 2026-07-29 --- # Claudoscope **Your Claude Code sessions, from every angle.** A native macOS menu bar app that watches your Claude Code and Cowork sessions and tells you when something needs you: a runaway session, a leaked credential, or Claude waiting on an answer. Full history, cost analytics, and one-click hardening. Zero telemetry, 100% local. - 100% local, on disk - 0 telemetry pings - $0, free and MIT licensed ## Install Requires macOS 14 (Sonoma) or later on Apple Silicon. ```bash brew tap cordwainersmith/claudoscope brew install --cask claudoscope ``` Or [download the .dmg directly](https://github.com/cordwainersmith/Claudoscope/releases). ## Capabilities Everything you need to understand your Claude Code sessions, from real-time token tracking to deep configuration browsing, all running natively on your Mac. ### Real-time monitoring Watches `~/.claude/projects/` via macOS FSEvents for near-instant file change detection. No polling, no Electron. ### Cost and session analytics Aggregates token usage across input, output, and cache, maps it to Anthropic or Vertex AI pricing, and visualizes your sessions, spending patterns, and usage over time. Estimates are reconciled against real Anthropic bills, including per-model rate changes and the web-search request fees most trackers miss. ### Secret detection and config health 85 lint rules check your `CLAUDE.md` files, skills, and hooks for issues. Secret detection scans sessions for leaked credentials with entropy-based filtering. Session checks flag runaway costs and token usage. ### Configuration viewer Reads your `settings.json` and presents permissions, YOLO mode, memory, and custom slash commands in a browsable layout. ### Fully local and private No servers, no network requests, no analytics pings. Claudoscope reads your logs directly from disk. Nothing leaves your machine. ### Skills and MCP browser Browse installed skills with full markdown rendering. Inspect MCP server arguments, commands, and environment variables. ### 1-click security hardening Installs a layered security baseline into `~/.claude/` in one click. Deny rules, hooks, sandbox, and 13 drift checks keep the baseline in place. Fully reversible. ### Cowork sessions Reads Claude Cowork sessions from the Claude desktop app alongside your Claude Code data. One view of every Claude session you have ever run, with cost rolled into the same totals. ### Session notifications Know the moment Claude is blocked on your answer or has finished a turn. Clicking the banner focuses the terminal tab running that session, in Ghostty, iTerm2, or Terminal.app. ### Cost alerts Thresholds on a single session, a rolling window, a day, or a month. Catches a runaway burn while it is still running instead of at the end of the month. Off by default. ### Query your own usage (MCP) An optional read-only MCP server lets Claude Code answer questions about your own sessions and spend. Nine tools, running on the same analytics engine as the dashboard so the numbers match. Served over a `0600` unix socket, secrets always masked, off by default. See [AGENTS.md](https://claudoscope.com/AGENTS.md) for the tool list. ## How it works Claudoscope reads what Claude already writes to your Mac, no agents and no proxies, and turns it into live analytics, alerts, and health checks. ## Notifications and cost alerts, without the shell scripts A dashboard only helps if you remember to open it. Claudoscope comes to you: when Claude is blocked on your answer, when a session starts burning money, and when a credential leaks. - **Session notifications.** "Claude needs you" for a real block, a permission, plan, or MCP prompt, and "Your turn" when a turn finishes. Event-driven, so neither re-fires on its own. Per-project mute, quiet hours, and a sound toggle. - **Click straight back to your terminal.** Tapping a banner focuses the terminal tab running that session. Works with Ghostty, iTerm2, and Terminal.app. - **Cost alerts.** Four thresholds covering a single-session cap, rolling-window burn from 5 minutes to 4 hours, daily total, and monthly total. Native notification plus a red menu bar dot. Off by default. - **Replaces your hand-rolled hook.** An existing `session-notify.sh` is detected, backed up, and disabled on enable, then restored on disable, so banners never double up. Alert thresholds are measured against estimated cost, computed locally from your transcripts. ## Security hardening: lock down Claude Code in one click Claude Code reads your filesystem, runs shell commands, and reaches outbound networks. Out of the box, it ships with very few guardrails. Claudoscope installs a layered security baseline into `~/.claude/` and continuously verifies the baseline stays in place. - **Layered defense.** Hard-deny rules block credential paths, destructive shell commands, and pipe-to-shell exfiltration. Sandbox isolation on by default. - **Pre/post-tool hooks.** Six shell hooks vet every Bash, Edit, and Write call. Blocks young packages, force-pushes to public repos, and credential leaks before they ship. - **Drift detection.** 13 lint checks (HRD001 through HRD013) verify each layer stays in place. Plain-language explanations and one-click fixes. - **Reversible by design.** Auto-backup before install. Revert restores the pre-install state. Uninstall removes only Claudoscope artifacts. The baseline is layered, so weakening any single layer does not unlock the others. | Layer | What it does | | --- | --- | | Permissions and sandbox | Hard-deny credential paths, destructive commands, and pipe-to-shell. | | Pre/post-tool hooks | Credential scan, command validator, push guard, package-age check. | | AutoMode soft-deny | High-risk operations require explicit user intent and confirmation. | | Governance | Marker-wrapped block in your global `CLAUDE.md` keeps rules in conversation. | | Security skill | On-demand guidance for secrets, dangerous patterns, and network calls. | ## Secret detection: catch leaked secrets in your Claude Code sessions Claudoscope continuously checks your configuration quality and watches for leaked credentials, all without leaving your machine. - **Secret detection.** Scans for private keys, AWS keys, API tokens, and more. Entropy filtering minimizes false positives. - **Real-time alerts.** Floating alert when a leaked credential is detected in an active session. - **Config linting.** 85 rules across 12 families check your `CLAUDE.md` files, skills, hooks, commands, plugins, and agent config for structural issues and invalid globs. - **Health scores.** Weighted config quality grade plus session checks for runaway costs, excessive tokens, and long conversations. ## Skills and MCPs Browse all installed Claude Code skills and Model Context Protocol servers. View triggers, full definitions, and environment variables instantly. - Full markdown rendering for skills - Inspect MCP arguments and commands - Check custom slash commands defined in config ## Configuration at a glance Reads your `~/.claude/settings.json` and presents it in an organized, browsable layout. - Native Light / Dark / System themes - Track permissions, YOLO mode status, and memory - Easy toggling of Anthropic / Vertex pricing ## Frequently asked questions ### Is Claudoscope free? Yes. Claudoscope is completely free and open-source under the MIT license. ### Does Claudoscope work with Enterprise Claude Code? Yes. Claudoscope reads directly from local JSONL session files in `~/.claude/projects/`. It works with any Claude Code deployment including Enterprise API setups where cookie-based trackers cannot function. ### How is Claudoscope different from the /usage command? The `/usage` command shows a snapshot of your current session. Claudoscope gives you a full browsable history of every session, with search, cost breakdowns, and analytics across all your projects. ### Does Claudoscope collect any data? No. Claudoscope runs 100% locally on your Mac with zero telemetry. It reads session files from your local disk and never sends data anywhere. ### What is Claude Code hardening? Claudoscope's hardening locks down Claude Code in one click. Claude Code can read your filesystem, run shell commands, and reach outbound networks with very few guardrails out of the box. Claudoscope's hardening baseline blocks credential leaks, destructive commands, and risky network calls through a layered mix of deny rules, sandbox isolation, and pre/post-tool hooks. Drift checks keep the baseline in place over time, and the install is fully reversible. ### Is the security hardening reversible? Yes. Before installing the baseline, Claudoscope takes a full backup of your existing `~/.claude/` configuration. Revert restores the pre-install state from the auto-backup. Uninstall surgically removes only Claudoscope-installed artifacts and leaves any rules you added by hand intact. ### Does Claudoscope work with Claude Cowork? Yes. Claudoscope reads Cowork sessions from `~/Library/Application Support/Claude/` and surfaces them in a dedicated rail alongside your Claude Code data. Cowork spend is rolled into the analytics totals, so the dashboard reflects your full Claude bill, not just the CLI portion. The rail appears automatically once at least one Cowork session exists on disk. ### Can Claudoscope notify me when Claude Code needs my input? Yes. Session notifications are opt-in. Claudoscope installs Claude Code Notification and Stop hooks and delivers two independently toggleable native macOS notifications: "Claude needs you" when a session is blocked on a 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. Clicking a notification focuses the terminal tab running that session in Ghostty, iTerm2, or Terminal.app. ### Can Claudoscope alert me before a Claude Code session gets expensive? Yes. Cost alerts are optional and off by default. Four rules cover a single-session cap, rolling-window spend from 5 minutes to 4 hours which doubles as runaway-burn detection, a daily total, and a monthly total. Alerts arrive as a macOS notification plus a red menu bar dot and stay in the popover until dismissed. All figures are estimates computed locally from your transcripts. ### Can Claude Code query my own usage data? Yes. Claudoscope includes an optional read-only MCP server, off by default, that runs inside the app so Claude Code can query your own usage data. Nine tools cover usage totals, project and session listing and search, config linting, plans, and canon. It reuses the same analytics engine as the dashboard, so the numbers match. 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. ## Get started Free, MIT-licensed, and maintained in the open. Requires macOS 14 (Sonoma) or later. - [Download Claudoscope](https://github.com/cordwainersmith/Claudoscope/releases) - [View on GitHub](https://github.com/cordwainersmith/Claudoscope) 100% local · zero telemetry · read-only · no account · native macOS · MIT licensed. Claudoscope is an independent open-source project and is not affiliated with or endorsed by Anthropic. Built by [Liran Baba](https://liranbaba.dev). ## Sitemap - [All pages](https://claudoscope.com/sitemap.md) - [llms.txt](https://claudoscope.com/llms.txt): curated index of every page, in llms.txt format - [llms-full.txt](https://claudoscope.com/llms-full.txt): every page concatenated into one file - [AGENTS.md](https://claudoscope.com/AGENTS.md): the app and its nine MCP tools --- # Claudoscope Claudoscope is a native macOS menu bar app for observing Claude Code and Claude Cowork. It reads the session transcripts Claude already writes to local disk and turns them into history, search, cost analytics, secret detection, config linting, notifications, and a reversible security baseline for `~/.claude/`. It is free, MIT licensed, runs entirely on the local machine, makes no network requests, and requires no account. It is an independent open-source project and is not affiliated with or endorsed by Anthropic. ## Installation Requires macOS 14 (Sonoma) or later on Apple Silicon. Homebrew (recommended, auto-updates): ```bash brew tap cordwainersmith/claudoscope brew install --cask claudoscope ``` Or download the DMG from the [releases page](https://github.com/cordwainersmith/Claudoscope/releases). Current version: 1.0.0, released 2026-07-27. ## Configuration Claudoscope needs no configuration to be useful. On first launch it scans `~/.claude/projects/` and paints a dashboard. Everything below is opt-in and off by default. | Feature | Default | What enabling it does | | --- | --- | --- | | Session notifications | off | Installs Claude Code `Notification` and `Stop` hooks. Delivers "Claude needs you" on a real block and "Your turn" when a turn finishes. Per-project mute, quiet hours, sound toggle. | | Cost alerts | off | Four thresholds: single-session cap, rolling window (5 minutes to 4 hours), daily total, monthly total. Native notification plus a red menu bar dot. | | MCP server | off | Runs a read-only MCP server inside the app so Claude Code can query your own usage data. See below. | | Security hardening | not installed | Writes a layered security baseline into `~/.claude/`. Auto-backup first, fully reversible. | | Agent routing | not installed | Installs cost-aware role-scoped subagents into `~/.claude/agents/` plus an orchestration policy in your global `CLAUDE.md`, between markers. | | Canon | not installed, per project | Installs a settled-decisions record file into the working tree so decisions are committed alongside code. Claudoscope reads and renders it, never writes to it. | Pricing provider (Anthropic or Vertex AI) is a toggle in settings and changes how estimates are computed. If you already have a hand-rolled `session-notify.sh` wired into your hooks, enabling Claudoscope notifications detects it, backs it up, and disables only its `Notification` and `Stop` entries. Turning the feature off restores them. No duplicate banners. ## Usage ### Reading sessions The menu bar widget shows today's sessions, tokens, cost, and any session currently running with a live cost figure. Clicking through opens the full dashboard: session list with search, per-session chat view, a Files tab with per-edit diffs, analytics by project and model, a cache hit-rate view, and rails for Skills, MCP servers, agents, plans, and configuration. Session summaries are cached in a GRDB-backed SQLite index keyed by file size and modification time, so launch is sub-second on a corpus of roughly 3,000 sessions. The cache is a pure derivative: deleting or corrupting it triggers a silent rebuild, and a parser, pricing, provider, or timezone change wipes and rebuilds it. ### Querying your own usage from Claude Code (MCP) Enable the MCP server in Claudoscope's settings. Claudoscope registers a bundled stdio shim through the `claude` CLI rather than editing `~/.claude.json` directly, and serves over a `0600` unix socket. The server is read-only and always masks secrets in tool output. It exposes nine tools: | Tool | Returns | | --- | --- | | `get_usage` | Cost and token analytics with per-day, per-model, and per-project breakdowns plus cache analytics. | | `list_projects` | All projects with session counts, real filesystem paths, total estimated cost, and last activity. | | `list_sessions` | Sessions, newest first by default, with cost, tokens, and the transcript JSONL path. | | `search_sessions` | Keyword search over session title, slug, and project name. | | `get_session` | Full detail for one session: per-model breakdown, per-day billed contributions, subagent linkage, transcript path. | | `get_config` | Inventory of loaded Claude Code configuration: commands, skills, MCP servers, memory files, hooks, plugins. MCP env values masked. | | `lint_config` | A fresh lint of `CLAUDE.md`, rules, skills, hooks, settings, and session data for secrets, with a health score. | | `list_plans` | Saved plan files with title, project hint, creation date, and path. | | `get_canon` | Settled engineering decisions recorded in `.claude/canon.md`. | The usage tools reuse the same analytics engine as the dashboard, so numbers match rather than approximately agreeing. Typical prompts once it is connected: ``` what did I spend on this project last week, broken down by model find the session where I set up the deploy pipeline lint my Claude Code config and show me anything that leaks secrets ``` ### Hardening `~/.claude/` One click installs a layered baseline: hard-deny rules for credential paths, destructive shell commands, and pipe-to-shell exfiltration; sandbox isolation on by default; six pre/post-tool hooks that vet every Bash, Edit, and Write call; an AutoMode soft-deny requiring explicit intent for high-risk operations; a marker-wrapped governance block in your global `CLAUDE.md`; and an on-demand security skill. Thirteen drift checks (HRD001 through HRD013) verify each layer stays in place, with plain-language explanations and one-click fixes. Claudoscope takes a full backup of `~/.claude/` before installing. Revert restores the pre-install state. Uninstall removes only Claudoscope-installed artifacts and leaves hand-written rules intact. ## Constraints worth knowing - macOS only, Apple Silicon only. This is a deliberate tradeoff, not a roadmap item. - All cost figures are estimates computed locally from transcripts. They are reconciled against real Anthropic bills but remain estimates. - Claudoscope never reads secrets out of the Keychain. MCP auth status for remote servers is derived from file hints only. - Claudoscope is read-only with respect to your session data. The only things it writes are the opt-in features listed above, each backed up first. ## Links - Site: https://claudoscope.com - Source: https://github.com/cordwainersmith/Claudoscope - Releases: https://github.com/cordwainersmith/Claudoscope/releases - Issues: https://github.com/cordwainersmith/Claudoscope/issues - Author: Liran Baba, https://liranbaba.dev --- --- title: "Blog | Claudoscope" description: "Articles about Claude Code session management, cost tracking, secret detection, and developer tooling from the Claudoscope team." canonical: https://claudoscope.com/blog/ last_updated: 2026-07-27 --- # Claude Code, AI dev tooling, and building in the open By Liran Baba, AI Solutions Architect. Writing about what I learn building tools for AI-assisted development. ## Posts ### [Claudoscope 1.0: from a menu bar readout to a lens on Claude Code](https://claudoscope.com/blog/claudoscope-1-0-from-a-menu-bar-readout-to-a-lens.md) *Release, Observability · July 27, 2026 · 11 min read* Claude Code notifications, cost alerts, an embedded MCP server for querying your own usage, per-session file diffs, and a session index that loads in under a second. ### [I found my database password in a Claude Code session file](https://claudoscope.com/blog/found-database-password-in-claude-code-session.md) *Security, Observability · March 31, 2026 · 7 min read* How a leaked credential in a Claude Code session file led to building Claudoscope, a macOS menu bar app for session analytics, cost tracking, and secret detection. --- Claudoscope is an independent open-source project and is not affiliated with or endorsed by Anthropic. [Source on GitHub](https://github.com/cordwainersmith/Claudoscope). ## Sitemap - [All pages](https://claudoscope.com/sitemap.md) - [llms.txt](https://claudoscope.com/llms.txt): curated index of every page, in llms.txt format - [AGENTS.md](https://claudoscope.com/AGENTS.md): the app and its nine MCP tools --- --- 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) --- --- title: "I found my database password in a Claude Code session file" description: "How a leaked credential in a Claude Code session file led to building Claudoscope, a macOS menu bar app for session analytics, cost tracking, and secret detection." canonical: https://claudoscope.com/blog/found-database-password-in-claude-code-session author: Liran Baba datePublished: 2026-03-31 last_updated: 2026-03-31 --- # I found my database password in a Claude Code session file *March 31, 2026 · Liran Baba · 7 min read* I use Claude Code for most of my programming work, and I have very little idea what it's actually doing under the hood. A few months ago I was poking around `~/.claude/projects/` and opened a session JSONL file. Buried in the conversation, Claude Code had read a `.env` file and echoed its contents back as a tool result. My database password, sitting in plaintext, in a file I never look at. That was the afternoon I stopped what I was working on and started building Claudoscope. ## The problem isn't Claude Code. It's visibility. Claude Code doesn't have a cost breakdown per session. The Enterprise API doesn't surface spend data at all; only the admin dashboard does, and it's not granular enough. When we rolled it out across the org, nobody could answer basic questions: which sessions are expensive? Is the agent stuck in a loop somewhere? Is our `CLAUDE.md` actually doing anything useful or just eating context window? And the security angle was worse. Session files contain the full conversation, including anything the agent reads from disk. If it touches a file with credentials, those credentials now live in an unencrypted JSONL file indefinitely. Nobody was checking for that. So I built a flashlight. Claudoscope is a native macOS menu bar app. It watches your Claude Code session files locally, parses them, and gives you a dashboard. Nothing leaves your machine. The menu bar widget gives you a glance: today's sessions, tokens, cost, and any sessions that are currently running with a live cost number next to them. Click through to the full dashboard when you want the details. ### "Why did Tuesday cost $47?" That was the question I kept asking and couldn't answer. The analytics view breaks it down: cost by project, cost by model, daily trends. The cache tab shows whether your prompt cache is stable or busting on every request (cache busting is expensive and invisible without tracking). There's a what-if calculator that shows what your bill would look like if you moved Opus sessions to Sonnet. ### "Is my CLAUDE.md any good?" I didn't plan on building a config linter. It started as a quick check for obvious problems in my own setup. Then I ran it on a colleague's `CLAUDE.md` and found it was over 4,000 tokens, roughly 10% of the context window eaten by instructions before the agent even started working. So I made it a rule. The linter now has 19 rules. It checks `CLAUDE.md` structure, skill metadata, deprecated commands, token budget estimates. It groups findings by rule rather than by file, so you see patterns. One rule (subprocess env scrub) has a one-click auto-fix. The first time I ran it on our team's configs, it flagged raw XML brackets in a skill's frontmatter that would break the system prompt parser. Nobody had noticed because the failure was silent. ### Secret scanning This is probably the most useful feature and also the hardest one to get people excited about. Did the agent just leak your credentials? You'd never know unless something was watching. Claudoscope scans session files for leaked credentials: private keys, AWS access keys, auth headers, API tokens, passwords in connection strings. It uses regex matching, Shannon entropy analysis, and allowlists for placeholder values. The entropy check matters because without it you get a wall of false positives from example code and docs. When it finds something, a panel pops up on screen. Doesn't matter if the dashboard is open. It watches the tail of active session files and alerts you immediately. ## What I learned from my own data Building this meant spending a lot of time inside Claude Code's JSONL format. A few things I didn't expect: Prompt cache reads are cheap ($0.30/MTok on Sonnet vs $3.00 uncached), so I assumed most of my input was cached. On some projects, 30 to 40% wasn't. The cache busts when session context shifts after compaction, and before I had a hit rate chart staring me in the face, I had no idea. I also figured my expensive sessions would be the big multi-hour ones. They weren't. The cost was in dozens of short sessions where Claude Code loaded context, did one thing, and exited. Each one paid full input with no cache. Fifty quick questions cost me more than the three-hour refactor. Most `CLAUDE.md` files across our team were 2,000 to 5,000 tokens. Context window you pay for on every message. A few people trimmed theirs after seeing the linter's token estimate. And one gotcha for anyone parsing these files themselves: the JSONL contains intermediate records with null `stop_reason`, in-progress streaming responses. Sum all records naively and you double-count tokens. I shipped this bug and didn't catch it until cost estimates were 1.5 to 2x the actual Vertex bill. Not documented anywhere, as far as I can tell. ## Under the hood It watches `~/.claude/projects/` with macOS FSEvents (not polling). Session parsing runs on a Swift actor for thread safety. Cost estimation runs per-message, not per-session, because different messages in the same session can use different models. There's an LRU cache (20 sessions) so navigating between recent sessions feels instant. I built it in SwiftUI, macOS 14+, Apple Silicon only. I wanted it to feel like a Mac app. That means no Linux or Windows, and I'm fine with that tradeoff. ## Install Free, open source, macOS only (Apple Silicon). Homebrew: ```bash brew tap cordwainersmith/claudoscope brew install --cask claudoscope ``` Or grab the DMG from [GitHub](https://github.com/cordwainersmith/Claudoscope). It auto-updates. The cost estimation is most useful on Enterprise plans where per-session data isn't available, but session analytics and config linting work regardless of your plan. Go check your session files. You might not like what you find. --- Claudoscope is an independent open-source project and is not affiliated with or endorsed by Anthropic. ## Sitemap - [All pages](https://claudoscope.com/sitemap.md)