---
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