ccgauge 0.3.1 → 1.0.0

package/README.md

@@ -128,7 +128,46 @@ Background mode persists state under `~/.ccgauge/`:
 | `ccgauge restart [options]` | Stop and re-start with new options. |
 | `ccgauge status [--json]` | Inspect the background service. |
 | `ccgauge open` | Open the running dashboard in your browser. |
-| `ccgauge logs [-f] [-n <lines>]` | Print background logs. |
+| `ccgauge logs [-f] [-n <lines>]` | Print background-service log file (the server's stdout). |
+| `ccgauge report [options]` | Print a formatted **usage report** to stdout (one-shot, no server). |
+| `ccgauge mcp` | Start the MCP server on stdio so LLMs can query usage. |
+
+### Report
+
+A no-server one-shot summary that reads the same JSONL files the dashboard does
+and prints a colored, aligned report:
+
+```bash
+ccgauge report                       # last 7d, all sources, top 10 models
+ccgauge report -r 30d -b project     # 30 days, broken down by project
+ccgauge report -s codex -m gpt-5.5   # only codex, only gpt-5.5*
+ccgauge report --json                # JSON output for scripting
+ccgauge report --since 2026-05-01 --until 2026-05-08
+```
+
+Report options:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `-r, --range <range>` | `7d` | `today` / `1d` / `7d` / `30d` / `90d` / `all` |
+| `-s, --source <provider>` | `all` | `claude` / `codex` / `all` |
+| `-b, --by <dim>` | `model` | Breakdown dimension: `model` / `project` / `session` |
+| `-g, --gran <granularity>` | `day` | Trend bucket: `hour` / `day` / `week` / `month` |
+| `-n, --limit <n>` | `10` | Rows in the breakdown table |
+| `--since <date>` | — | Override range start (ISO date or `YYYY-MM-DD`) |
+| `--until <date>` | — | Override range end |
+| `-m, --model <pat>` | — | Filter records whose model contains `<pat>` |
+| `--project <pat>` | — | Filter by project basename / cwd substring |
+| `-j, --json` | off | Machine-readable JSON instead of formatted text |
+| `--no-color` | — | Disable ANSI colors (auto-disabled when piped) |
+| `--no-trend` | — | Skip the trend chart |
+| `--no-breakdown` | — | Skip the breakdown table |
+
+Date-only `--since/--until` values use local calendar-day boundaries, so
+`--until 2026-05-08` includes all of May 8.
+
+> The name `report` (not `logs`) avoids clashing with `ccgauge logs`, which tails
+> the background server's stdout log file.
 
 ### Startup options
 
@@ -143,6 +182,200 @@ Background mode persists state under `~/.ccgauge/`:
 | `--strict-port` | start, restart, root | Fail if the preferred port is busy. |
 | `--log <path>` | start --background, restart | Background log file path. |
 
+## MCP server (let an LLM query your usage)
+
+ccgauge ships an [Model Context Protocol](https://modelcontextprotocol.io/)
+server so any MCP-aware client (Claude Desktop, Cursor, Cline, Codex CLI,
+your own agent…) can talk to your local Claude Code + Codex CLI history
+through structured tools — no copy-paste, no screenshots of the dashboard.
+
+### What you can ask
+
+Once configured, you can ask things like:
+
+- *"How much did I spend on AI coding this week? Break it down by Claude vs Codex."*
+- *"What did I work on yesterday?"*
+- *"Show me my 10 most expensive sessions this month."*
+- *"Which project ate the most tokens in the last 30 days?"*
+- *"Was prompt caching saving me money? How much?"*
+- *"Estimate the cost of 100K input + 20K output on Opus 4.7."*
+- *"How big was my Codex reasoning overhead last week?"*
+- *"Give me a weekly stand-up bullet list of what I shipped."*
+
+The LLM picks the right tool, calls it locally, and answers in plain
+English with real numbers from your machine.
+
+### Capabilities at a glance
+
+| Tool | What it answers |
+| --- | --- |
+| `usage_summary` | Total tokens / cost / cache savings for a date range. Always returns combined totals + per-source breakdown. |
+| `usage_by_time` | Time-series buckets (hour / day / week / month) for trend questions. |
+| `usage_by_model` | Per-model cost share. Each entry tagged with its `source`. |
+| `usage_by_project` | Per-project (cwd) cost share + session counts + last-activity. |
+| `usage_by_session` | Session list with title (= first user message), models, duration, cost. Sort by recent / cost / tokens / duration. |
+| `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. |
+
+| Resource URI | Content |
+| --- | --- |
+| `ccgauge://providers` | Detected providers, data dirs, file/record counts, indexer status. |
+
+**Common arguments** (every analytical tool accepts these):
+
+- `source`: `"claude"` | `"codex"` | `"all"` (default `"all"`). When `"all"`, the response carries combined totals **and** a `bySource: { claude, codex }` breakdown so the LLM can answer either combined or provider-specific questions in a single call.
+- Date range: pass `range` (one of `today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `7d`, `30d`, `90d`, `all`) **or** explicit `from` / `to` (ISO date or full timestamp).
+
+### Configure your MCP client
+
+The exact config-file location depends on your client; the snippet shape
+is the same.
+
+#### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) /
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "npx",
+      "args": ["-y", "ccgauge", "mcp"]
+    }
+  }
+}
+```
+
+If you've installed ccgauge globally (`npm i -g ccgauge`), drop the `npx`:
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 8 ccgauge tools appear in the tool picker.
+
+#### Cursor
+
+`~/.cursor/mcp.json` (project-level: `<project>/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+#### Cline / Continue / generic MCP clients
+
+Anything that follows the standard `{ command, args, env? }` shape works.
+Use either `npx -y ccgauge mcp` (no global install) or `ccgauge mcp`
+(with global install). To override scan paths, pass them via `env`:
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"],
+      "env": {
+        "CCGAUGE_CODEX_DIR": "/custom/codex/path",
+        "CLAUDE_CONFIG_DIR": "/custom/claude/path",
+        "CCGAUGE_STATE_DIR": "/custom/cache/path"
+      }
+    }
+  }
+}
+```
+
+#### Verify it's working
+
+In Claude Desktop, open a new chat and ask:
+
+> *"What ccgauge tools do you have? Run usage_summary for the last 7 days."*
+
+You should see Claude pick `usage_summary`, return a JSON payload with
+`totals` + `bySource`, then summarise it in prose with real numbers.
+
+### Prompt cookbook
+
+Drop these into Claude Desktop / Cursor / Cline as-is. The italics next
+to each one are the tool(s) the LLM will pick — useful if you want to
+debug "why did it answer X".
+
+#### Cost & usage
+
+- *"How much did I spend on AI coding this week, broken down by Claude and Codex?"*
+  → `usage_summary({ range: "7d" })`
+- *"What's my AI coding cost this month? How does that compare to last month?"*
+  → `usage_summary({ range: "this_month" })` + `usage_summary({ range: "last_month" })`
+- *"Show me a daily cost trend for the last 30 days."*
+  → `usage_by_time({ range: "30d", granularity: "day" })`
+- *"Which Claude model did I use the most this month, and how much did it cost?"*
+  → `usage_by_model({ range: "this_month", source: "claude" })`
+- *"Top 5 most expensive sessions this month?"*
+  → `usage_by_session({ range: "this_month", sort: "cost", limit: 5 })`
+
+#### Work content / standup
+
+- *"What did I work on yesterday? Group by project."*
+  → `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`)
+- *"What was my last coding session about?"*
+  → `recent_activity({ limit: 1 })`
+
+#### Caching / efficiency
+
+- *"How many tokens did Anthropic prompt caching save me this month?"*
+  → `usage_summary({ range: "this_month", source: "claude" })` — the response includes `saved_usd`.
+- *"What percentage of my Codex output is reasoning tokens this week?"*
+  → `usage_summary({ range: "7d", source: "codex" })` — response carries `reasoning_tokens` next to `output_tokens`.
+
+#### Budget / planning
+
+- *"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.
+
+#### Cross-source comparisons
+
+- *"Am I getting more value out of Claude or Codex this month, by tokens-per-dollar?"*
+  → `usage_summary({ range: "this_month" })` — both totals are in `bySource`.
+- *"For each provider, which project ate the most tokens last week?"*
+  → `usage_by_project({ range: "last_week" })` (each entry already carries `source`).
+
+### Privacy posture
+
+- **stdio only** in v1 — no network ports, no remote access
+- Reads only the JSONL files you already have on disk; no upstream API calls
+- Absolute paths in error messages are scrubbed (`$HOME` → `~`)
+- The MCP server uses a separate persisted cache (`~/.ccgauge/cache/index-mcp-v2.json`) so it never fights the dashboard for the same on-disk state file
+
+### Troubleshooting
+
+| Symptom | Try |
+| --- | --- |
+| Client doesn't see ccgauge tools | Restart the client after editing the config; check `npx -y ccgauge mcp` runs in your shell |
+| First call is slow | First call after a cold start indexes all JSONL files (~1–3 s for 100 files); subsequent calls are O(1) |
+| "no providers detected" in the resource | The MCP process can't see `~/.claude/projects` / `~/.codex/sessions`; pass `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` via `env` in the MCP config |
+| Want to see what the server is logging | Watch the client's MCP log; ccgauge writes to **stderr** (stdout is reserved for JSON-RPC) |
+
 ## Configuration
 
 ccgauge auto-detects the standard locations:
@@ -203,7 +436,7 @@ This repo is a working Next.js project — run the dashboard against your live d
 git clone https://github.com/chengzuopeng/ccgauge.git
 cd ccgauge
 pnpm install
-pnpm dev               # http://localhost:3737
+pnpm dev               # http://localhost:3738
 ```
 
 Scripts:

package/README.zh-CN.md

@@ -128,7 +128,44 @@ ccgauge stop
 | `ccgauge restart [options]` | 停止再用新参数启动。 |
 | `ccgauge status [--json]` | 查看后台状态。 |
 | `ccgauge open` | 在浏览器打开正在运行的看板。 |
-| `ccgauge logs [-f] [-n <lines>]` | 查看后台日志。 |
+| `ccgauge logs [-f] [-n <lines>]` | 查看后台服务的日志（server stdout）。 |
+| `ccgauge report [options]` | 命令行**用量报告**，直接打到终端（一次性，不起服务）。 |
+| `ccgauge mcp` | 起 MCP 服务（stdio），让 LLM 查你的用量。 |
+
+### 命令行报告（report）
+
+不需要起 server，直接读 JSONL，在终端打印漂亮的彩色对齐报告：
+
+```bash
+ccgauge report                       # 默认：近 7 天 / 所有数据源 / 前 10 个模型
+ccgauge report -r 30d -b project     # 30 天，按项目分组
+ccgauge report -s codex -m gpt-5.5   # 只看 codex 的 gpt-5.5*
+ccgauge report --json                # 输出 JSON 给脚本用
+ccgauge report --since 2026-05-01 --until 2026-05-08
+```
+
+report 参数：
+
+| 参数 | 默认 | 作用 |
+| --- | --- | --- |
+| `-r, --range <range>` | `7d` | `today` / `1d` / `7d` / `30d` / `90d` / `all` |
+| `-s, --source <provider>` | `all` | `claude` / `codex` / `all` |
+| `-b, --by <dim>` | `model` | 分组维度：`model` / `project` / `session` |
+| `-g, --gran <granularity>` | `day` | 趋势粒度：`hour` / `day` / `week` / `month` |
+| `-n, --limit <n>` | `10` | 分组表显示行数 |
+| `--since <date>` | — | 自定义起始日期（覆盖 `--range`，支持 `YYYY-MM-DD`） |
+| `--until <date>` | — | 自定义截止日期 |
+| `-m, --model <pat>` | — | 按模型名子串过滤 |
+| `--project <pat>` | — | 按项目名 / cwd 子串过滤 |
+| `-j, --json` | off | 输出 JSON 而不是格式化文本 |
+| `--no-color` | — | 关掉 ANSI 颜色（管道里会自动关） |
+| `--no-trend` | — | 不画趋势条 |
+| `--no-breakdown` | — | 不打分组表 |
+
+只写日期的 `--since/--until` 会按本地自然日边界处理，所以
+`--until 2026-05-08` 会包含 5 月 8 日整天。
+
+> 用 `report` 而不是 `logs` 是为了避免和 `ccgauge logs`（tail 后台 server 的 stdout）混淆。
 
 ### 启动参数
 
@@ -143,6 +180,196 @@ ccgauge stop
 | `--strict-port` | start, restart, 根命令 | 端口不可用时直接失败。 |
 | `--log <path>` | start --background, restart | 后台日志文件。 |
 
+## MCP 服务（让大模型直接查你的用量）
+
+ccgauge 内置了一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务，
+任何 MCP 客户端（Claude Desktop / Cursor / Cline / Codex CLI / 自建 agent）都能
+通过结构化 tool 调用，直接问大模型关于你本机 Claude Code + Codex CLI 历史的问题——
+不用复制粘贴、不用截图看板。
+
+### 你能问什么
+
+配好之后，可以这样问：
+
+- *"我这周在 AI 编程上花了多少？分别看下 Claude 和 Codex。"*
+- *"我昨天都在做什么？"*
+- *"列一下本月最贵的 10 个会话。"*
+- *"过去 30 天哪个项目最吃 token？"*
+- *"prompt caching 帮我省了多少钱？"*
+- *"如果我在 Opus 4.7 上再跑 100K input + 20K output，要多少钱？"*
+- *"上周 Codex 的 reasoning 开销有多大？"*
+- *"给我一份本周完成事项的 standup bullet list。"*
+
+LLM 会自动选合适的 tool、本地调用、用大白话给你带真实数字的答案。
+
+### 工具一览
+
+| Tool | 回答什么 |
+| --- | --- |
+| `usage_summary` | 一段时间内总 tokens / 花费 / 缓存节省。永远同时返回合并总数 + 按 source 拆分。 |
+| `usage_by_time` | 时间序列（小时/天/周/月），用于趋势 / "什么时候开销爆了"。 |
+| `usage_by_model` | 按模型的成本占比，每条带 source。 |
+| `usage_by_project` | 按项目（cwd）的成本占比 + 会话数 + 最近活跃时间。 |
+| `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 条活跃会话（不限日期）。 |
+
+| Resource URI | 内容 |
+| --- | --- |
+| `ccgauge://providers` | 检测到的 provider、数据目录、文件 / 记录数、indexer 状态。 |
+
+**公共参数**（每个分析类工具都接）：
+
+- `source`：`"claude"` | `"codex"` | `"all"`（默认 `"all"`）。当 `"all"` 时，响应同时带合并总数 **和** `bySource: { claude, codex }` 拆分，让 LLM 一次调用就能回答 "总共多少" 和 "分别多少" 两类问题。
+- 时间范围：传 `range`（`today` / `yesterday` / `this_week` / `last_week` / `this_month` / `last_month` / `7d` / `30d` / `90d` / `all`），**或**显式 `from` / `to`（ISO 日期或完整时间戳）。
+
+### 在 MCP 客户端里配置
+
+不同客户端的配置文件位置不同，但 snippet 形状一样。
+
+#### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）/
+`%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "npx",
+      "args": ["-y", "ccgauge", "mcp"]
+    }
+  }
+}
+```
+
+如果已经全局装了 ccgauge（`npm i -g ccgauge`），可以省掉 `npx`：
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+重启 Claude Desktop，工具选择器里就能看到 ccgauge 的 8 个工具。
+
+#### Cursor
+
+`~/.cursor/mcp.json`（项目级：`<project>/.cursor/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+#### Cline / Continue / 通用 MCP 客户端
+
+任何遵循标准 `{ command, args, env? }` 格式的客户端都能用。`npx -y ccgauge mcp`
+（无需全局装）或 `ccgauge mcp`（已全局装）任选其一。要覆盖扫描路径，通过 `env` 传：
+
+```json
+{
+  "mcpServers": {
+    "ccgauge": {
+      "command": "ccgauge",
+      "args": ["mcp"],
+      "env": {
+        "CCGAUGE_CODEX_DIR": "/custom/codex/path",
+        "CLAUDE_CONFIG_DIR": "/custom/claude/path",
+        "CCGAUGE_STATE_DIR": "/custom/cache/path"
+      }
+    }
+  }
+}
+```
+
+#### 验证是否生效
+
+在 Claude Desktop 新开一个对话，问：
+
+> *"你有哪些 ccgauge 工具？跑一下 usage_summary 看最近 7 天数据。"*
+
+如果配置成功，Claude 会调 `usage_summary`，返回带 `totals` + `bySource` 的 JSON，
+然后用大白话总结成带真实数字的回答。
+
+### Prompt 示例集
+
+直接复制丢进 Claude Desktop / Cursor / Cline 即可。每个 prompt 后面斜体注的是
+LLM 大概率会调的工具——方便你"为什么会这样回答"反查。
+
+#### 用量与花费
+
+- *"我这周用 AI 编程花了多少钱？分开看 Claude 和 Codex。"*
+  → `usage_summary({ range: "7d" })`
+- *"本月 AI 编程花了多少？跟上个月比怎么样？"*
+  → `usage_summary({ range: "this_month" })` + `usage_summary({ range: "last_month" })`
+- *"画一下最近 30 天的每日花费趋势。"*
+  → `usage_by_time({ range: "30d", granularity: "day" })`
+- *"本月用的最多的 Claude 模型是哪个？花了多少？"*
+  → `usage_by_model({ range: "this_month", source: "claude" })`
+- *"本月最贵的 5 个会话是哪些？"*
+  → `usage_by_session({ range: "this_month", sort: "cost", limit: 5 })`
+
+#### 工作内容回顾 / standup
+
+- *"我昨天都做了什么？按项目分一下。"*
+  → `daily_summary({ date: "yesterday" })`
+- *"给我一份周一 standup 用的 bullet list，列我上周完成的事。"*
+  → `weekly_summary({ week_offset: -1 })`
+- *"过去两周我接触最多的 3 个项目是什么？"*
+  → `usage_by_project({ range: "14d", limit: 3 })`（LLM 也可能补一次 `weekly_summary`）
+- *"我最近一次的编码会话是关于什么的？"*
+  → `recent_activity({ limit: 1 })`
+
+#### 缓存 / 效率
+
+- *"本月 Anthropic prompt caching 帮我省了多少 tokens？"*
+  → `usage_summary({ range: "this_month", source: "claude" })`——返回里有 `saved_usd`。
+- *"本周 Codex 的 output 里有多少比例是 reasoning tokens？"*
+  → `usage_summary({ range: "7d", source: "codex" })`——返回里 `reasoning_tokens` 紧挨着 `output_tokens`。
+
+#### 预算 / 规划
+
+- *"按当前消耗速度，本月预计花多少？"*
+  → `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 按公开单价做算术。
+
+#### 跨数据源对比
+
+- *"本月 Claude 和 Codex 哪个性价比更高（按每美元 tokens）？"*
+  → `usage_summary({ range: "this_month" })`——两边数字都在 `bySource` 里。
+- *"上周每个 provider 的最吃 token 项目分别是哪个？"*
+  → `usage_by_project({ range: "last_week" })`（每条 entry 自带 `source`）。
+
+### 隐私边界
+
+- v1 **仅 stdio**——不开网络端口，不能远程访问
+- 只读本机已有的 JSONL 文件，零上游 API 调用
+- 错误信息里的绝对路径会脱敏（`$HOME` → `~`）
+- MCP 用独立的持久化缓存文件（`~/.ccgauge/cache/index-mcp-v2.json`），永远不会和看板抢同一份磁盘状态
+
+### 排障
+
+| 现象 | 建议 |
+| --- | --- |
+| 客户端看不到 ccgauge 工具 | 改完配置重启客户端；终端里手动跑 `npx -y ccgauge mcp` 看是否能起 |
+| 第一次调用比较慢 | 冷启动后第一次会全量索引（100 文件 ~1–3s）；之后都是 O(1) |
+| Resource 显示 "no providers detected" | MCP 进程看不到 `~/.claude/projects` / `~/.codex/sessions`；通过 MCP 配置的 `env` 传 `CLAUDE_CONFIG_DIR` / `CCGAUGE_CODEX_DIR` |
+| 想看 server 在打什么日志 | 看客户端的 MCP 日志；ccgauge 把日志写到 **stderr**（stdout 被 JSON-RPC 占用）|
+
 ## 配置
 
 ccgauge 会自动识别标准路径：
@@ -202,7 +429,7 @@ lib/providers/<name>/
 git clone https://github.com/chengzuopeng/ccgauge.git
 cd ccgauge
 pnpm install
-pnpm dev               # http://localhost:3737
+pnpm dev               # http://localhost:3738
 ```
 
 常用脚本：

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { closeSync, createReadStream, existsSync, openSync } from 'node:fs';
 import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -25,8 +25,15 @@ const DEFAULT_LOG_FILE = join(STATE_DIR, 'ccgauge.log');
 const STATE_VERSION = 1;
 const DEFAULT_PORT = '3737';
 const DEFAULT_HOST = '127.0.0.1';
-const COMMAND_NAMES = new Set(['start', 'stop', 'restart', 'status', 'open', 'logs']);
-const VALUE_OPTIONS = new Set(['-p', '--port', '-H', '--host', '--dir', '--log', '-n', '--lines']);
+const COMMAND_NAMES = new Set([
+  'start', 'stop', 'restart', 'status', 'open', 'logs', 'mcp',
+  'report',
+]);
+const VALUE_OPTIONS = new Set([
+  '-p', '--port', '-H', '--host', '--dir', '--log', '-n', '--lines',
+  '-r', '--range', '-s', '--source', '-b', '--by', '-g', '--gran',
+  '-m', '--model', '--project', '--since', '--until',
+]);
 
 function browserHost(host) {
   if (!host || host === '0.0.0.0' || host === '::' || host === '[::]') return '127.0.0.1';
@@ -132,6 +139,35 @@ program
     await logs(opts);
   });
 
+program
+  .command('mcp')
+  .description('start the MCP server (stdio) so LLMs can query usage data')
+  .action(async () => {
+    await startMcp();
+  });
+
+function addReportOptions(cmd) {
+  return cmd
+    .option('-r, --range <range>', 'today | 1d | 7d | 30d | 90d | all', '7d')
+    .option('-s, --source <provider>', 'claude | codex | all', 'all')
+    .option('-b, --by <dim>', 'breakdown dimension: model | project | session', 'model')
+    .option('-g, --gran <granularity>', 'trend granularity: hour | day | week | month', 'day')
+    .option('-n, --limit <n>', 'rows in breakdown table', '10')
+    .option('--since <date>', 'override range start (ISO date or YYYY-MM-DD)')
+    .option('--until <date>', 'override range end (ISO date or YYYY-MM-DD)')
+    .option('-m, --model <pat>', 'filter by model substring')
+    .option('--project <pat>', 'filter by project (cwd basename match)')
+    .option('-j, --json', 'output JSON instead of formatted text')
+    .option('--no-color', 'disable ANSI colors')
+    .option('--no-trend', 'skip the trend chart')
+    .option('--no-breakdown', 'skip the breakdown table');
+}
+
+addReportOptions(program.command('report').description('print a formatted usage report to stdout'))
+  .action(async (opts) => {
+    await report(opts);
+  });
+
 await program.parseAsync(normalizeArgv(process.argv));
 
 function normalizeArgv(argv) {
@@ -221,6 +257,9 @@ async function startBackground(standaloneEntry, opts) {
     env,
     detached: true,
     stdio: ['ignore', out, err],
+    // Suppress the fleeting console window that Windows pops up for a
+    // detached background child. No-op on macOS/Linux.
+    windowsHide: true,
   });
   child.unref();
   // Once spawn() has dup'd these fds into the child, the parent can release them.
@@ -344,6 +383,87 @@ or run the dev server with
   process.exit(1);
 }
 
+async function report(opts) {
+  const bundle = join(packageRoot, 'dist', 'report', 'index.mjs');
+  if (!existsSync(bundle)) {
+    console.error(`
+[ccgauge] Report bundle not found:
+  ${bundle}
+
+If you installed ccgauge from npm: please reinstall — the published package
+should include the report bundle.
+
+If you are running from source: build it first with
+  $ pnpm build:report
+or run the full build with
+  $ pnpm build
+`);
+    process.exit(1);
+  }
+  const limit = parseInt(String(opts.limit ?? '10'), 10);
+  const reportOpts = {
+    range: String(opts.range ?? '7d'),
+    source: String(opts.source ?? 'all'),
+    by: String(opts.by ?? 'model'),
+    gran: String(opts.gran ?? 'day'),
+    limit: Number.isFinite(limit) && limit > 0 ? limit : 10,
+    since: opts.since ? String(opts.since) : undefined,
+    until: opts.until ? String(opts.until) : undefined,
+    json: Boolean(opts.json),
+    color: opts.color !== false && process.stdout.isTTY,
+    showTrend: opts.trend !== false,
+    showBreakdown: opts.breakdown !== false,
+    model: opts.model ? String(opts.model) : undefined,
+    project: opts.project ? String(opts.project) : undefined,
+  };
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    const out = await mod.runReport(reportOpts);
+    process.stdout.write(out);
+    if (!out.endsWith('\n')) process.stdout.write('\n');
+  } catch (err) {
+    console.error(`[ccgauge] report failed: ${(err && err.message) || err}`);
+    process.exit(1);
+  }
+  // The indexer keeps fs watchers alive, which would block process exit.
+  // For a one-shot report we explicitly exit once stdout is drained.
+  process.stdout.once?.('drain', () => process.exit(0));
+  if (process.stdout.writableLength === 0) process.exit(0);
+}
+
+async function startMcp() {
+  const bundle = join(packageRoot, 'dist', 'mcp', 'server.mjs');
+  if (!existsSync(bundle)) {
+    console.error(`
+[ccgauge-mcp] Build artifact not found:
+  ${bundle}
+
+If you installed ccgauge from npm: please reinstall — the published package should
+include the MCP server bundle.
+
+If you are running from source: build first with
+  $ pnpm build:mcp
+or run the full build with
+  $ pnpm build
+`);
+    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);
+  });
+}
+
 async function resolvePort(opts) {
   const preferred = parseInt(String(opts.port), 10);
   if (!Number.isInteger(preferred) || preferred <= 0 || preferred > 65535) {