# 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