中文文档

A native macOS menu bar app for monitoring your Claude Code, Codex CLI, Gemini CLI, and marketplace-installed AI workflow plugins: sessions, subscription usage, accounts, tokens, and cost analytics in real time.

• Notch Island — live activity surface docked to the MacBook notch for every running Claude Code / Codex / Gemini session. Permission cards (Allow/Deny), waiting-input hints, and one-keystroke focus back into the exact terminal tab where the session lives.
• Plugin Marketplace — install, update, disable, or uninstall .csplugin bundles from Settings → Plugins → Discover. The official catalog lives at claude-statistics-plugins.
• Ghostty tab-accurate focus — clicking a session card jumps to the exact Ghostty tab the session is running in, even when multiple sessions share the same project directory (surface id → window+tab → cwd fallbacks).
• Multi-provider menu bar strip — menu bar shows every enabled provider (Claude / Codex / Gemini) side by side: icon + rotating window/quota usage, colour-coded at 50% (orange) and 80% (red) consumed.
• Subscription extensions — third-party endpoint plugins such as GLM Coding Plan can add token-based subscription identities alongside native OAuth/JWT accounts.
• Gemini OAuth auto-refresh — attaches the Gemini CLI client_secret so refresh no longer silently fails with HTTP 400 client_secret is missing.
• Hooks engine rewritten in Swift — replaced Python hook scripts with a single Swift HookCLI binary; faster cold start, simpler install, uniform diagnostics.

Download the latest .dmg from Releases, open it, and drag Claude Statistics into Applications.

Because the app is not notarized by Apple, macOS may block the first launch. If that happens:

xattr -cr /Applications/Claude\ Statistics.app

Or right-click the app → Open → confirm Open in the dialog.

# Clone the repository
git clone https://github.com/sj719045032/claude-statistics.git
cd claude-statistics

# Generate Xcode project
xcodegen generate

# Open in Xcode
open ClaudeStatistics.xcodeproj

For local debug runs, use the provided script:

bash scripts/run-debug.sh

This script builds using the dedicated debug DerivedData path and relaunches the menu bar app safely.

Claude Statistics has a built-in marketplace for provider adapters, terminal/editor integrations, share-card extensions, and subscription endpoints.

• Open Settings → Plugins → Discover to fetch the official catalog.
• Click Install to download a .csplugin.zip, verify its SHA-256, unzip it, trust it, and hot-load it without restarting.
• Installed user plugins can be disabled, updated, or uninstalled from Settings → Plugins → Installed.
• Current catalog categories are provider, terminal (shown as Integrations), share-card, subscription, and utility.
• Legacy catalog values remain compatible: vendor maps to provider, while chat-app and editor-integration map to terminal.

The public plugin catalog is maintained in sj719045032/claude-statistics-plugins. Plugin authors can publish .csplugin.zip assets on GitHub Releases and open a catalog PR with downloadURL, sha256, version, and permissions.

Session Detail	Transcript Search

Overview	Period Detail

Claude Statistics lives in your macOS menu bar and opens as a floating panel.

• Native NSStatusItem + floating panel experience
• Multi-provider usage strip — every enabled provider (Claude / Codex / Gemini) gets its own cell in the menu bar, icon + rotating window/quota usage, colour-coded at 50% / 80% consumed; per-provider visibility toggles under Settings → Menu bar display
• Fast access to Sessions, Stats, Usage, and Settings from one compact panel
• No dock icon — built as a lightweight menu bar utility

A live activity surface docked to the MacBook notch (Dynamic Island–style; falls back to a top-screen pill on non-notch Macs). Turns claude / codex / gemini hook events into on-screen interactions so you never have to leave the notch to handle an approval or know what's running.

• Active sessions panel — one glance at the notch shows every running Claude Code / Codex / Gemini session, grouped by project, with live status: waiting / working / awaiting approval
• Permission cards — Claude Code PermissionRequest hooks surface as inline Allow / Deny cards; decisions are written back through the hook protocol, no terminal switch needed
• Waiting-input indicator — idle sessions waiting on your next prompt show a subtle notch pulse so you can glance without expanding the island
• One-keystroke focus return — Return (or click) on a selected card jumps straight into that session's exact terminal tab. Precise-by-default routing:
  • Ghostty: surface id → window + tab id → cwd fallbacks
  • iTerm2: tty match
  • Terminal.app: tty match
  • Kitty / WezTerm / Alacritty: native CLI focus
