Metadata-Version: 2.4
Name: cc-statistics
Version: 0.12.18
Summary: Claude Code 会话统计工具 — 分析 AI Coding 工程指标
Author: androidZzT
License-Expression: MIT
Project-URL: Homepage, https://github.com/androidZzT/cc-statistics
Project-URL: Repository, https://github.com/androidZzT/cc-statistics
Keywords: claude-code,statistics,ai-coding,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

  cc-statistics macOS App
  
cc-statistics
  
The only AI coding tracker that unifies Claude Code, Gemini CLI, Codex CLI, and Cursor — in one native macOS app.
  
Track every token, cost, and session across all your AI tools. 100% local. Zero dependencies.

    Zero Dependencies
    Platform

    Why? •
    Features •
    Screenshots •
    Quick Start •
    CLI •
    中文

---

## 🤔 Why cc-statistics?

You're using multiple AI coding tools. But do you actually know:

- 💸 **What your combined spend is** across Claude Code, Gemini CLI, Codex, and Cursor?
- 🔧 **Which MCP tools are being called most** — and whether they're worth the tokens?
- ⏱️ **How much time Claude is actually working** versus waiting for you?
- 📈 **Which projects are consuming the most** — and across which models?

Most tools only answer this for Claude Code. cc-statistics answers it for all four.

### How does it compare?

| | cc-statistics | CCDash | claude-usage | ccflare |
|---|:---:|:---:|:---:|:---:|
| **Claude Code** | ✅ | ✅ | ✅ | ✅ |
| **Gemini CLI** | ✅ | ❌ | ❌ | ❌ |
| **Codex CLI** | ✅ | ❌ | ❌ | ❌ |
| **Cursor** | ✅ | ❌ | ❌ | ❌ |
| **Native macOS App** | ✅ | ❌ | ❌ | ❌ |
| **Pixel-Art Mascot (Clawd)** | ✅ | ❌ | ❌ | ❌ |
| **Session Search & Resume** | ✅ | ✅ | ❌ | ❌ |
| **Weekly / Monthly Reports** | ✅ | ✅ | ❌ | ❌ |
| **Webhook** (Slack / Feishu / DingTalk) | ✅ | ✅ Slack/Discord | ❌ | ❌ |
| **Tool Call Analytics** | ✅ | ✅ | ❌ | ❌ |
| **Code Changes by Language** | ✅ | ❌ | ❌ | ❌ |
| **AI vs User Time** | ✅ | ❌ | ❌ | ❌ |
| **Usage Alerts** | ✅ | ✅ | ❌ | ❌ |
| **Usage Quota Predictor** | ✅ | ✅ | ❌ | ❌ |
| **Share Session Messages** | ✅ | ❌ | ❌ | ❌ |
| **Web Dashboard** | ✅ | ✅ | ✅ | ✅ |
| **CLI Tool** | ✅ | ✅ | ❌ | ✅ |
| **Zero Dependencies** | ✅ | ✅ | ❌ | ❌ |
| Cache Efficiency Grade | ⏳ planned | ✅ | ❌ | ❌ |
| Live Stream | ⏳ planned | ✅ | ❌ | ❌ |

> cc-statistics is a community project, not affiliated with Anthropic, Google, or OpenAI.

---

## 🚀 Features

### 🌐 4-Platform Unified View
> Claude Code · Gemini CLI · Codex CLI · Cursor — switch between platforms or aggregate all four into a single report. Each source is read entirely from local files; no API keys, no accounts, no network requests.

### 🖥️ Native macOS Menu Bar App
> Pre-built SwiftUI binary — launch with `cc-stats-app` and it lives in your menu bar permanently. Shows Claude logo + today's token count + estimated cost at a glance. Turns **red** when you hit your daily usage quota. Right-click to switch display modes. Global hotkey `Cmd+Shift+C` opens the full dashboard from anywhere.

### 🐾 Clawd — Pixel-Art Status Bar Mascot
> A pixel-art Clawd mascot reacts to Claude Code's agent state in real time: idle, thinking, typing, happy, sleeping, and error — each with its own animated sprite. Built on [clawd-on-desk](https://github.com/rullerzhou-afk/clawd-on-desk) hook integration.

Clawd Animation States

### 📊 Usage Quota Predictor
> Real-time prediction of when you'll hit your usage quota based on current burn rate. Displays estimated time remaining, projected reset time, and risk level — so you can pace your usage and avoid unexpected throttling.

### 🔍 Session Search & Resume
> Search your entire session history by keyword across all platforms. Results show timestamps and a ready-to-run resume command — one copy-paste and you're back in context:
> ```bash
> claude --resume <session-id>
> ```

