Claudoscope

<p align="center"> <img src="Claudoscope/Resources/logo-c-t.png" alt="Claudoscope" width="200" /> </p> <h1 align="center">Claudoscope</h1> <p align="center"> A native macOS menu bar app for exploring, analyzing, and managing your Claude Code and Cowork sessions. </p> <p align="center"> <a href="https://github.com/cordwainersmith/Claudoscope/releases/latest"><img src="https://img.shields.io/github/v/release/cordwainersmith/Claudoscope?color=blue" alt="Release"></a> <a href="https://claudoscope.com/"><img src="https://img.shields.io/badge/website-claudoscope.com-6366f1" alt="Website"></a> <img src="https://img.shields.io/badge/platform-macOS%2014.0+-000000?logo=apple&logoColor=white" alt="Platform"> <img src="https://img.shields.io/badge/install-brew%20install%20--cask%20claudoscope-FBB040?logo=homebrew&logoColor=white" alt="Homebrew"> <a href="https://dl.claudoscope.com/stats"><img src="https://img.shields.io/endpoint?url=https://dl.claudoscope.com/badge&color=green" alt="Downloads"></a> </p> <p align="center"> <a href="https://www.producthunt.com/products/claudoscope?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-claudoscope" target="_blank" rel="noopener noreferrer"><img alt="Claudoscope - Browse, search &amp; track costs across Claude Code sessions | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1112495&theme=light&t=1775035320571"></a> </p> <p align="center"> <strong>🎉 Claudoscope 1.0 is here</strong> </p> <p align="center"> Sessions now persist between launches, with cost alerts, notifications, and per-file diffs.<br /> <a href="https://github.com/cordwainersmith/Claudoscope/releases/tag/v1.0.0">See what's new</a> &nbsp;·&nbsp; <a href="CHANGELOG.md">Full changelog</a> </p>

---

Claudoscope reads your local Claude Code session files (~/.claude/projects/) and Claude Cowork sessions from the Claude desktop app, then surfaces them through a compact menu bar widget and a full-featured dashboard window. It provides real-time session tracking, cost estimation with spend alerts, analytics, per-file diffs of everything Claude changed, plan browsing, timeline history, configuration health checks, a 1-click security hardening baseline that locks down your Claude Code environment, and secret scanning that detects leaked credentials in your session history with real-time alerts, all without sending any data off your machine.

Why Claudoscope

The first version displayed one number: roughly what I had spent in Claude Code that day. 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 am not watching it?

The catch is that most of the answers are time-sensitive. A session going sideways is worth knowing about while it is going sideways. A leaked credential in a transcript matters most in the minutes after it lands. Claude sitting on a permission prompt while you read something in another window is pure dead time. A dashboard you have to remember to open has already failed at the part that mattered.

So Claudoscope works in both directions. It comes to you through session notifications, cost alerts, real-time secret scanning, and an MCP server that lets Claude Code answer questions about your own usage without opening anything. And when you do want to dig, the dashboard has the full history: every session, every file Claude touched, every plan, and a config linter for the setup underneath it all.

Everything runs locally. No telemetry, no account, no network calls beyond checking for updates.

Full version history is in CHANGELOG.md.

Table of Contents

• Why Claudoscope
• Requirements
• Installation
• How It Works
• Secret Scanning
• Hardening
• Menu Bar Widget
• Notifications and Cost Alerts
• Dashboard Window
  • Analytics
  • Sessions
  • Tools
  • Plans
  • Timeline
  • Cowork
  • Hooks
  • Commands
  • MCPs
  • Skills
  • Agents
  • Plugins
  • Memory
  • Canon
  • Config Health
  • Agent Routing
  • Settings
• Command Palette
• Cost Estimation
• Acknowledgments
• License

Requirements

• macOS 14.0 (Sonoma) or later
• Apple Silicon Mac (M1 or later). Intel Macs are not currently supported.
• Claude Code installed and used at least once (so that ~/.claude/projects/ exists with session data)

Installation

Using an AI coding agent? Point it at AGENT-INSTALL.md and it will handle the Homebrew install for you.

Homebrew (recommended)

brew tap cordwainersmith/claudoscope
brew install --cask claudoscope

Updating

Claudoscope checks for updates automatically via GitHub Releases. When a new version is available, an indicator appears in the menu bar popover and in Settings > Updates. Clicking "Download and Install" downloads the new DMG, verifies its code signature, replaces the app, and relaunches. No manual steps required.

You can also update via Homebrew:

brew upgrade --cask claudoscope

Or disable automatic checks entirely in Settings > Updates.

Manual install

Download the latest Claudoscope.dmg from the Releases page, open it, and drag Claudoscope to your Applications folder.

How It Works

