cordwainersmith/claudoscope

Summary

Claudoscope is a native macOS menu bar app (Swift/SwiftUI, macOS 14+) that reads Claude Code's local JSONL session files from ~/.claude/projects/ using FSEvents, then surfaces them in a dashboard with token analytics, cost estimation, conversation history, and config inspection (hooks, MCPs, memory files). It runs entirely offline with no data leaving the machine. The infra/ directory also contains a Cloudflare Workers TypeScript service that tracks download counts via KV storage.

Great for

People interested in building native macOS tooling around AI coding assistants — specifically reading and visualizing local JSONL telemetry files, working with FSEvents file watching, and building SwiftUI dashboard UIs.

Easy wins

• +Add a CONTRIBUTING.md with build instructions (the project uses XcodeGen via project.yml — document how to run `xcodegen generate` and open in Xcode)
• +Add GitHub Actions CI that builds the project with xcodebuild to catch regressions — the repo has Package.swift and project.yml already, making this straightforward
• +The Homebrew formula (homebrew/claudoscope.rb) has `version '1.0.0'` and `sha256 'PLACEHOLDER'` hardcoded — automate version/sha bumps as part of the release workflow
• +The download counter (infra/download-counter/src/index.ts) has no rate limiting or deduplication on the KV increment path — a basic IP-based or time-window dedup would make the stats more meaningful

Red flags

• !Only 1 commit recorded — either history was squashed/force-pushed or the repo was created from a zip, making it impossible to understand the evolution of the codebase or review individual changes
• !homebrew/claudoscope.rb has sha256 'PLACEHOLDER' — the published Homebrew cask is non-functional as checked in
• !No tests whatsoever (no test targets in file tree, has_tests: false) — a JSONL parser with cost calculations is exactly where silent regressions hurt users
• !No CI — breaking builds could sit undetected indefinitely
• !The Views/ directory contents are not listed in the file tree (only subdirectory names shown), so the majority of UI code is opaque from this review
• !Last commit timestamp is 2026-03-16, which is in the future relative to current date — suggests the metadata may be synthetic or the system clock was wrong during commit

Code quality

The Cloudflare Worker code (index.ts) is clean and well-structured: error handling prevents KV failures from breaking redirects via try/catch in waitUntil, VERSION_PATTERN validates input before any KV writes, and the stats endpoint is token-protected. The homebrew formula is a placeholder stub (sha256 'PLACEHOLDER'), which is a minor but real issue for anyone trying to use it. The Swift source structure (Models/, Services/, Store/, Views/, Utilities/) shows reasonable separation of concerns — SessionParser, SessionCache, AnalyticsEngine, and ClaudeFileWatcher are each in their own files. Without seeing the View implementations the full picture is incomplete, but the architecture described in the README (LRU cache, FSEvents, no polling) aligns with a thoughtful design.

What makes it unique

There's no direct competitor doing exactly this for Claude Code specifically — it occupies a real niche as a local-first observability layer for Claude Code's JSONL session files. The closest analogues would be generic JSONL log viewers or AI usage dashboards, but none are tailored to Claude Code's specific file format and config structure. That said, with 2 stars and 1 contributor it's effectively a personal tool that was open-sourced, not a community project yet.