### 💬 Share Session Messages
> Export and share individual session conversations as clean, formatted text — useful for documenting AI-assisted work, sharing context with teammates, or archiving important sessions.

### 📊 Multi-Dimensional Analytics
> Instructions count · Tool calls Top 10 (Skill and MCP tools broken out by name) · AI processing time vs user active time · Code changes by language (via `git log --numstat`) · Token breakdown by model · Cost estimation with built-in pricing for Opus / Sonnet / Haiku / Gemini 2.5 Pro / Flash / GPT-4o

### 🔔 Usage Alerts
> Set daily and weekly cost limits. When you're over threshold, the macOS menu bar icon turns red and a native system notification fires — respecting your Focus modes, no app in foreground required.

### 📋 Weekly & Monthly Reports
> Auto-generate Markdown summaries for any period: total tokens, cost by model, most active projects, top tool calls, code changes by language. Push directly to your team channel:
> ```bash
> cc-stats --report week
> cc-stats --notify https://hooks.slack.com/services/xxx
> ```
> Slack, Feishu, and DingTalk webhooks all supported.

### ⚡ Project Comparison
> See which projects are consuming the most resources side by side:
> ```bash
> cc-stats --compare --since 1w
> ```

### 🌐 Web Dashboard
> Browser-based dark-themed dashboard for all platforms — useful on Linux/Windows or when you want a larger view than the menu bar panel.

### 🔒 100% Local & Zero Dependencies
> All data is read from local files. Nothing is sent over the network. Pure Python standard library — no `pip install`, no npm, no Docker.

---

## 🖼️ Screenshots

     🖥️ macOS App — Dark Mode
     🖥️ macOS App — Light Mode

     macOS App Dark
     macOS App Light

     📊 Usage Quota Predictor
     🔴 Max Usage Reached

     Usage Quota Predictor
     Max Usage

     🔍 Session List
     🔧 Tool Call Analytics

     Session List
     Tool Call Analytics

     ⚡ Skill / MCP Analytics
     💬 Share Session Messages

     Skill Analytics
     Share Messages

     🌐 4-Platform Unified View
     ⚙️ Settings

     Multi-Platform
     Settings

     🔔 Notifications
     🌐 Web Dashboard

     Notifications
     Web Dashboard

### CLI Demo

CC Stats CLI Demo

---

## ⚡ Quick Start

### Prerequisites

- Python 3.8+
- At least one of: Claude Code CLI, Gemini CLI, Codex CLI, or Cursor installed and used

### 3 steps

```bash
# 1. Install
uv tool install cc-statistics   # or: pipx install cc-statistics

# 2. Run your first report (all platforms, last 7 days)
cc-stats --all --since 7d

# 3. Launch macOS menu bar app (macOS only)
cc-stats-app
```

That's it. No configuration file needed.

**Alternative install methods:**

```bash
# pipx
pipx install cc-statistics

# Homebrew (macOS / Linux)
brew install androidZzT/tap/cc-statistics
```

---

## 📖 CLI Reference

```bash
cc-stats                      # Analyze current directory sessions
cc-stats --list               # List all detected projects (all platforms)
cc-stats --all --since 3d     # Last 3 days, all projects, all platforms
cc-stats --all --since 1w     # Last week
cc-stats myproject --last 3   # Last 3 sessions for a specific project
cc-stats --report week        # Generate weekly Markdown report
cc-stats --report month       # Generate monthly Markdown report
cc-stats --compare --since 1w # Side-by-side project comparison
cc-stats --notify <url>       # Push report to Slack / Feishu / DingTalk webhook
cc-stats-web                  # Open web dashboard in browser
cc-stats-app                  # Launch macOS menu bar app
```

---

## 🗂️ Data Sources

All data is read from local files. Nothing is sent over the network.

| Source | Local path |
|--------|-----------|
| Claude Code | `~/.claude/projects/<project>/<session>.jsonl` |
| Gemini CLI | `~/.gemini/tmp/<project>/chats/<session>.json` |
| Codex CLI | `~/.codex/sessions/*.jsonl` |
| Cursor | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` |
| Git Changes | `git log --numstat` in project directory |

---

## Acknowledgments

Status bar Clawd animation sprites from [clawd-on-desk](https://github.com/rullerzhou-afk/clawd-on-desk) — an Electron desktop pet that senses AI coding agent state via hooks and plays pixel-art animations.

---

## Support

If cc-statistics saves you money on your AI coding bills, consider [sponsoring](https://github.com/sponsors/androidZzT) the project.
