{"id":51035181,"url":"https://github.com/chengzuopeng/ccgauge","last_synced_at":"2026-06-22T05:00:53.461Z","repository":{"id":355430554,"uuid":"1228062603","full_name":"chengzuopeng/ccgauge","owner":"chengzuopeng","description":"Claude Code Dashboard — local web UI for Claude Code token usage and cost. npx ccgauge","archived":false,"fork":false,"pushed_at":"2026-06-19T12:32:44.000Z","size":12749,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T14:25:04.214Z","etag":null,"topics":["anthropic","claude","claude-code","cli","cost-tracker","dashboard","nextjs","usage-tracker"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ccgauge","language":"TypeScript","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/chengzuopeng.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-03T14:45:22.000Z","updated_at":"2026-06-19T12:32:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chengzuopeng/ccgauge","commit_stats":null,"previous_names":["chengzuopeng/ccdsb","chengzuopeng/ccgauge"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/chengzuopeng/ccgauge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chengzuopeng%2Fccgauge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chengzuopeng%2Fccgauge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chengzuopeng%2Fccgauge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chengzuopeng%2Fccgauge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chengzuopeng","download_url":"https://codeload.github.com/chengzuopeng/ccgauge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chengzuopeng%2Fccgauge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34635038,"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-06-22T02:00:06.391Z","response_time":106,"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":["anthropic","claude","claude-code","cli","cost-tracker","dashboard","nextjs","usage-tracker"],"created_at":"2026-06-22T05:00:48.668Z","updated_at":"2026-06-22T05:00:53.453Z","avatar_url":"https://github.com/chengzuopeng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ccgauge\n\n**Tokens, cost, and cache-savings dashboard for Claude Code + Codex CLI.**\nOne command. Zero install. Everything stays on your laptop.\n\n[![npm](https://img.shields.io/npm/v/ccgauge?color=4F46E5\u0026style=flat-square)](https://www.npmjs.com/package/ccgauge)\n[![license](https://img.shields.io/npm/l/ccgauge?color=4F46E5\u0026style=flat-square)](https://github.com/chengzuopeng/ccgauge/blob/main/LICENSE)\n[![node](https://img.shields.io/node/v/ccgauge?color=4F46E5\u0026style=flat-square)](#)\n\n**🌐 [chengzuopeng.github.io/ccgauge](https://chengzuopeng.github.io/ccgauge)**\n\n[English](https://github.com/chengzuopeng/ccgauge/blob/main/README.md) · [简体中文](https://github.com/chengzuopeng/ccgauge/blob/main/README.zh-CN.md)\n\n\u003c/div\u003e\n\n```bash\nnpx ccgauge\n```\n\nccgauge reads the JSONL session files Claude Code and Codex CLI already store on your disk, computes day / project / model / session breakdowns plus **dollar-equivalent cost**, and opens a unified browser dashboard. Switch providers with one click. Ask your LLM about your usage via the built-in MCP server. Or skip the browser entirely and run `ccgauge report -d` for a rich terminal dashboard.\n\n**No login. No telemetry. No outbound network calls.**\n\n![Overview — English / Dark](https://raw.githubusercontent.com/chengzuopeng/ccgauge/main/docs/screenshots/overview-en-dark.png)\n\n---\n\n## Why ccgauge stands out\n\n- 🪟 **Two CLIs, one dashboard.** Claude Code and Codex CLI side by side — switch sources from the nav bar, or merge them in the All view. No other dashboard covers both.\n- 💰 **Cache savings as a first-class KPI.** See exactly how many dollars Anthropic prompt caching saved you this week. Not a footnote — a card on the overview.\n- ⏱️ **Live 5-hour block.** Countdown, progress bar, projected total cost — know when the rate-limit window rolls over *before* you hit it.\n- 🤖 **MCP-native.** Plug into Claude Desktop / Cursor / Cline and ask *\"What did I work on yesterday, by project?\"* in plain English. Real numbers, no screenshots, no copy-paste.\n- 🔒 **100% local \u0026 private.** Reads JSONL files you already have. Zero outbound calls. MIT licensed. Your transcripts never leave the machine.\n- 🪜 **Worktree-aware projects.** All worktrees of the same repo collapse into one project row — the way you actually think about your work.\n\n## What's new in v1.1.0\n\n- **`ccgauge report --dashboard` / `-d`** — rich one-screen TUI: KPI tiles, stacked-bar trend chart, breakdown tables, day×hour heatmap. Perfect for SSH / tmux / a quick check without leaving the terminal. Falls back to plain text below 80 columns.\n- **Custom date range** on `/usage` — proper calendar picker (react-day-picker), brand-themed, follows your language toggle. `?range=custom\u0026from=...\u0026to=...` URL contract.\n- **Marketing site at root URLs** — English at `/cli/` / `/features/` / `/mcp/`, Chinese under `/zh/...`. Old `/en/*` paths still resolve via static redirects.\n\nSee [CHANGELOG.md](https://github.com/chengzuopeng/ccgauge/blob/main/CHANGELOG.md) for the full release notes.\n\n## Features\n\n### Dashboard (browser)\n- **Overview** — 6 KPI cards (tokens today / cost / cache hit / top model / active sessions / live 5h block) with day-over-day delta on each.\n- **Usage** — turn-grouped table with expandable tool calls, CSV export, **Tokens / Conversations** chart toggle. Filters: range (incl. **custom date**), granularity, model + project multi-select.\n- **Sessions** — per-conversation list with model / tokens / cost / duration; click in for the message-level timeline.\n- **Projects** — per-`cwd` aggregation with sparkline and spend share; worktrees auto-collapsed.\n- **Models** — side-by-side cost share, token share, cache hit, official per-1M pricing.\n- **Light / Dark / System** themes (no flash), **EN / 中文**, cookie + localStorage synced.\n\n### CLI report (terminal)\n- `ccgauge report` — colored, aligned text report in ~0.2s, ideal for CI.\n- `ccgauge report -d` — rich TUI: KPI tiles, stacked vertical-bar trend, double-column breakdown tables, 7×24 activity heatmap.\n- Filters: `--range / --source / --by / --since / --until / --model / --project`.\n- `--json` for scripts; `--no-color` auto-detected when piped.\n\n### MCP server (LLM access)\n- `ccgauge mcp` — stdio JSON-RPC server. Plug into Claude Desktop / Cursor / Cline / your own agent.\n- **9 tools** for usage summary, time-series, per-model / project / session breakdowns, daily / weekly summaries, recent activity, hypothetical cost estimator.\n- Reasoning-token breakdown for models that emit one.\n- Separate cache (`index-mcp-v2.json`) so MCP and the dashboard never fight.\n\n### Cost transparency\n- **Cache savings** quantified as a dollar figure on the overview.\n- Codex cost shown as **OpenAI API equivalent** so subscription users can compare value against pay-as-you-go.\n- Built-in pricing: 12 Claude models + gpt-5 family + o-series; unknown models fall back to family-latest.\n\n### Privacy by design\n- 100% local: read-only access to JSONL files, zero outbound calls.\n- Open source, MIT licensed.\n- Background mode for an always-on service with `start / stop / restart / status / open / logs` lifecycle commands.\n\n## Quick start\n\n```bash\nnpx ccgauge                              # zero-install one-shot\nnpm i -g ccgauge \u0026\u0026 ccgauge              # or install globally\n```\n\nDashboard opens at [http://localhost:3737](http://localhost:3737). If the port is busy, ccgauge picks the next free one. `Ctrl+C` to stop.\n\n**Requirements:** Node.js 20+. macOS / Linux / Windows.\n\n## CLI\n\n### Commands\n\n| Command | Purpose |\n| --- | --- |\n| `ccgauge`, `ccgauge start` | Start dashboard server in foreground. |\n| `ccgauge start --background` | Start a detached background service. |\n| `ccgauge stop [--force]` | Stop the background service. |\n| `ccgauge restart [options]` | Stop and re-start with new options. |\n| `ccgauge status [--json]` | Inspect background service. Exits **3** (systemd-style \"not running\") when nothing is up. |\n| `ccgauge open` | Open the running dashboard in your browser. |\n| `ccgauge logs [-f] [-n N]` | Tail the background-service log. |\n| `ccgauge report [options]` | One-shot text or TUI report (no server). |\n| `ccgauge mcp` | Start the MCP server on stdio for LLM access. |\n| `ccgauge doctor` | One-screen diagnostic — paste into bug reports. |\n\n### Startup options\n\n| Option | Default | Purpose |\n| --- | --- | --- |\n| `-p, --port \u003cport\u003e` | `3737` | Preferred port. Falls back if busy unless `--strict-port`. |\n| `-H, --host \u003chost\u003e` | `127.0.0.1` | Bind host. |\n| `--no-open` | — | Skip auto-open in foreground. |\n| `-b, --background` | — | Run as detached background service. |\n| `-q, --quiet` | — | Silence Next.js output. |\n| `--dir \u003cpath\u003e` | — | Add `\u003cpath\u003e/projects` as an extra Claude source. |\n| `--strict-port` | — | Fail if the preferred port is busy. |\n\n### Background mode\n\n```bash\nccgauge start -b                  # detached service, state in ~/.ccgauge/\nccgauge status                    # PID / URL / uptime\nccgauge logs --follow             # tail the service log\nccgauge stop                      # graceful stop (or --force)\n```\n\n`~/.ccgauge/` holds `state.json` (PID, URL, start time, log path) and `ccgauge.log`. Override with `CCGAUGE_STATE_DIR=/tmp/profile` for isolated profiles.\n\n### `ccgauge report`\n\n```bash\nccgauge report                       # last 7d, all sources, text\nccgauge report -d                    # rich TUI dashboard\nccgauge report -r 30d -b project     # 30 days, broken down by project\nccgauge report -s codex -m gpt-5     # only Codex, only gpt-5 models\nccgauge report --json                # machine-readable\n```\n\n| Option | Default | Purpose |\n| --- | --- | --- |\n| `-r, --range \u003crange\u003e` | `7d` | `today` / `1d` / `7d` / `30d` / `90d` / `all` |\n| `-s, --source \u003cprovider\u003e` | `all` | `claude` / `codex` / `all` |\n| `-b, --by \u003cdim\u003e` | `model` | Breakdown: `model` / `project` / `session` |\n| `-g, --gran \u003cgran\u003e` | `day` | Trend bucket: `hour` / `day` / `week` / `month` |\n| `-n, --limit \u003cn\u003e` | `10` | Rows in the breakdown table |\n| `--since` / `--until` | — | ISO date range override (`YYYY-MM-DD`, local day-aligned) |\n| `-m, --model \u003cpat\u003e` | — | Filter records whose model contains `\u003cpat\u003e` |\n| `--project \u003cpat\u003e` | — | Filter by project basename / cwd substring |\n| `-d, --dashboard` | — | Rich one-screen TUI layout (KPI tiles + stacked trend + breakdown + heatmap) |\n| `--width \u003cn\u003e` | tty cols | Force output width — useful for screenshots / CI |\n| `--no-banner / --compact` | — | Dashboard trimmings (skip banner / skip trend chart) |\n| `-j, --json` | — | JSON output |\n| `--no-color` | auto | Disable ANSI colors (auto when piped) |\n| `--no-trend / --no-breakdown` | — | Skip sections (text mode only) |\n\n## MCP — let an LLM query your usage\n\nConfigure once, then ask in plain English. Snippet shape is the same across clients (Claude Desktop / Cursor / Cline / Continue):\n\n```json\n{\n  \"mcpServers\": {\n    \"ccgauge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ccgauge\", \"mcp\"]\n    }\n  }\n}\n```\n\nRestart your client. Try: *\"What ccgauge tools do you have? Run usage_summary for last 7 days.\"*\n\nIf you've installed ccgauge globally, drop the `npx` and use `\"command\": \"ccgauge\"`. To override scan paths, pass `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` via the `env` field.\n\n### Tools\n\n| Tool | What it answers |\n| --- | --- |\n| `usage_summary` | Total tokens / cost / cache savings for a date range. Always returns combined totals + per-source breakdown. |\n| `usage_by_time` | Time-series buckets (hour / day / week / month) for trend questions. |\n| `usage_by_model` | Per-model cost share. Each entry tagged with its `source`. |\n| `usage_by_project` | Per-project (`cwd`) cost share + session counts + last activity. |\n| `usage_by_session` | Session list sorted by recent / cost / tokens / duration. |\n| `daily_summary` | *\"What did I do today / yesterday / on YYYY-MM-DD?\"* — sessions grouped by project + top tool calls. |\n| `weekly_summary` | 7-day roll-up: daily cost trend, top sessions / projects, models. `week_offset=-1` for last week. |\n| `recent_activity` | N most recently active sessions across providers. |\n| `cost_estimator` | USD cost of a hypothetical request. Uses built-in pricing tables; does NOT consult history. |\n\nEvery analytical tool accepts `source` (`claude` / `codex` / `all`) and either `range` (`today` / `7d` / `30d` / `this_week` / `last_week` / `this_month` / `last_month` / `all`) or explicit `from` / `to`. The `all` view always returns combined totals + a `bySource: { claude, codex }` breakdown — one call, two answers.\n\n### Prompt examples\n\n- *\"How much did I spend on AI coding this week, broken down by Claude vs Codex?\"*\n- *\"Show me a daily cost trend for the last 30 days.\"*\n- *\"Top 5 most expensive sessions this month?\"*\n- *\"What did I work on yesterday? Group by project.\"*\n- *\"Generate a Monday standup bullet list of what I shipped last week.\"*\n- *\"At my current burn rate, how much will I spend this month? If I run another 200K input + 50K output on Opus 4.7 today, what does that add?\"*\n\n### Privacy \u0026 troubleshooting\n\n- **stdio only** in v1 — no network ports.\n- Reads only existing JSONL files; absolute paths in error messages are scrubbed (`$HOME` → `~`).\n\n| Symptom | Try |\n| --- | --- |\n| Client doesn't see tools | Restart client after editing config; run `ccgauge mcp --check` or `ccgauge doctor` |\n| First call is slow | Cold start indexes all JSONL (~1–3s for 100 files); subsequent calls are O(1) |\n| \"no providers detected\" | Pass `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` via `env` in MCP config |\n| Want to see server logs | Watch client's MCP log — ccgauge writes to **stderr** (stdout is reserved for JSON-RPC) |\n\n## Configuration\n\nccgauge auto-detects standard locations:\n\n| Provider | Default sources |\n| --- | --- |\n| Claude Code | `~/.claude/projects`, `~/.config/claude/projects` |\n| OpenAI Codex CLI | `~/.codex/sessions`, `~/.codex/archived_sessions` |\n\nOverride / extend via environment variables:\n\n| Variable | Effect |\n| --- | --- |\n| `CLAUDE_CONFIG_DIR` | Add `\u003cdir\u003e/projects` as a Claude data source |\n| `CCGAUGE_CONFIG_DIR` | Same as above (legacy ccgauge name) |\n| `CCGAUGE_CODEX_DIR` | Add an extra Codex sessions directory |\n| `CODEX_HOME` | Add `\u003cdir\u003e/sessions` and `\u003cdir\u003e/archived_sessions` |\n| `CCGAUGE_STATE_DIR` | Override background service state / log directory |\n\n## Develop\n\n```bash\ngit clone https://github.com/chengzuopeng/ccgauge.git\ncd ccgauge\npnpm install\npnpm dev               # http://localhost:3738\npnpm typecheck         # tsc --noEmit\npnpm test              # parser smoke tests (Node 22+)\npnpm build             # next build + bundle MCP + bundle CLI report\n```\n\nThe repo is a working Next.js project — hot-reload against your live data while iterating. Adding a third provider (Gemini CLI, Cursor, Aider, …) is one new directory in [`lib/providers/\u003cname\u003e/`](https://github.com/chengzuopeng/ccgauge/tree/main/lib/providers) plus one registry line — `scan.ts`, the aggregator, the pricing module, and every page need no changes.\n\nThe marketing site lives in [`site/`](https://github.com/chengzuopeng/ccgauge/tree/main/site) (Astro + Tailwind) and ships separately from the npm package — run with `pnpm site:dev`.\n\n## Troubleshooting\n\n\u003e First stop for any \"why doesn't this work\" question: **`ccgauge doctor`**. One screen, version + env + build artifacts + service state + per-provider scan. Paste into bug reports.\n\n| Symptom | Try |\n| --- | --- |\n| Port keeps drifting | `ccgauge --strict-port --port 3737` |\n| Stale background service | `ccgauge status`, then `ccgauge stop --force` |\n| Background didn't start | `ccgauge logs` reads `~/.ccgauge/ccgauge.log` |\n| No data shown for Codex | Ensure `~/.codex/sessions` exists; check the **Settings** page for detected paths |\n| Want to bypass auto-open | `ccgauge --no-open` |\n\n## FAQ\n\n**Does ccgauge upload anything?**\nNo. Runs entirely on your machine; reads JSONL files Claude Code and Codex CLI already store locally; zero outbound calls; no API credentials needed.\n\n**How is this different from [ccusage](https://github.com/ryoppippi/ccusage)?**\nccusage is a CLI that prints usage tables. ccgauge is a polished web dashboard with charts, per-session drill-down, a 5h rate-limit countdown, project / model breakdowns — and **also covers OpenAI Codex CLI** out of the box. Plus an MCP server so your LLM can answer questions about your usage in plain English, and an in-terminal TUI dashboard (`ccgauge report -d`) for when the browser isn't an option.\n\n**Does it work for Claude Pro / Max / Team / Codex Plus subscribers?**\nYes. The dashboard always reports the **API-equivalent dollar value** of your usage — useful to gauge *\"how much would this cost on PAYG?\"*. Subscription plans bill differently; ccgauge is not your invoice.\n\n**Which models are supported?**\nAll `claude-*` (Opus / Sonnet / Haiku, 3.x and 4.x) and the gpt-5 family + gpt-4.1 family + o-series (o3, o4-mini). Unknown models fall back to family-latest pricing automatically.\n\n## License\n\nMIT — see [LICENSE](https://github.com/chengzuopeng/ccgauge/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchengzuopeng%2Fccgauge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchengzuopeng%2Fccgauge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchengzuopeng%2Fccgauge/lists"}