ccgauge 1.0.2 → 1.0.4

package/README.md

@@ -38,8 +38,9 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 ## Highlights
 
 ### Cross-provider analytics
-- One dashboard for both **Claude Code** and **OpenAI Codex CLI**
-- Toggle data source from the nav bar; URL persists via `?source=`, last choice cached in cookie
+- One dashboard for both **Claude Code** and **OpenAI Codex CLI**, plus an **All view** that merges the two
+- Toggle data source from the nav bar (Claude · Codex · All), each button rendered with the real provider logo; URL persists via `?source=`, last choice cached in cookie
+- **Worktree-aware Projects** — all worktrees of the same repo collapse into a single project row
 - Built-in **provider adapter layer** (`lib/providers/`) — adding a third CLI (Gemini CLI, Cursor, Aider, …) is one new file plus a single registry line
 
 ### At-a-glance KPIs
@@ -51,7 +52,7 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 - **Sessions** — per-conversation list with model / tokens / cost / duration, plus a message-level timeline
 - **Projects** — per-`cwd` aggregation cards with sparkline and spend share
 - **Models** — side-by-side comparison: cost share, tokens share, cache hit, USD pricing
-- **Usage** — turn-grouped table with expandable tool-call breakdown, CSV export
+- **Usage** — turn-grouped table with expandable tool-call breakdown, CSV export. **Tokens / Conversations** toggle on the trend chart so you can count rows the way the usage table counts them
 
 ### Cost transparency
 - **Cache savings** is its own KPI — quantifies how much Anthropic prompt caching saved you vs. paying full input price
@@ -63,6 +64,17 @@ Everything runs locally as a Next.js app. Your conversation transcripts never le
 - **English / 中文** (cookie + localStorage)
 - Filters: time range (today / 7d / 30d / 90d / all), granularity (hour / day / week / month), model and project multi-select
 
+### CLI report (no server)
+- `ccgauge report` prints a colored, aligned terminal usage report in ~0.2 s from the same JSONL the dashboard reads
+- `--range / --source / --by / --since / --until / --model / --project` filters
+- `--json` for machine-readable output; `--no-color` auto-applied when piped — drops cleanly into shell scripts and CI
+
+### MCP server (for LLMs)
+- `ccgauge mcp` runs a stdio JSON-RPC server so **Claude Desktop / Cursor / Cline** can query your local usage directly
+- Nine MCP tools: `usage_summary`, `usage_by_time`, `usage_by_model`, `usage_by_project`, `usage_by_session`, `daily_summary`, `weekly_summary`, `recent_activity`, `cost_estimator`
+- Reasoning-token breakdown surfaced for the models that emit one
+- Separate named cache (`index-mcp-v2.json`) so MCP runs don't contend with the dashboard
+
 ### Privacy by design
 - 100 % local: read-only access to existing JSONL files, zero outbound network calls
 - Open source, MIT-licensed
@@ -217,6 +229,7 @@ English with real numbers from your machine.
 | `daily_summary` | "What did I do today / yesterday / Monday / on YYYY-MM-DD?" Sessions grouped by project + models + top tool calls. |
 | `weekly_summary` | 7-day roll-up: per-day cost trend, top sessions, top projects, models. `week_offset=-1` for last week. |
 | `recent_activity` | The N most recently active sessions across providers. |
+| `cost_estimator` | Compute the USD cost of a hypothetical request (`{ source, model, input_tokens, output_tokens, cache_* }`). Uses built-in per-1M-token pricing; does NOT consult usage history. |
 
 | Resource URI | Content |
 | --- | --- |
@@ -334,8 +347,8 @@ debug "why did it answer X".
   → `daily_summary({ date: "yesterday" })`
 - *"Generate a Monday stand-up bullet list of what I shipped last week."*
   → `weekly_summary({ week_offset: -1 })`
-- *"Which 3 projects have I touched most in the last 2 weeks?"*
-  → `usage_by_project({ range: "14d", limit: 3 })` (LLM may also pull `weekly_summary`)
+- *"Which 3 projects have I touched most in the last two weeks?"*
+  → `usage_by_project({ from: "2026-05-01", to: "2026-05-15", limit: 3 })` — pass explicit `from`/`to` for any window not covered by the named ranges (`7d` / `30d` / `90d` / `this_week` / `last_week` / …).
 - *"What was my last coding session about?"*
   → `recent_activity({ limit: 1 })`
 