• Session lifecycle pulses — session start / end, tool use, subagent start / stop, pre/post-compact events, all optional and per-provider
• Per-provider master switches — enable or disable notch notifications independently for Claude / Codex / Gemini under Settings → Notch
• Global shortcut — bring the island forward with a customizable hotkey (Settings → Keyboard shortcuts), with arrow-key navigation inside
• Focus-preserving keyboard capture — uses a global CGEventTap so the island doesn't steal key window from your terminal / editor mid-session

Claude Statistics automatically discovers and parses sessions from ~/.claude/projects/ (Claude Code), ~/.codex/projects/ (Codex CLI), and ~/.gemini/tmp/ (Gemini CLI). Each provider keeps its own parsing pipeline and local cache, so switching providers does not stop background indexing for the others.

Session List

• Search by project path, topic, session name, or session ID
• Recent sessions section for quick access
• Grouped by project directory with expandable/collapsible sections
• Each session shows topic/title, model badge, message count, token count, cost, context usage, and timestamp
• Model-aware color badges (Opus / Sonnet / Haiku)
• Batch selection mode for bulk deletion
• Real-time updates via macOS file watching where available, with provider-specific rescans for formats that need it
• Quick actions on hover: new session, resume session, open transcript, delete, copy path

Session Detail

• Per-session overview: model, duration, file size, start/end time
• Accurate token accounting: input, output, cache write, cache read
• Multi-model cost breakdown with per-model token usage
• Context window utilization percentage and visual indicators
• Token distribution bar with cache breakdown
• Tool usage ranking with animated progress bars
• Trend chart for session activity over time

Session Actions

• Resume any session in your preferred terminal
• Start a new Claude Code session in the same project
• Delete individual or multiple sessions with confirmation
• Copy session path / identifiers quickly

Built-in transcript browsing for full conversation history.

• Full transcript viewer inside the app
• Search across conversation content and tool calls
• Match navigation (previous / next)
• Search result highlighting inside markdown content
• Dedicated rendering for tool calls, tool details, and message roles
• Markdown rendering with code block support
• Better visibility into Claude tool activity inside each session

Analyze usage from the local transcript data you already have.

• All-time summary: total cost, sessions, tokens, messages
• Period-based aggregation: Daily / Weekly / Monthly
• Interactive cost bar chart with drill-down into period detail
• Period detail pages with overview, trend chart, token distribution, and model breakdown
• Cache token breakdown (5-minute write, 1-hour write, cache read)
• Period list optimized for fast scanning of cost and token-heavy windows
• All-time summary is computed from parsed sessions directly, so it stays stable across period switches

Fetches provider-specific live usage data and combines it with local session analytics.

• Claude: 5-hour and 7-day windows with utilization, reset countdown, and per-model windows when available
• Codex: local JWT-derived identity and plan context, plus transcript-based usage reconstruction
• Gemini: grouped quota buckets (Pro / Flash / Flash Lite) with reset countdown and local token trend charts
• Marketplace subscription extensions: token-based accounts and quotas for third-party endpoints such as GLM Coding Plan
• Menu bar usage text adapts to the active provider's best metric
• Extra Usage credit tracking when available
• Usage trend chart with cumulative token and cost view
• Interpolated tooltip + crosshair for chart inspection
• Animated progress bars for rate-limit usage
• Error banner with retry action and direct dashboard link when supported
• Configurable auto-refresh interval

A compact switcher in the footer lets you toggle between providers at any time. Claude ships as the default chassis provider; Codex, Gemini, and future providers can be delivered as plugins.

• Claude Code — reads ~/.claude/projects/, fetches usage from Anthropic's OAuth API
• Codex CLI — reads ~/.codex/projects/, decodes profile from local JWT
• Gemini CLI — reads ~/.gemini/tmp/, fetches usage from Gemini API, and exposes provider-specific grouped usage/trend views
• Marketplace providers — provider plugins can contribute descriptors, account UI, pricing, hooks, status line integration, and transcript/session parsing

