Skip to main content

Claudoscope 1.4 is here. See what's new →

New · Fleet view

Click a capability to zoom in

Claudoscope robot logo

The Claude Code session viewer for your Mac.

Claudoscope is a free, open-source session visualizer that lives in your Mac's menu bar. It reads your Claude Code and Cowork session files locally, so you can browse and search every transcript, see what each message cost, and get told 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.

brew install --cask claudoscope
Download
100%Local, on-disk 0Telemetry pings $0Free, MIT-licensed

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.

Session Viewer

Open any Claude Code session as a readable chat transcript, with tokens and cost on every message. Search inside the conversation, flip to the Files tab to see each edit as a diff, check the Context tab for how full the window got, and switch on Focus mode to hide thinking and tool calls and read just the conversation. The Trace tab plays the whole session back on a timeline. Watch a replay.

Fleet View

One board for every Claude Code session running now or in the last 24 hours, across all projects. Agents waiting on you come first, with a live wait timer and the reason they stopped. Each card shows its context size, spend per hour, and how long until its prompt cache goes cold. How the Fleet view works.

Real-time Monitoring

Watches ~/.claude/projects/ via macOS FSEvents for near-instant file change detection. No polling, no Electron. Where those files live and how long Claude Code keeps them.

Cost & 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. How this compares to /usage, the Console, and ccusage.

Secret Detection & 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 & Private

No servers, no network requests, no analytics pings. Claudoscope reads your logs directly from disk. Nothing leaves your machine.

Skills & 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've 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.

Coming from ccusage? Same session files, different job. A feature table, where the cost numbers diverge, and what maps to what.

Claudoscope vs ccusage

How it works

From files on disk to answers.

Claudoscope reads what Claude already writes to your Mac, no agents and no proxies, and turns it into live analytics, alerts, and health checks.

~/.claude/projects/ cowork sessions settings.json cost analytics alerts health score
New in 1.4

A Claude Code session viewer that plays the session back

Reading a transcript top to bottom tells you what was said. The Trace tab shows how the session actually went: every prompt, how long Claude worked on it, each tool call, subagents forking off and merging back, the context filling up, and cost climbing. Press Replay and it plays like a movie.

A 42-minute Claude Code session in the Trace tab, replayed at 300×.

Trace tab

The whole session on one time axis. Errors and blocked calls are marked, and idle stretches over five minutes fold into a labeled break so a two-day session fits one screen.

Replay

A playhead sweeps the session at 60×, 300×, or 1200×, or fits it to twenty seconds. The footer keeps the current turn, context fill, and spend so far.

Hover, click, measure

Hover any mark for a readout, click it to jump to that point in the chat, or drag across a range to count its turns, tool calls, failures, and spend.

Minimap and bookmarks

A strip above the chat shows the session at a glance. Bookmark the turns worth coming back to, with a note, and find them again from any session.

Resume in your terminal

One button opens Ghostty, iTerm2, or Terminal.app in the session's directory and runs claude --resume. Worktree sessions reopen in their worktree.

Share card

Export the trace as a PNG with duration, turns, tool calls, and cost. No transcript text goes into the image.

New in 1.0

Claude Code notifications and cost alerts, without the shell scripts

A dashboard only helps if you remember to open it. Claudoscope now 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.
4 Cost alert thresholds,
all off by default

Alert thresholds are measured against estimated cost, computed locally from your transcripts.

Claudoscope notification settings for Claude Code, with Claude needs you and Your turn toggles, quiet hours, and per-project mute
Session notifications, with per-project mute and quiet hours.
Claudoscope cost alert thresholds for Claude Code: single session, rolling window, daily total, and monthly total
Cost alerts, with four thresholds in estimated dollars or tokens.

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–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.
13 Drift checks keep the
baseline in place
Claudoscope Hardening rail showing the layered security baseline installed in ~/.claude/ with drift detection

The baseline is layered, so weakening any single layer doesn’t unlock the others.

Permissions & 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. It exists because of a database password that ended up in a session file.

  • 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.
85 Lint rules across
12 rule families
Claudoscope secret detection and config health view for Claude Code sessions
Skills browser showing installed Claude Code skills

Skills & MCP

Deep Dive into Skills & 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

Claude Code Configuration at a Glance

Reads your ~/.claude/settings.json and presents it in a beautifully organized, browsable layout.

  • Native Light / Dark / System themes
  • Track permissions, YOLO mode status, and memory
  • Easy toggling of Anthropic / Vertex pricing
Settings view showing Claude Code configuration

FAQ

Frequently asked questions

Is Claudoscope free?
Yes. Claudoscope is completely free and open-source under the MIT license.
How do I view and replay Claude Code sessions?
Install Claudoscope, a free and open-source Claude Code session viewer for macOS. It reads the JSONL transcripts Claude Code keeps in ~/.claude/projects/ and opens any session as a readable chat with tokens and cost on every message. The Trace tab lays the same session out on a time axis, showing prompts, tool calls, subagents, context fill, and cumulative cost, and Replay plays it back at up to 1200×. Resume reopens the session in your terminal with claude --resume. Everything runs locally. See the Trace tab in action.
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.
How is Claudoscope different from ccusage?
ccusage is a command-line report that prints usage by day, week, month, or session and runs anywhere Node runs. Claudoscope is a native macOS app that watches the same files live, keeps a searchable session history, scans transcripts for leaked secrets, and fires cost alerts. Both are free, local, and MIT licensed, and they run side by side. The full comparison, including when ccusage is the better pick, is on the ccusage comparison page.
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

Start exploring your Claude Code sessions, free and open source.

Free, MIT-licensed, and maintained in the open. Requires macOS 14.0 (Sonoma) or later.

Download Claudoscope View on GitHub
100% Local
Zero Telemetry
Read-Only
No Account
Native macOS
MIT Licensed