Claudoscope monitors ~/.claude/projects/ using macOS FSEvents for near-instant detection of changes to JSONL session files. Updates parse incrementally and surface in the UI in real time. No polling, no server process, no network requests, everything runs locally.

Parsed session summaries persist in a local SQLite index, so launching paints the dashboard from disk immediately (sub-second on a ~3,000-file corpus) instead of re-reading every transcript. A background pass then re-parses only the files that actually changed. The index is a pure derivative of your session files: change the parser, the pricing tables, the provider, or your timezone and it rebuilds itself in the background. Delete it and nothing is lost. Fully parsed sessions are additionally held in an in-memory LRU cache for instant re-access while you browse.

The app runs as an accessory process (LSUIElement = true) and lives in your menu bar without a permanent Dock presence. The Dock icon appears only while the dashboard window is open.

Optionally, Claudoscope can expose its own data back to Claude Code through a read-only MCP server (off by default, see Settings), so you can ask Claude about your own usage.

Secret Scanning

Claudoscope detects leaked credentials inside Claude Code session files and alerts you in real time. Ten credential patterns are scanned across your full Claude Code session history:

• Private keys (RSA, OpenSSH, PGP, EC)
• AWS access keys and secret access keys
• HTTP Authorization headers (Bearer, Basic)
• API keys and tokens
• Password literals in code, config, and connection strings
• Database connection strings with embedded credentials
• Platform tokens (GitHub PATs/OAuth, OpenAI, Anthropic, Stripe, Slack, npm, Google, SendGrid, Shopify, DigitalOcean, Linear, PyPI, HuggingFace, Azure, Vault, Docker)
• Slack incoming webhook URLs
• Critical platform tokens (Stripe live keys, Stripe webhook secrets, OpenAI service/admin keys, Anthropic admin keys, Azure storage account keys, Vault tokens) escalated to ERROR severity
• Subprocess credential exposure when env scrubbing is disabled

A multi-stage false-positive filter (Shannon entropy analysis, capture-group value extraction, randomness heuristics, and expanded allowlists for placeholders and conversational context) keeps noise low.

Real-time alerts: when a session file is updated, Claudoscope scans the tail of the file for new credentials and pops a floating alert panel on a match. Toggle in Settings > Security.

Background full-history scan: a complete sweep of all session files runs in the background under Config Health and reports every match grouped by rule. Config and session checks load instantly while secret scanning progresses with an inline indicator.

All scanning is local. Detected secrets never leave your machine, and Claudoscope never transmits session content over the network.

Hardening

Claude Code is powerful by design: it reads your filesystem, runs shell commands, and reaches outbound networks. Out of the box, those capabilities ship with very few guardrails. Claudoscope's Hardening rail installs a vendor-neutral security baseline into ~/.claude/ in a single click, then continuously verifies that the baseline stays in place.

The baseline is layered, so weakening any single layer does not unlock the others:

• Permissions and Sandbox. Hard-deny rules block reads and writes to credential paths (~/.ssh/, .netrc, .npmrc, secrets/), block destructive shell commands (rm -rf /, sudo, chmod 777, eval, git push --force, git reset --hard), and block pipe-to-shell exfiltration (curl ... | sh). Sandbox isolation is turned on for tool execution.
• Hooks. Six PreToolUse and PostToolUse shell hooks vet every Bash, Edit, and Write call before it runs: a credential scanner, a command validator, a public-repo push guard, a proprietary-file flag, a package-age check that blocks dependencies less than 14 days old, and an intent guard for git reset --hard.
• AutoMode. Soft-deny rules require explicit user intent for high-risk operations. Force-pushes must name a target branch, git reset --hard requires a specific ref, and every curl or wget invocation requires the URL, the purpose, and explicit confirmation in the user's message.
• Governance. A marker-wrapped block is appended to your global CLAUDE.md so the agent has the rules in-conversation. This layer is advisory: the hard enforcement lives in the layers above.
• Security skill. A security-awareness skill is deployed that the agent can consult on demand for guidance on secrets, dangerous code patterns, and external connectivity.

Reversible by design. Before writing anything, the installer takes a full backup of your existing ~/.claude/ configuration. Three lifecycle actions are always one click away from the rail:

• Install / Reinstall refreshes every layer from the bundled baseline.
• Revert restores the pre-install state from the auto-backup.
• Uninstall surgically removes every Claudoscope-installed artifact, leaving any rules you added by hand intact.

Drift detection. Eleven lint checks (HRD001 through HRD011) verify each layer stays in place after install. If a deny rule, hook, or governance block goes missing, the rail flags the drift, explains the impact in plain language, and offers a one-click fix.

Trusted Sources. A dedicated sheet lets you curate the hosts, package registries, and repositories the agent is permitted to reach without explicit approval. Anything off the list requires confirmation per request, with plain-language descriptions of what each entry unlocks.

Everything runs locally. The baseline installs into your exi