Providers that are not installed are hidden or disabled automatically depending on the current control.

• Launch at login
• Preferred terminal selection:
  • Auto
  • Ghostty
  • Terminal.app
  • iTerm2
  • Warp
  • Kitty
  • Alacritty
• Language selection: Auto / English / Simplified Chinese
• Font scale control
• Custom tab ordering
• Plugin marketplace: Discover / Installed tabs, install/update/disable/uninstall, trust reset, and catalog refresh
• Model pricing management (view, edit, fetch latest pricing)
• Status line integration for Claude Code, Codex CLI, and Gemini CLI
• OAuth token detection from macOS Keychain or ~/.claude/.credentials.json
• Diagnostics log export
• Sparkle-based in-app update checks

Generate beautiful, shareable stat cards from your session analytics.

• Persona-driven roles — 9 unique share roles (Vibe Coding King, Tool Summoner, Night Shift Engineer, etc.) with themed gradients, SF Symbols artwork, and mascot scenes
• Achievement badges — 11 unlockable badges across categories like schedule, context, model preference, tooling, cost efficiency, and burst usage
• Proof metrics — data-backed evidence showing your top stats (token counts, session counts, tool usage, cost efficiency)
• QR code integration — each card includes a QR code for sharing or quick access
• Export as PNG — render and save share cards at native resolution for social media or messaging

• Material-based cards with consistent design tokens (Theme.swift)
• Hover scale animation for clickable icon buttons
• Sliding capsule indicators for tab and period selection
• Chevron rotation and push transitions for expandable groups
• Chart reveal animation from left to right
• Staggered list entry animations in statistics views
• Improved hover feedback in session and statistics rows

• macOS 14.0+
• Xcode 16.0+ (for local development)
• XcodeGen (to generate the project from project.yml)

Claude Statistics supports three providers, each with its own local-first data sources:

Claude Code

• Parses JSONL transcript files under ~/.claude/projects/
• Extracts session metadata, timestamps, token counts, model usage, tool calls, and cost estimates
• Uses built-in model pricing tables (customizable via settings / pricing file)
• Fetches subscription usage windows from Anthropic's OAuth-backed API (5h / 7d / per-model)

Codex CLI

• Parses conversation files under ~/.codex/projects/
• Decodes user profile (name, email, plan) from a local JWT — no extra API calls
• Session scanning, transcript parsing, and lightweight search indexing adapted for Codex's file format

Gemini CLI

• Parses JSON transcript files under ~/.gemini/tmp/ and project roots from ~/.gemini/history/
• Extracts session history, token counts, model usage, and provider-specific grouped usage windows
• Keeps the latest snapshot when Gemini writes multiple files for the same logical session
• Uses lightweight search indexing and provider-specific usage/menu bar presentation

Plugin system

• Loads .csplugin bundles from the official marketplace catalog, the app bundle, or the user plugin folder
• Verifies marketplace downloads with SHA-256 and manifest ID matching before hot-loading
• Lets provider, terminal/editor, share-card, and subscription plugins register capabilities through ClaudeStatisticsKit
• Keeps parsing and analytics local on your machine; catalog metadata is fetched only when Discover is opened or refreshed

ClaudeStatistics/
├── App/                    # App entry, status bar controller, floating panel
├── Models/                 # Session, SessionStats, AggregateStats, UsageData, ShareRole, ShareMetrics, etc.
├── Providers/              # SessionProvider protocol + Claude, Codex, and Gemini implementations
│   ├── SessionProvider.swift
│   ├── Claude/             # ClaudeProvider, ClaudeSessionScanner, ClaudeTranscriptParser
│   ├── Codex/              # CodexProvider, CodexSessionScanner, CodexTranscriptParser
│   └── Gemini/             # GeminiProvider, GeminiSessionScanner, GeminiTranscriptParser
├── Services/               # Parsing, scanning, storage, pricing fetch, usage API, share metrics builder, logs
├── Utilities/              # Terminal launching, time formatting, language handling, share image exporter
├── ViewModels/             # SessionViewModel, UsageViewModel, ProfileViewModel
├── Views/                  # Sessions, statistics, usage, transcript, settings, theme, share cards
├── Resources/              # Localizable strings and assets
├── Plugins/                # ClaudeStatisticsKit SDK + first-party plugin targets
└── scripts/                # Debug build/run and DMG release helpers