@@ -351,7 +364,7 @@ debug "why did it answer X".
 - *"At my current burn rate, how much will I spend this month?"*
   → `usage_summary({ range: "this_month" })` + `usage_by_time({ range: "this_month", granularity: "day" })` — LLM extrapolates.
 - *"If I run another 200K input + 50K output on Opus 4.7 today, what does that add to my month-to-date cost?"*
-  → `usage_summary({ range: "this_month" })` + LLM does the arithmetic from the published per-1M-token rates.
+  → `cost_estimator({ source: "claude", model: "claude-opus-4-7", input_tokens: 200000, output_tokens: 50000 })` + `usage_summary({ range: "this_month" })` — the estimator returns the dollar cost for the hypothetical request without touching your usage history.
 
 #### Cross-source comparisons
 
@@ -448,6 +461,8 @@ pnpm test              # codex parser smoke test (Node 22+)
 pnpm build             # next build + copy static into .next/standalone
 pnpm start             # run bin/cli.mjs against the standalone build
 pnpm screenshots       # regenerate docs/screenshots/*.png
+pnpm site:dev          # marketing site dev server, http://localhost:4321
+pnpm site:build        # build only the site/ marketing site
 pnpm clean             # rm -rf .next node_modules
 ```
 

package/README.zh-CN.md

@@ -38,8 +38,9 @@ npx ccgauge
 ## 亮点
 
 ### 多 CLI 数据源
-- 一份看板覆盖 **Claude Code** 与 **OpenAI Codex CLI**
-- 顶部一键切换，URL 用 `?source=` 持久化，cookie 记忆上次选择
+- 一份看板覆盖 **Claude Code** 与 **OpenAI Codex CLI**，并提供 **All 视图**把两者合并查看
+- 顶部三档切换（Claude · Codex · All），每个按钮都带真品牌 logo；URL 用 `?source=` 持久化，cookie 记忆上次选择
+- **Worktree 感知的 Projects 合并** —— 同一个 repo 的所有 worktree 自动并到同一个项目行
 - 内置 **Provider 适配层**（`lib/providers/`）—— 增加第三个 CLI（Gemini CLI / Cursor / Aider …）只需一个新文件加注册表一行
 
 ### KPI 一眼看完
@@ -51,7 +52,7 @@ npx ccgauge
 - **会话页** —— 每场对话单独成行（模型 / token / 花费 / 时长），点进去看消息级时间线
 - **项目页** —— 按 `cwd` 聚合成卡片网格，含趋势条与花费占比
 - **模型页** —— 各模型并排对比：成本占比、token 占比、缓存命中、官方单价
-- **用量页** —— 按对话轮次分组的明细表，可展开看每次工具调用，支持 CSV 导出
+- **用量页** —— 按对话轮次分组的明细表，可展开看每次工具调用，支持 CSV 导出。趋势图支持 **Token / 对话数** 切换，让条形图行数和用量表 1:1 对齐
 
 ### 成本透明
 - **缓存节省** 单独成卡 —— 量化 Anthropic prompt caching 实际帮你节省了多少美元
@@ -63,6 +64,17 @@ npx ccgauge
 - **English / 中文** 双语，cookie + localStorage 双向同步
 - 完整筛选：时间区间（今天 / 7 天 / 30 天 / 90 天 / 全部）、粒度（小时 / 天 / 周 / 月）、模型 / 项目 multi-select
 
+### 命令行报告（无 server）
+- `ccgauge report` 读取同一份 JSONL，在 ~0.2 秒内打出彩色对齐的终端报告
+- `--range / --source / --by / --since / --until / --model / --project` 滤波参数
+- `--json` 输出给脚本；`--no-color` 走管道时自动开启 —— 可以直接塞进 shell 和 CI
+
+### MCP 服务（给 LLM 用）
+- `ccgauge mcp` 起一个 stdio JSON-RPC 服务，让 **Claude Desktop / Cursor / Cline** 等 MCP 客户端直接查你本地的 ccgauge 历史
+- 9 个 MCP tool：`usage_summary`、`usage_by_time`、`usage_by_model`、`usage_by_project`、`usage_by_session`、`daily_summary`、`weekly_summary`、`recent_activity`、`cost_estimator`
+- 支持模型有 reasoning token 时单独折算
+- 独立命名缓存（`index-mcp-v2.json`），MCP 进程不会和仪表盘抢同一份磁盘索引
+
 ### 隐私优先
 - 100 % 本地：只读访问已有 JSONL 文件，零外网调用
 - 开源，MIT 协议
@@ -213,7 +225,8 @@ LLM 会自动选合适的 tool、本地调用、用大白话给你带真实数
 | `usage_by_session` | 会话列表，含标题（首条用户消息）/ 模型 / 时长 / 花费。可按 recent / cost / tokens / duration 排序。 |
 | `daily_summary` | "今天 / 昨天 / 周一 / YYYY-MM-DD 我都干了啥？" 按项目分组的会话 + 模型 + top 工具调用。 |
 | `weekly_summary` | 7 天 roll-up：每日花费趋势 + top 会话 + top 项目 + 模型分布。`week_offset=-1` 看上周。 |
-| `recent_activity` | 最近 N 条活跃会话（不限日期）。 |
+| `recent_activity` | 最近 N 条活跃会话（默认最近 30 天，可显式给 `from`/`to`）。 |
+| `cost_estimator` | 计算"假设我用 X 模型发 N 个 token 要花多少钱"。直接读内置 per-1M-token 单价表，不查历史。常用于额度规划 / what-if。 |
 
 | Resource URI | 内容 |
 | --- | --- |
@@ -329,7 +342,7 @@ LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
 - *"给我一份周一 standup 用的 bullet list，列我上周完成的事。"*
   → `weekly_summary({ week_offset: -1 })`
 - *"过去两周我接触最多的 3 个项目是什么？"*
-  → `usage_by_project({ range: "14d", limit: 3 })`（LLM 也可能补一次 `weekly_summary`）
+  → `usage_by_project({ from: "2026-05-01", to: "2026-05-15", limit: 3 })`——非 `7d` / `30d` / `90d` / `this_week` / `last_week` 等命名窗口时，传显式 `from` / `to`。
 - *"我最近一次的编码会话是关于什么的？"*
   → `recent_activity({ limit: 1 })`
 
@@ -345,7 +358,7 @@ LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
 - *"按当前消耗速度，本月预计花多少？"*
   → `usage_summary({ range: "this_month" })` + `usage_by_time({ range: "this_month", granularity: "day" })`——LLM 自己外推。
 - *"如果我今天再在 Opus 4.7 上跑 200K input + 50K output，本月累计要多少？"*
-  → `usage_summary({ range: "this_month" })` + LLM 按公开单价做算术。
+  → `cost_estimator({ source: "claude", model: "claude-opus-4-7", input_tokens: 200000, output_tokens: 50000 })` + `usage_summary({ range: "this_month" })`——estimator 直接按内置单价表返回这笔假设请求的美元成本，不查历史。
 
 #### 跨数据源对比
 
@@ -441,6 +454,8 @@ pnpm test              # codex parser 烟测（Node 22+）
 pnpm build             # next build + 把 static 拷进 .next/standalone
 pnpm start             # 用 bin/cli.mjs 跑 standalone 产物
 pnpm screenshots       # 重新生成 docs/screenshots/*.png
+pnpm site:dev          # 产品官网开发服务，http://localhost:4321
+pnpm site:build        # 只构建 site/ 产品官网
 pnpm clean             # rm -rf .next node_modules
 ```
 
