{"id":51551338,"url":"https://github.com/zihenghe04/CCDash","last_synced_at":"2026-07-12T14:01:17.242Z","repository":{"id":346602609,"uuid":"1190732754","full_name":"zihenghe04/CCDash","owner":"zihenghe04","description":"Open-source unified usage dashboard for Claude — track tokens, quota, costs across Claude Code, claude.ai \u0026 API in one panel. 开源 Claude 全平台用量监控面板，聚合 Claude Code / claude.ai / API 数据，适用于 Pro/Max 订阅用户与开发者。https://dyp23yngrtumg.ok.kimi.link","archived":false,"fork":false,"pushed_at":"2026-04-13T04:09:04.000Z","size":122357,"stargazers_count":63,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-13T05:10:13.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://dyp23yngrtumg.ok.kimi.link/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zihenghe04.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T15:09:14.000Z","updated_at":"2026-04-13T04:09:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zihenghe04/CCDash","commit_stats":null,"previous_names":["zihenghe04/ccdash"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/zihenghe04/CCDash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zihenghe04%2FCCDash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zihenghe04%2FCCDash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zihenghe04%2FCCDash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zihenghe04%2FCCDash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zihenghe04","download_url":"https://codeload.github.com/zihenghe04/CCDash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zihenghe04%2FCCDash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-10T00:00:52.212Z","updated_at":"2026-07-12T14:01:17.235Z","avatar_url":"https://github.com/zihenghe04.png","language":"Python","funding_links":[],"categories":["Usage \u0026 Cost Monitoring"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" width=\"140\" height=\"140\" alt=\"CCDash Logo\" style=\"border-radius: 24px;\"\u003e\n  \u003ch1\u003e✨ CCDash\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eSee every token. Every session. Every dollar.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\u003cem\u003eA real-time analytics dashboard for Claude Code — no API key, no signup, no build step.\u003c/em\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.8+-blue?style=flat-square\u0026logo=python\" alt=\"Python\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"License\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square\" alt=\"Platform\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/zero-dependencies-orange?style=flat-square\" alt=\"Zero Deps\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/zihenghe04/CCDash?style=flat-square\u0026color=blueviolet\" alt=\"Latest Release\"\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://zihenghe04.github.io/CCDash/\"\u003e\u003cstrong\u003e🌐 Live Demo\u003c/strong\u003e\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#-whats-new\"\u003eWhat's New\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#-why-ccdash\"\u003eWhy?\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#%EF%B8%8F-screenshots\"\u003eScreenshots\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#-remote-monitoring\"\u003eRemote\u003c/a\u003e \u0026bull;\n    \u003ca href=\"ROADMAP.md\"\u003eRoadmap\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#%E4%B8%AD%E6%96%87%E6%96%87%E6%A1%A3\"\u003e中文\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## 🆕 What's New\n\n### v0.9.2 · 2026-04-13\n\n- 🟢 **Session status column** ([#3](https://github.com/zihenghe04/CCDash/issues/3)) — every session in the list now shows a live status badge: **Working** (pulsing, active within 1 min), **Idle** (within 10 min), or **Done**. Works for local **and** remote sessions.\n- 🔌 **API endpoint detection** ([#4](https://github.com/zihenghe04/CCDash/issues/4)) — Settings now auto-detects whether Claude Code is pointed at the official API or a proxy / relay, with masked credentials (reads env vars, `~/.claude/settings.json`, `~/.claude.json`).\n- 🍏 **macOS launchd auto-start** — one-command install (`./launchd/install.sh server`) for auto-start at login + auto-restart on crash. Optional `autossh` SSH-tunnel launcher for remote agents. Templates only, no hardcoded paths.\n- 🪟 **Windows compatibility** (via [#6](https://github.com/zihenghe04/CCDash/pull/6)) — UTF-8 stdio wrapping, history file encoding fix, theme toggle re-renders dynamic components.\n\nSee the full [CHANGELOG](CHANGELOG.md) for earlier releases, or the [ROADMAP](ROADMAP.md) for what's coming next (v0.10 polish + observability, v0.11 file heat tracking, v1.0 stable).\n\n---\n\n## 🤔 Why CCDash?\n\nYou're paying for a Claude subscription. But do you actually know:\n\n- 💸 **How much would your usage cost** at API rates? (Spoiler: probably a lot more than $20/mo)\n- 📊 **Which model eats the most tokens?** Opus? Sonnet? How much cache hit are you getting?\n- ⏱️ **What's your average response time?** Is it getting slower?\n- 🔥 **Are you about to hit the rate limit?** How much of your 5h/7d quota is used?\n- 🪝 **Which session is running right now?** Which ones idle? Which are finished?\n\n**No existing tool answers these for Claude Code CLI subscribers.** CCDash does — with zero API keys, zero build step, and just Python stdlib.\n\n### How is this different?\n\n| | CCDash | Claude.ai Settings | NewAPI / One API | Karma | Dragon-UI |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Works with **subscriptions** (no API key) | ✅ | ✅ | ❌ | ✅ | ✅ |\n| Per-call **cost estimation** | ✅ | ❌ | ✅ | ✅ | ✅ |\n| **RPM / TPM / burn rate** | ✅ | ❌ | ✅ | ❌ | ✅ |\n| **TTFT** \u0026 duration tracking | ✅ | ❌ | ✅ | ❌ | ❌ |\n| **Cache efficiency** grading | ✅ | ❌ | ❌ | ✅ | ✅ |\n| **Session detail** timeline | ✅ | ❌ | ❌ | ✅ | ❌ |\n| **Session chain** tracking | ✅ | ❌ | ❌ | ✅ | ❌ |\n| **Tool / work mode** analytics | ✅ | ❌ | ❌ | ✅ | ✅ |\n| **Coding rhythm** analysis | ✅ | ❌ | ❌ | ✅ | ❌ |\n| **Multi-server** aggregation | ✅ | ❌ | ✅ | ❌ | SSH |\n| **5h + 7d quota** tracking | ✅ | ✅ | ❌ | ❌ | ❌ |\n| **Privacy mode** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Data export** (CSV/JSON) | ✅ | ❌ | ✅ | ❌ | ✅ |\n| Day/week **comparison** | ✅ | ❌ | ❌ | ❌ | ✅ |\n| Daily trend \u0026 heatmap | ✅ | ❌ | ✅ | ✅ | ✅ |\n| **MCP server** analytics | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Rate limit predictor** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Cost optimization** insights | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Token budget** management | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Git integration** (AI cost/commit) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Webhook** alerts | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **CLI tool** (`ccdash-cli.py`) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Self-hosted / zero deps | ✅ | — | ❌ | ❌ | ❌ |\n\n\u003e **Note**: CCDash is a community project, not affiliated with Anthropic.\n\n---\n\n## 🚀 Features\n\nGrouped by what you actually want to do:\n\n### 👁 See what's happening right now\n\n| | |\n|---|---|\n| 📈 **Real-time Overview** | HUD gauges for 5h \u0026 7d quota · RPM / TPM / burn-rate severity · $/day projection · avg TTFT \u0026 duration · day/week comparison with flip-card toggle |\n| 🟢 **Live session status** ·`v0.9.2` | Every session in the list shows **Working** / **Idle** / **Done** with a pulsing badge — works for local and remote sessions |\n| 📡 **Live Stream** | Real-time API call feed · colored token indicators (↓input ↑output ⟲cache) · per-call cost · pause control |\n| 🔌 **API endpoint detection** ·`v0.9.2` | Auto-detects whether Claude Code is on the official API or a **proxy / relay**, with masked credentials |\n\n### 💰 Understand your cost\n\n| | |\n|---|---|\n| 💰 **Cost Intelligence** | Per-call cost at [official pricing](https://docs.anthropic.com/en/docs/about-claude/pricing) · daily trend · per-model \u0026 per-project breakdown · cache efficiency grading |\n| 💡 **Smart Insights** | Model downgrade suggestions (Opus → Sonnet savings estimates), cache optimization, cost anomaly detection, peak-hour warning |\n| 💰 **Token Budget** | Daily / weekly / monthly limits · progress bars on Overview · thresholds at 60% / 80% / 100% with pulse animation on overrun |\n| 📊 **Comparison Reports** | Weekly \u0026 monthly reports · delta percentages with ↑↓ arrows · highlights (top model, cache rate, avg daily cost, most active day) |\n| ⚡ **Rate Limit Predictor** | Risk level (Safe → Critical) · time-to-throttle countdown · multi-window burn rates (5m/15m/30m/60m) |\n\n### 🔍 Dig into your sessions\n\n| | |\n|---|---|\n| 📋 **Session detail** | Click any session → full conversation timeline · user/assistant messages with tool call badges · file operations · session chain (all sessions in the same project) · copy Session ID / `claude --resume` command · privacy mode |\n| 🔀 **Multi-select compare** | Check multiple sessions → aggregated stats + model / tool breakdown |\n| 🔗 **Git integration** | Per-commit AI cost · AI-assisted commit percentage · avg cost per commit · commit table |\n| 🔍 **Deep analytics** | Model DNA stacked bar · tool distribution donut · **MCP server analytics** · coding rhythm · work mode · **prompt efficiency** (output ratio, cache grade, interaction mode) · activity heatmap · context window usage % |\n\n### 🌐 Go beyond one machine\n\n| | |\n|---|---|\n| 🌐 **Multi-Server aggregation** | Lightweight `agent.py` on any remote host · aggregate into one dashboard · remote session detail, chain, and **live status** · SSH tunnel friendly |\n| 👥 **Multi-Account** | Configure multiple Claude accounts (personal / work) · per-account 5h / 7d quota tracking · Settings page real-time display |\n| 🍏 **macOS launchd auto-start** ·`v0.9.2` | One-command install: `./launchd/install.sh server [tunnel]` · auto-restart on crash · autossh-backed SSH tunnel for remote agents · templates only, no hardcoded paths |\n| 🔔 **Webhook alerts** | Slack / Discord / HTTP · background monitoring for quota \u003e 80% and budget overruns · connectivity test · Slack/Discord format auto-detection |\n\n### ⌨️ Work from the terminal\n\n| | |\n|---|---|\n| ⌨️ **`ccdash-cli.py`** | Five commands — `status` · `top` · `models` · `budget` · `live` · colored output · `--server URL` for remote connections · zero dependencies |\n| 📤 **Data export** | CSV or JSON export — respects active source and filters |\n\n### 🎨 A UI that doesn't suck\n\nDark / Light theme with smooth transitions · Phosphor icons · HUD gauges with gradient glow · sliding nav indicator · page transitions · card flip animations · bilingual (EN / ZH) · Analytics **Core / Advanced** tabs to tame long pages · collapsible sections throughout\n\n---\n\n\n\n\n\n## 🎬 Demo\nhttps://github.com/user-attachments/assets/4373ee6a-a8d2-4bba-beba-e730ca015b94\n\n\n## 🖼️ Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e🌙 Overview — Dark\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e☀️ Overview — Light\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/overview-dark.png\" alt=\"Overview Dark\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/overview-light.png\" alt=\"Overview Light\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📊 Analytics\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📡 Live Stream\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/analytics.png\" alt=\"Analytics\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/live.png\" alt=\"Live Stream\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📋 System Logs\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e🔍 Session Detail\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/logs.png\" alt=\"Logs\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/logs2.png\" alt=\"Session Detail\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n- 🐍 Python 3.8+\n- 🤖 Claude Code CLI installed and used (data lives in `~/.claude/`)\n\n### 3 commands to go\n\n```bash\ngit clone https://github.com/zihenghe04/CCDash.git\ncd CCDash\npython3 server.py\n```\n\nOpen 👉 **http://localhost:8420**\n\nThat's it. No `pip install`, no `npm`, no Docker. Just Python.\n\n---\n\n## ⚙️ Configuration\n\nCopy the template and edit:\n\n```bash\ncp config.example.json config.json\n```\n\n```json\n{\n  \"remotes\": [],\n  \"claude_session_key\": \"\",\n  \"claude_org_id\": \"\",\n  \"budget\": { \"daily\": 20, \"weekly\": 100, \"monthly\": 400 },\n  \"webhooks\": []\n}\n```\n\n| Field | Required | Description |\n|:------|:--------:|:------------|\n| `remotes` | ❌ | Remote agent endpoints for multi-server monitoring |\n| `claude_session_key` | ❌ | Enables 5h/7d subscription quota tracking |\n| `claude_org_id` | ❌ | Your claude.ai organization ID |\n| `budget` | ❌ | Daily / weekly / monthly cost limits in USD |\n| `webhooks` | ❌ | Webhook endpoints for alerts (Slack / Discord / HTTP) |\n| `accounts` | ❌ | Multi-account config (array of `{name, session_key, org_id}`) |\n\n### 🔑 Getting Session Key (Optional)\n\nTo unlock real-time quota gauges:\n\n1. Log in to [claude.ai](https://claude.ai)\n2. Open DevTools (`F12`) → **Application** → **Cookies** → `claude.ai`\n3. Copy the `sessionKey` value\n4. Find your org ID in any API request URL: `organizations/{org_id}/...`\n\n\u003e 💡 The session key lasts weeks. CCDash will show a warning when it expires.\n\n---\n\n## 🌐 Remote Monitoring\n\nMonitor multiple machines from one dashboard. `agent.py` is a lightweight, read-only companion that exposes the same JSONL scanning as `server.py` over HTTP:\n\n```bash\n# 📡 On remote server (same repo cloned):\npython3 agent.py --port 8421 --token my_secret\n\n# 🔒 On local machine: SSH tunnel\nssh -L 8421:127.0.0.1:8421 user@server -N -f\n```\n\nAdd to your local `config.json`:\n\n```json\n{\n  \"remotes\": [\n    {\n      \"name\": \"GPU Server\",\n      \"url\": \"http://127.0.0.1:8421\",\n      \"token\": \"my_secret\",\n      \"enabled\": true\n    }\n  ]\n}\n```\n\nProjects from remote servers are tagged with `CLOUD` badges in the dashboard, **including live session status** — a session currently running on the remote shows as **Working** in your local panel within seconds of activity.\n\n\u003e 🍏 macOS users: `./launchd/install.sh server tunnel` below sets up the SSH tunnel with `autossh` auto-reconnect and auto-start at login. No manual `ssh -L` needed.\n\n---\n\n## 🍏 macOS Auto-Start (launchd)\n\nRun CCDash in the background with auto-restart on crash and auto-start at login — no more \"did I remember to start it?\".\n\n```bash\n# Install server auto-start\n./launchd/install.sh server\n\n# Install server + SSH tunnel (prompts for remote host/port)\n./launchd/install.sh server tunnel\n\n# Uninstall\n./launchd/install.sh uninstall\n```\n\nWhat it does:\n\n- `launchd/install.sh server` — generates `~/Library/LaunchAgents/com.ccdash.server.plist` from the template, writes your repo path and `python3`, and loads it. Server starts at login and respawns within 5 seconds if it crashes.\n- `launchd/install.sh tunnel` — installs an `autossh` tunnel (`brew install autossh` required) that keeps `127.0.0.1:\u003clocal\u003e` forwarded to `remote:\u003cport\u003e`, auto-reconnecting on dropouts. Interactively asks for user/host/port — nothing is hardcoded.\n\nLogs go to `/tmp/ccdash.log` and `/tmp/ccdash-tunnel.log`. The plist templates are in `launchd/*.template` with placeholder variables only — no private info ever hits the repo.\n\nManual control:\n\n```bash\nlaunchctl list | grep ccdash                              # status\nlaunchctl kickstart -k gui/$(id -u)/com.ccdash.server     # restart server\ntail -f /tmp/ccdash.log                                   # tail logs\n```\n\n---\n\n## ⌨️ CLI Tool\n\nCheck usage without leaving the terminal:\n\n```bash\npython3 ccdash-cli.py status        # Today's overview + quota gauge\npython3 ccdash-cli.py top           # Project TOP 5\npython3 ccdash-cli.py models        # Model cost breakdown\npython3 ccdash-cli.py budget        # Budget progress bars\npython3 ccdash-cli.py live          # Recent API calls\n```\n\nConnect to a remote CCDash instance:\n\n```bash\npython3 ccdash-cli.py --server http://myserver:8420 status\n```\n\n\u003e Requires a running `server.py`. Zero dependencies — just Python stdlib.\n\n---\n\n## 🔔 Webhook Notifications\n\nGet alerts when quota is running low or budget is exceeded.\n\n### Setup in Dashboard\n\n1. Go to **Settings** → **Webhook Notifications**\n2. Paste your webhook URL (Slack / Discord / any HTTP endpoint)\n3. Select format and click **Save**\n4. Click **Test** to verify\n\n### Supported Formats\n\n| Platform | URL Pattern | Auto-detected |\n|:---------|:-----------|:-------------:|\n| Slack | `https://hooks.slack.com/services/...` | ✅ |\n| Discord | `https://discord.com/api/webhooks/...` | ✅ |\n| Generic | Any HTTPS endpoint | — |\n\n### Or configure in `config.json`\n\n```json\n{\n  \"webhooks\": [\n    {\n      \"url\": \"https://hooks.slack.com/services/T.../B.../xxx\",\n      \"format\": \"slack\",\n      \"enabled\": true,\n      \"events\": [\"all\"]\n    }\n  ]\n}\n```\n\n### Trigger Events\n\n| Event | Condition |\n|:------|:---------|\n| `quota_warning` | 5h quota usage \u003e 80% |\n| `budget_exceeded` | Daily cost exceeds budget limit |\n\n\u003e Background check runs every 5 minutes when webhooks are configured.\n\n---\n\n## 🏗️ Architecture\n\n```\n~/.claude/projects/  ←── Claude Code writes JSONL session files here\n        │\n        ▼\n   ┌─────────┐     ┌───────────┐\n   │ server.py│────▶│  web UI   │  ← http://localhost:8420\n   └────┬────┘     └───────────┘\n        │\n        ├── Scans JSONL files for token usage \u0026 session data\n        ├── Calculates cost per call using official pricing\n        ├── (Optional) Calls claude.ai API for quota data\n        └── (Optional) Aggregates remote agent.py data\n```\n\n### Tech Stack\n\n| Layer | Technology | Why |\n|:------|:-----------|:----|\n| Backend | Python stdlib | Zero install, runs everywhere |\n| Frontend | Vanilla JS | No build step, instant load |\n| Charts | [ApexCharts](https://apexcharts.com/) | Beautiful, interactive |\n| Icons | [Phosphor](https://phosphoricons.com/) | Clean, consistent |\n| Quota | Swift (macOS) | Bypasses Cloudflare for claude.ai API |\n\n---\n\n## 📁 Project Structure\n\n```\nCCDash/\n├── 🐍 server.py            # Dashboard backend (Python stdlib)\n├── 📡 agent.py             # Remote monitoring agent\n├── ⌨️ ccdash-cli.py        # CLI quick-check tool\n├── 🍎 fetch-usage.swift    # macOS quota fetcher\n├── 🔧 config.example.json  # Config template\n├── 🚀 start.sh             # One-click launcher\n├── 🌐 web/\n│   ├── index.html          # SPA shell\n│   ├── style.css           # Dark slate + emerald theme\n│   └── app.js              # All frontend logic\n├── 📊 docs/                # GitHub Pages demo site\n├── 🗺️ ROADMAP.md           # Iteration roadmap\n├── 🖼️ screenshot/\n├── 📄 LICENSE              # MIT\n└── 📖 README.md\n```\n\n---\n\n## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full release history.\n\n## 🤝 Contributing\n\nContributions welcome! Feel free to open issues or PRs.\n\n## 📄 License\n\n[MIT](LICENSE) — Use it however you want.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n# 中文文档\n\n\u003c/div\u003e\n\n## ✨ CCDash 是什么？\n\n**每个 Token 去哪了。每个会话干了什么。每一分钱花在哪。**\n\nCCDash 是一个**自托管的实时分析面板**，用于监控 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 的使用情况。直接读取本地 JSONL 文件——**无需 API Key**、无需构建步骤、无需 Docker，只要 Python。\n\n\u003e 📌 社区项目，与 Anthropic 无关联。\n\n### 🆕 v0.9.2 最新更新\n\n- 🟢 **会话状态列** ([#3](https://github.com/zihenghe04/CCDash/issues/3)) — 会话列表每行显示实时状态徽章：**工作中**（1 分钟内活跃，脉冲效果）/ **等待中**（10 分钟内）/ **已结束**。本地和**远程会话**都支持。\n- 🔌 **API 端点自动检测** ([#4](https://github.com/zihenghe04/CCDash/issues/4)) — 设置页自动检测 Claude Code 连的是**官方 API** 还是**中转站/代理**，凭据自动掩码（读环境变量 → `~/.claude/settings.json` → `~/.claude.json`）。\n- 🍏 **macOS launchd 开机自启** — 一条命令安装：`./launchd/install.sh server [tunnel]`。崩溃自动重启，可选 autossh 隧道自启。模板无任何硬编码路径/IP。\n- 🪟 **Windows 兼容性修复**（合并 [#6](https://github.com/zihenghe04/CCDash/pull/6)）— UTF-8 stdio 包装、history.jsonl 编码修复、主题切换动态组件重渲染。\n\n完整历史见 [CHANGELOG](CHANGELOG.md)，后续计划见 [ROADMAP](ROADMAP.md)（v0.10 可观测性、v0.11 文件热力追踪、v1.0 稳定版）。\n\n### 为什么需要 CCDash？\n\n你在用 Claude 订阅，但你知道吗：\n\n- 💸 你的使用量如果按 API 计费要花多少钱？\n- 📊 哪个模型消耗了最多的 Token？缓存命中率如何？\n- ⏱️ 平均响应时间是多少？是否在变慢？\n- 🔥 离限速还有多远？5 小时 / 7 天额度用了多少？\n- 🟢 **当前哪些会话还在跑？哪些已空闲？哪些结束了？**\n\n**目前没有任何工具为 Claude Code 订阅用户提供这些数据。** CCDash 填补了这个空白。\n\n---\n\n## 🖼️ 界面预览\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e🌙 概览 · 暗色\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e☀️ 概览 · 亮色\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/overview-dark.png\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/overview-light.png\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📊 深度分析\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📡 实时监控\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/analytics.png\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/live.png\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e📋 日志\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e🔍 会话详情\u003c/strong\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/logs.png\" width=\"100%\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"screenshot/logs2.png\" width=\"100%\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🚀 快速开始\n\n```bash\ngit clone https://github.com/zihenghe04/CCDash.git\ncd CCDash\npython3 server.py\n```\n\n打开 👉 **http://localhost:8420**\n\n无需 `pip install`，无需 `npm`，无需 Docker。只要有 Python 就行。\n\n---\n\n## ⚙️ 配置说明\n\n```bash\ncp config.example.json config.json\n```\n\n| 字段 | 必填 | 说明 |\n|:-----|:----:|:-----|\n| `remotes` | ❌ | 远程 Agent 端点，用于多服务器聚合 |\n| `claude_session_key` | ❌ | claude.ai Session Key，启用额度追踪 |\n| `claude_org_id` | ❌ | claude.ai 组织 ID |\n| `budget` | ❌ | 每日/每周/每月成本上限（USD） |\n| `webhooks` | ❌ | Webhook 告警端点（Slack/Discord/HTTP） |\n| `accounts` | ❌ | 多账户配置（name/session_key/org_id 数组） |\n\n### 🔑 获取 Session Key（可选）\n\n1. 登录 [claude.ai](https://claude.ai)\n2. 按 `F12` 打开开发者工具 → **Application** → **Cookies**\n3. 复制 `sessionKey` 值\n4. 在网络请求中找到 `organizations/{org_id}/` 中的组织 ID\n\n\u003e 💡 Session Key 一般能持续数周。过期后面板会显示警告。\n\n---\n\n## 🌐 远程监控\n\n在远程服务器部署 Agent，一个面板查看所有机器：\n\n```bash\n# 📡 远程服务器\npython3 agent.py --port 8421 --token your_secret\n\n# 🔒 本地 SSH 隧道\nssh -L 8421:127.0.0.1:8421 user@server -N -f\n```\n\n在 `config.json` 中添加：\n\n```json\n{\n  \"remotes\": [{\n    \"name\": \"云服务器\",\n    \"url\": \"http://127.0.0.1:8421\",\n    \"token\": \"your_secret\",\n    \"enabled\": true\n  }]\n}\n```\n\n远程项目在面板中会显示 `CLOUD` 标签，**包括实时会话状态** —— 远程正在跑的会话几秒内就会在本地面板上变成**工作中**。\n\n\u003e 🍏 macOS 用户：下面 `./launchd/install.sh server tunnel` 一条命令把 SSH 隧道也交给 autossh 自动重连 + 开机自启，不用手动 `ssh -L`。\n\n---\n\n## 🍏 macOS 开机自启（launchd）\n\n后台运行 CCDash，崩溃自动重启，登录自动启动：\n\n```bash\n# 只装 server 自启\n./launchd/install.sh server\n\n# server + SSH 隧道（会交互式询问远程主机/端口）\n./launchd/install.sh server tunnel\n\n# 卸载\n./launchd/install.sh uninstall\n```\n\n安装器会从 `launchd/*.template` 生成真正的 plist，写入 `~/Library/LaunchAgents/`，其中仓库路径和 `python3` 会被脚本自动填充；SSH 隧道的主机/端口/用户在执行时交互式输入——**仓库里不会留下任何隐私信息**。\n\n常用命令：\n\n```bash\nlaunchctl list | grep ccdash                              # 查看状态\nlaunchctl kickstart -k gui/$(id -u)/com.ccdash.server     # 重启 server\ntail -f /tmp/ccdash.log                                   # 查看日志\n```\n\n日志输出：`/tmp/ccdash.log`（server）、`/tmp/ccdash-tunnel.log`（隧道）。\n\n---\n\n## ⌨️ CLI 命令行工具\n\n不离开终端即可查看用量：\n\n```bash\npython3 ccdash-cli.py status        # 今日概览 + 额度仪表\npython3 ccdash-cli.py top           # 项目 TOP 5\npython3 ccdash-cli.py models        # 模型成本明细\npython3 ccdash-cli.py budget        # 预算进度条\npython3 ccdash-cli.py live          # 最近 API 调用\n```\n\n连接远程 CCDash：\n\n```bash\npython3 ccdash-cli.py --server http://myserver:8420 status\n```\n\n\u003e 需要 `server.py` 运行中。零依赖，只需 Python。\n\n---\n\n## 🔔 Webhook 通知\n\n额度不足或预算超标时自动告警。\n\n在面板 **设置** → **Webhook 通知** 中配置，或在 `config.json` 中添加：\n\n```json\n{\n  \"webhooks\": [\n    {\n      \"url\": \"https://hooks.slack.com/services/T.../B.../xxx\",\n      \"format\": \"slack\",\n      \"enabled\": true,\n      \"events\": [\"all\"]\n    }\n  ]\n}\n```\n\n支持 Slack、Discord 和通用 HTTP Webhook。后台每 5 分钟检查一次触发条件（额度 \u003e80%、每日预算超标）。\n\n---\n\n## 🚀 全部功能一览\n\n按使用场景分组：\n\n### 👁 看到正在发生的一切\n\n| | |\n|---|---|\n| 📈 **实时概览** | HUD 仪表盘（5h/7d 额度）· RPM / TPM / 消耗速率 · 成本预估（$/day）· 平均首字 \u0026 耗时 · 日/周环比卡片翻转 |\n| 🟢 **会话实时状态** ·`v0.9.2` | 会话列表每行显示 **工作中** / **等待中** / **已结束** 徽章（带脉冲动画）· 本地 + 远程都支持 |\n| 📡 **实时流** | 实时 API 调用流 · 彩色 Token 指示器（↓input ↑output ⟲cache）· 单次调用成本 · 暂停控制 |\n| 🔌 **API 端点检测** ·`v0.9.2` | 自动检测 Claude Code 连的是**官方** 还是 **中转站 / 代理**，凭据掩码 |\n\n### 💰 看懂成本\n\n| | |\n|---|---|\n| 💰 **成本追踪** | 基于[官方定价](https://docs.anthropic.com/en/docs/about-claude/pricing)逐次计费 · 每日趋势 · 按模型/项目拆分 · 缓存效率评级 |\n| 💡 **智能优化** | 模型降级建议（Opus → Sonnet 节省估算）· 缓存优化 · 成本异常检测 · 高峰时段提醒 |\n| 💰 **Token 预算** | 每日 / 每周 / 每月上限 · 概览页实时进度条 · 60% / 80% / 100% 三档预警 · 超标脉冲动画 |\n| 📊 **对比报告** | 周报 \u0026 月报 · 环比增减箭头 · 亮点（最活跃模型、缓存命中率、日均成本、最活跃日）|\n| ⚡ **限速预测** | 风险等级（安全→紧急）· 剩余可用时间倒计时 · 多窗口消耗速率（5m / 15m / 30m / 60m） |\n\n### 🔍 深入每个会话\n\n| | |\n|---|---|\n| 📋 **会话详情** | 点击任意会话 → 完整对话时间轴 · 用户/助手消息带工具调用徽章 · 文件操作追踪 · 会话链（同项目下所有会话）· 复制 Session ID / `claude --resume` 命令 · 隐私模式 |\n| 🔀 **多选对比** | 勾选多个会话 → 合并统计 + 模型 / 工具分布图表 |\n| 🔗 **Git 关联** | 每 commit AI 成本 · AI 辅助提交占比 · 平均每 commit 成本 · 提交表 |\n| 🔍 **深度分析** | 模型 DNA 堆叠条 · 工具分布环图 · **MCP 服务器分析** · 编码节奏 · 工作模式 · **Prompt 效率**（输出比率 / 缓存评级 / 交互模式）· 活跃热力图 · 上下文窗口使用率 |\n\n### 🌐 跨机器使用\n\n| | |\n|---|---|\n| 🌐 **多服务器聚合** | 远程部署轻量级 `agent.py` · 所有数据汇总到一个面板 · 远程会话详情、会话链、**实时状态**一起同步 · SSH 隧道友好 |\n| 👥 **多账户** | 配置多个 Claude 账户（个人 / 工作）· 分账户 5h / 7d 额度追踪 · 设置页实时显示 |\n| 🍏 **macOS launchd 自启** ·`v0.9.2` | 一条命令：`./launchd/install.sh server [tunnel]` · 崩溃自动重启 · autossh 隧道自启 · 模板无任何硬编码 |\n| 🔔 **Webhook 告警** | Slack / Discord / HTTP · 后台监控额度 \u003e80% 和预算超标 · 连通性测试 · Slack/Discord 格式自动识别 |\n\n### ⌨️ 终端玩家\n\n| | |\n|---|---|\n| ⌨️ **`ccdash-cli.py`** | 五个命令：`status` · `top` · `models` · `budget` · `live` · 彩色输出 · `--server URL` 连接远程 · 零依赖 |\n| 📤 **数据导出** | CSV / JSON 导出，尊重当前数据源和过滤条件 |\n\n### 🎨 不糟糕的 UI\n\n暗色 / 亮色主题平滑切换 · Phosphor 图标 · HUD 渐变发光仪表盘 · 滑动导航指示器 · 页面过渡 · 卡片翻转动画 · 中英双语 · 分析页 **Core / Advanced** 标签页拆分长页面 · 各区块可折叠\n\n---\n\n## 📄 许可证\n\n[MIT](LICENSE) — 随便用。\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=zihenghe04%2FCCDash\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/image?repos=zihenghe04/CCDash\u0026type=date\u0026theme=dark\u0026legend=bottom-right\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/image?repos=zihenghe04/CCDash\u0026type=date\u0026legend=bottom-right\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/image?repos=zihenghe04/CCDash\u0026type=date\u0026legend=bottom-right\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n\n\u003cdiv align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cp\u003e\u003csub\u003eBuilt with ☕ and curiosity\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzihenghe04%2FCCDash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzihenghe04%2FCCDash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzihenghe04%2FCCDash/lists"}