Notable implementation details:

• SwiftUI + AppKit hybrid architecture
• NSStatusItem for menu bar presence
• Custom floating panel managed by StatusBarController
• Theme.swift design-token layer for shared styling and animation
• Sparkle for in-app updates

bash scripts/run-debug.sh

This script:

1. Kills older app instances
2. Cleans stale debug builds
3. Builds with the dedicated /tmp/claude-stats-build DerivedData path
4. Re-registers the app with Launch Services
5. Launches the fresh binary directly

bash scripts/build-dmg.sh 2.9.1
# Outputs:
#   build/ClaudeStatistics-2.9.1.dmg
#   build/ClaudeStatistics-2.9.1.zip           — full Sparkle update
#   build/releases-archive/*.delta             — incremental Sparkle updates
#   build/marketplace/*.csplugin.zip           — marketplace plugin artifacts

The script will:

1. Build a Release configuration with the specified version
2. Create a drag-to-install DMG and a ZIP for Sparkle
3. Sign both with Sparkle's EdDSA key
4. Maintain build/releases-archive/ (historical ZIPs + deltas)
5. Regenerate appcast.xml via generate_appcast, including a <sparkle:deltas> block for every prior version still in the archive
6. Package marketplace .csplugin.zip artifacts with matching .sha256 files
7. Print a ready-to-paste gh release create command at the end with all required assets (DMG, full ZIP, every new .delta file, and plugin artifacts)

Incremental updates: first release ships full ZIPs only; starting from the second release, existing users auto-download tiny .delta patches (often < 1 MB). If build/releases-archive/ is empty on a fresh checkout, seed it by downloading the most recent 2–3 shipped ZIPs from GitHub releases before running build-dmg.sh. Version numbers must be pure dotted numeric (2.9.1), otherwise Sparkle's version comparison can't rank them and delta generation is skipped.

# 1. Commit and push appcast / version updates
git add ClaudeStatistics.xcodeproj/project.pbxproj appcast.xml
git commit -m "chore: update appcast for vX.Y.Z"
git push

# 2. Switch to the publishing account
gh auth switch --hostname github.com --user sj719045032

# 3. Run the `gh release create` command the build script printed — it
#    already includes the DMG, the full ZIP, and every generated delta.

# 4. Switch back if needed
gh auth switch --hostname github.com --user tinystone007

Existing users receive updates through Sparkle's in-app updater — deltas when possible, full ZIP as fallback.

Model pricing is stored in ~/.claude-statistics/pricing.json and can be edited manually or from the Settings tab.

Claude Statistics stands on the shoulders of excellent open source work and community projects. Huge thanks to:

• claude-island (Apache 2.0) — architectural inspiration for the notch notifications layer (local socket model, notch-shape rendering, hook installer idempotency). We re-implemented the ideas independently; no code is copied.
• codex-island-app — inspiration for the terminal-focus playbook (AppleScript → AX → NSRunningApplication.activate layered fallback, TTY variant normalization). Ideas only, no code copied.

• Sparkle — signed auto-update framework powering in-app upgrades, delta patches, and EdDSA-signed appcasts.
• MarkdownView — rich Markdown rendering inside the notch cards and session detail view (brings along cmark-gfm, Highlightr, LaTeXSwiftUI, MathJaxSwift, HTMLEntities, SwiftDraw, and swift-markdown).
• TelemetryDeck SwiftSDK — privacy-respecting anonymous usage analytics (no personal data collected).

• Anthropic Claude Code, OpenAI Codex CLI, and Google Gemini CLI — the three coding assistants this app reads, tracks, and augments.
• XcodeGen — keeps the .xcodeproj regeneratable from project.yml.

If you spot an open source project we're using but haven't credited here, please open an issue — we're happy to add it.

MIT