@@ -495,10 +510,11 @@ pnpm publish --access public  # 会自动先跑 pnpm build（prepublishOnly）
 ## 产品官网
 
 产品官网（Astro + Tailwind 自建、中英双语、暗 / 亮主题、独立部署）放在
-[`site/`](./site/) 目录。它跟着主仓库一起在 git 里，但**不会**进 npm 包。
+[`site/`](./site/) 目录。它跟着主仓库一起在 git 里，但**不会**进 npm 包；
+命令和依赖统一由根目录 `package.json` 管理。
 
 ```bash
-cd site && pnpm install && pnpm dev   # http://localhost:4321
+pnpm site:dev   # http://localhost:4321
 ```
 
 构建 / 部署细节见 [`site/README.md`](./site/README.md)。

package/bin/cli.mjs

@@ -142,8 +142,9 @@ program
 program
   .command('mcp')
   .description('start the MCP server (stdio) so LLMs can query usage data')
-  .action(async () => {
-    await startMcp();
+  .option('--check', 'verify the bundle + indexer; print one line per provider and exit')
+  .action(async (opts) => {
+    await startMcp(opts);
   });
 
 function addReportOptions(cmd) {
@@ -438,7 +439,7 @@ or run the full build with
   }
 }
 
-async function startMcp() {
+async function startMcp(opts = {}) {
   const bundle = join(packageRoot, 'dist', 'mcp', 'server.mjs');
   if (!existsSync(bundle)) {
     console.error(`
@@ -455,20 +456,39 @@ or run the full build with
 `);
     process.exit(1);
   }
-  // Hand control to the bundled MCP server. It owns the stdio JSON-RPC
-  // session for the lifetime of the parent (the LLM client) process.
-  const child = spawn(process.execPath, [bundle], {
-    stdio: 'inherit',
-    env: process.env,
-  });
-  const forward = (sig) => () => {
-    if (!child.killed) child.kill(sig);
-  };
-  process.on('SIGINT', forward('SIGINT'));
-  process.on('SIGTERM', forward('SIGTERM'));
-  child.on('exit', (code, sig) => {
-    process.exit(typeof code === 'number' ? code : sig ? 128 : 0);
-  });
+
+  // --check: don't actually run the JSON-RPC server — load the bundle,
+  // boot the indexer, print one line per provider, and exit. Lets users
+  // verify their install without wiring up an MCP client.
+  if (opts.check) {
+    const mod = await import(pathToFileURL(bundle).href);
+    if (typeof mod.printCheck !== 'function') {
+      console.error('[ccgauge-mcp] this bundle was built without --check support');
+      process.exit(1);
+    }
+    const code = await mod.printCheck();
+    process.exit(typeof code === 'number' ? code : 0);
+  }
+
+  // Run the bundled MCP server **in this process** — the bundle exposes a
+  // top-level `runStdioServer()` so we just import + invoke it. Spawning a
+  // second Node process here is wasted memory/latency (LLM clients already
+  // spawn `ccgauge mcp` per conversation), and forwarding signals across
+  // processes is brittle (e.g. SIGHUP isn't covered by the old shim).
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    if (typeof mod.runStdioServer !== 'function') {
+      console.error('[ccgauge-mcp] bundle missing runStdioServer export');
+      process.exit(1);
+    }
+    await mod.runStdioServer();
+    // runStdioServer keeps the loop alive via the stdio transport; if it
+    // ever returns it means the transport closed cleanly.
+    process.exit(0);
+  } catch (err) {
+    console.error('[ccgauge-mcp] failed to start:', err?.message ?? err);
+    process.exit(1);
+  }
 }
 
 async function resolvePort(opts) {
@@ -567,9 +587,18 @@ async function readState() {
   try {
     const raw = await readFile(STATE_FILE, 'utf8');
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
     // Treat unknown / future versions as stale (auto-clean on next stop/start).
     if (parsed.version !== STATE_VERSION) return null;
+    // Type-guard the fields callers actually use — `stop`, `status`, and
+    // `restart` all assume these have the right shape. A hand-edited
+    // state.json with the right `version` but garbage in `pid` could
+    // otherwise crash `safeKill()` or `isProcessRunning()`.
+    if (typeof parsed.pid !== 'number' || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
+      return null;
+    }
+    if (typeof parsed.url !== 'string' || !parsed.url) return null;
+    if (typeof parsed.logFile !== 'string' || !parsed.logFile) return null;
     return parsed;
   } catch {
     return null;