@mai0313/vibe-coding-tracker 0.16.0 → 1.0.0

package/README.md

@@ -143,7 +143,6 @@ vct <COMMAND> [OPTIONS]
 Commands:
   analysis    Analyze JSONL conversation files (single file or all sessions)
   usage       Display token usage statistics
-  statusline  Cache Claude Code rate limits from a statusLine hook (stdin JSON)
   version     Display version information
   update      Update to the latest version from GitHub releases
   help        Print this message or the help of the given subcommand(s)
@@ -151,12 +150,12 @@ Commands:
 
 Time range flags (shared by `usage` and `analysis`, mutually exclusive, default `--all`):
 
-| Flag        | Window                            |
-| ----------- | --------------------------------- |
-| `--daily`   | Sessions modified today           |
-| `--weekly`  | Current ISO week (Monday → today) |
-| `--monthly` | Current calendar month            |
-| `--all`     | Every session on disk (default)   |
+| Flag          | Window                            |
+| ------------- | --------------------------------- |
+| `--daily`     | Sessions modified today           |
+| `--weekly`    | Current ISO week (Monday → today) |
+| `--monthly`   | Current calendar month            |
+| `-a`, `--all` | Every session on disk (default)   |
 
 ---
 
@@ -172,6 +171,7 @@ Time range flags (shared by `usage` and `analysis`, mutually exclusive, default
 | `--table`                                      | Static table, no TUI                |
 | `--text`                                       | Plain text, script-friendly         |
 | `--json`                                       | JSON with enriched pricing metadata |
+| `--output <FILE>`                              | Save enriched JSON to a file        |
 | `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above) |
 
 ### Basic Usage
@@ -189,6 +189,9 @@ vct usage --text
 # JSON for data processing (includes cost_usd and matched_model fields)
 vct usage --json
 
+# Save enriched JSON straight to a file
+vct usage --output report.json
+
 # Combine time range with output format
 vct usage --weekly
 vct usage --table --monthly
@@ -232,7 +235,7 @@ The tool automatically scans these directories:
 
 ### Live Quota Panels
 
-At the bottom of the interactive dashboard, the per-provider stats sit on the left and two live quota panels sit on the right:
+`vct usage` shows **live remaining quota for Claude Code and Codex right in the dashboard — with zero setup.** No status-line hook, no config file: vct reads each provider's own OAuth credentials, calls its usage API on a background thread, and keeps the panels current while you work.
 
 ```
 ┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
@@ -243,10 +246,14 @@ At the bottom of the interactive dashboard, the per-provider stats sit on the le
 └───────────────────────────┴────────────────┴─────────────────┘
 ```
 
-- **Claude** — 5-hour and weekly rate-limit usage. Claude Code only exposes these limits through its `statusLine` hook, so wire `vct statusline ingest` into your statusLine (see [Statusline Command](#statusline-command)) for this panel to populate.
-- **Codex** — plan tier, 5-hour and weekly usage, and credit balance. Pulled live from the ChatGPT backend (`wham/usage`) using the token in `~/.codex/auth.json` on a background thread; when unavailable it falls back to the newest `rate_limits` in your Codex session logs (the title shows `(API)` vs `(session)`).
+- **Claude** — 5-hour and weekly usage from the official OAuth usage API (`GET /api/oauth/usage`), read from `~/.claude/.credentials.json`.
+- **Codex** — plan tier, 5-hour and weekly usage, and credit balance from the ChatGPT backend (`wham/usage`) using `~/.codex/auth.json`; falls back to the newest `rate_limits` in your Codex session logs when the API is unavailable (the title shows `Codex` vs `Codex (session)`).
+
+**Automatic token refresh.** For both providers, when a token is near expiry or rejected, vct refreshes it and writes the new token back to the provider's own credential file (in that CLI's exact format), so a token is reused across checks rather than refreshed every time. If a refresh cannot proceed, the panel shows a `run: <provider> auth login` hint instead of breaking.
+
+A panel appears only for a provider whose credentials are present. Quota panels appear only in the interactive TUI; `--table`, `--text`, and `--json` are unchanged.
 
-Quota panels appear only in the interactive TUI; `--table`, `--text`, and `--json` are unchanged.
+> **Platform note:** on macOS, Claude Code stores its OAuth credentials in the system Keychain rather than `~/.claude/.credentials.json`, so the Claude panel is not shown on macOS.
 
 ---
 
@@ -320,35 +327,6 @@ vct analysis --output today.json --daily
 
 ---
 
-## Statusline Command
-
-**Feed Claude Code rate limits into the `usage` dashboard.**
-
-Claude Code only exposes its 5-hour / weekly rate limits through the `statusLine` hook's stdin JSON, so `vct` captures them from there and caches them to `~/.vibe_coding_tracker/claude_rate_limits.json` for the Claude quota panel.
-
-### If you already have a statusLine
-
-Add one backgrounded line to your existing statusLine script. It has zero impact on your current display and is isolated, so a vct error can never disturb the statusLine:
-
-```bash
-printf '%s' "$input" | vct statusline ingest >/dev/null 2>&1 &
-```
-
-### If you do not have a statusLine yet
-
-Point Claude Code's `~/.claude/settings.json` straight at vct, which caches the limits and prints a compact one-line status:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "vct statusline"
-  }
-}
-```
-
----
-
 ## Update Command
 
 **Keep your installation up-to-date automatically.**

package/README.zh-CN.md

@@ -143,7 +143,6 @@ vct <COMMAND> [OPTIONS]
 Commands:
   analysis    Analyze JSONL conversation files (single file or all sessions)
   usage       Display token usage statistics
-  statusline  Cache Claude Code rate limits from a statusLine hook (stdin JSON)
   version     Display version information
   update      Update to the latest version from GitHub releases
   help        Print this message or the help of the given subcommand(s)
@@ -151,12 +150,12 @@ Commands:
 
 时间范围 flag（`usage` 与 `analysis` 共用，互斥，默认 `--all`）：
 
-| Flag        | 范围                         |
-| ----------- | ---------------------------- |
-| `--daily`   | 今天更新过的 session         |
-| `--weekly`  | 本 ISO 周（周一 → 今天）     |
-| `--monthly` | 本自然月                     |
-| `--all`     | 磁盘上所有 session（默认值） |
+| Flag          | 范围                         |
+| ------------- | ---------------------------- |
+| `--daily`     | 今天更新过的 session         |
+| `--weekly`    | 本 ISO 周（周一 → 今天）     |
+| `--monthly`   | 本自然月                     |
+| `-a`, `--all` | 磁盘上所有 session（默认值） |
 
 ---
 
@@ -172,6 +171,7 @@ Commands:
 | `--table`                                      | 静态表格，不启动 TUI       |
 | `--text`                                       | 纯文本，适合脚本处理       |
 | `--json`                                       | JSON 输出，附带定价信息    |
+| `--output <FILE>`                              | 将富化 JSON 保存到文件     |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格） |
 
 ### 基本用法
@@ -189,6 +189,9 @@ vct usage --text
 # JSON 输出，包含 cost_usd 与 matched_model 字段
 vct usage --json
 
+# 直接把富化 JSON 保存到文件
+vct usage --output report.json
+
 # 时间范围与输出格式可自由组合
 vct usage --weekly
 vct usage --table --monthly
@@ -232,7 +235,7 @@ vct usage --json --daily
 
 ### 实时额度面板
 
-在交互式仪表盘底部，左侧是各 provider 统计，右侧是两个实时额度面板：
+`vct usage` 会**在仪表盘中直接显示 Claude Code 与 Codex 的实时剩余额度——完全零配置。** 不需要 status-line hook，也不需要配置文件：vct 会读取各 provider 自己的 OAuth 凭证，在后台线程调用其用量 API，并在你工作时保持面板持续更新。
 
 ```
 ┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
@@ -243,10 +246,14 @@ vct usage --json --daily
 └───────────────────────────┴────────────────┴─────────────────┘
 ```
 
-- **Claude** — 5 小时和每周的额度用量。Claude Code 仅通过 `statusLine` hook 暴露这些额度，需将 `vct statusline ingest` 接入你的 statusLine（见 [Statusline 命令](#statusline-%E5%91%BD%E4%BB%A4)）此面板才会有数据。
-- **Codex** — 套餐类型、5 小时和每周用量、额度余额。后台线程使用 `~/.codex/auth.json` 中的 token 从 ChatGPT 后端（`wham/usage`）实时拉取；不可用时回退到 Codex 会话日志中最新的 `rate_limits`（标题显示 `(API)` 或 `(session)`）。
+- **Claude** — 5 小时和每周用量，来自官方 OAuth 用量 API（`GET /api/oauth/usage`），从 `~/.claude/.credentials.json` 读取。
+- **Codex** — 套餐类型、5 小时和每周用量以及额度余额，使用 `~/.codex/auth.json` 从 ChatGPT 后端（`wham/usage`）获取；API 不可用时回退到 Codex 会话日志中最新的 `rate_limits`（标题显示 `Codex` 或 `Codex (session)`）。
+
+**自动刷新 token。** 对这两个 provider，当 token 接近过期或被拒绝时，vct 会刷新它并把新 token 写回该 provider 自己的凭证文件（采用该 CLI 的原始格式），因此 token 会在多次检查之间复用，而不是每次都重新刷新。如果刷新失败，面板会显示 `run: <provider> auth login` 提示，而不会直接中断。
+
+只有在某个 provider 的凭证存在时，才会显示对应的面板。额度面板仅在交互式 TUI 中显示；`--table`、`--text`、`--json` 不受影响。
 
-额度面板仅在交互式 TUI 中显示；`--table`、`--text`、`--json` 不受影响。
+> **平台说明：** 在 macOS 上，Claude Code 会把 OAuth 凭证保存在系统 Keychain 中，而不是 `~/.claude/.credentials.json`，因此在 macOS 上不会显示 Claude 面板。
 
 ---
 
@@ -320,35 +327,6 @@ vct analysis --output today.json --daily
 
 ---
 
-## Statusline 命令
-
-**将 Claude Code 的额度信息接入 `usage` 仪表盘。**
-
-Claude Code 仅通过 `statusLine` hook 的 stdin JSON 暴露其 5 小时 / 每周额度，因此 `vct` 从那里捕获并缓存到 `~/.vibe_coding_tracker/claude_rate_limits.json`，供 Claude 额度面板读取。
-
-### 如果你已有 statusLine
-
-在现有 statusLine 脚本中加一行后台命令。它对当前显示零影响，且相互隔离，vct 出错也绝不会干扰 statusLine：
-
-```bash
-printf '%s' "$input" | vct statusline ingest >/dev/null 2>&1 &
-```
-
-### 如果你还没有 statusLine
-
-让 Claude Code 的 `~/.claude/settings.json` 直接指向 vct，它会缓存额度并打印一行简洁状态：
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "vct statusline"
-  }
-}
-```
-
----
-
 ## Update 命令
 
 **自动保持安装版本为最新。**

package/README.zh-TW.md

@@ -143,7 +143,6 @@ vct <COMMAND> [OPTIONS]
 Commands:
   analysis    Analyze JSONL conversation files (single file or all sessions)
   usage       Display token usage statistics
-  statusline  Cache Claude Code rate limits from a statusLine hook (stdin JSON)
   version     Display version information
   update      Update to the latest version from GitHub releases
   help        Print this message or the help of the given subcommand(s)
@@ -151,12 +150,12 @@ Commands:
 
 時間範圍 flag（`usage` 與 `analysis` 共用，互斥，預設 `--all`）：
 
-| Flag        | 範圍                       |
-| ----------- | -------------------------- |
-| `--daily`   | 今天更新過的 session       |
-| `--weekly`  | 本 ISO 週（週一 → 今天）   |
-| `--monthly` | 本自然月                   |
-| `--all`     | 磁碟上所有 session（預設） |
+| Flag          | 範圍                       |
+| ------------- | -------------------------- |
+| `--daily`     | 今天更新過的 session       |
+| `--weekly`    | 本 ISO 週（週一 → 今天）   |
+| `--monthly`   | 本自然月                   |
+| `-a`, `--all` | 磁碟上所有 session（預設） |
 
 ---
 
@@ -172,6 +171,7 @@ Commands:
 | `--table`                                      | 靜態表格，不啟動 TUI         |
 | `--text`                                       | 純文字，適合腳本處理         |
 | `--json`                                       | JSON 輸出，附帶 pricing 資訊 |
+| `--output <FILE>`                              | 將富化 JSON 存成檔案         |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格）   |
 
 ### 基本用法
@@ -189,6 +189,9 @@ vct usage --text
 # JSON 輸出，包含 cost_usd 與 matched_model 欄位
 vct usage --json
 
+# 直接把富化 JSON 存成檔案
+vct usage --output report.json
+
 # 時間範圍與輸出格式可自由組合
 vct usage --weekly
 vct usage --table --monthly
@@ -232,7 +235,7 @@ vct usage --json --daily
 
 ### 即時額度面板
 
-在互動式儀表板底部，左側是各 provider 統計，右側是兩個即時額度面板：
+`vct usage` 會**在儀表板中直接顯示 Claude Code 與 Codex 的即時剩餘額度——完全零設定。** 不需要 status-line hook，也不需要設定檔：vct 會讀取各 provider 自己的 OAuth 憑證，在背景執行緒呼叫其用量 API，並在你工作時讓面板保持最新。
 
 ```
 ┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
@@ -243,10 +246,14 @@ vct usage --json --daily
 └───────────────────────────┴────────────────┴─────────────────┘
 ```
 
-- **Claude** — 5 小時和每週的額度用量。Claude Code 僅透過 `statusLine` hook 暴露這些額度，需將 `vct statusline ingest` 接入你的 statusLine（見 [Statusline 指令](#statusline-%E6%8C%87%E4%BB%A4)）此面板才會有資料。
-- **Codex** — 方案類型、5 小時和每週用量、額度餘額。背景執行緒使用 `~/.codex/auth.json` 中的 token 從 ChatGPT 後端（`wham/usage`）即時拉取；不可用時回退到 Codex 工作階段紀錄中最新的 `rate_limits`（標題顯示 `(API)` 或 `(session)`）。
+- **Claude** — 5 小時和每週用量，來自官方 OAuth 用量 API（`GET /api/oauth/usage`），從 `~/.claude/.credentials.json` 讀取。
+- **Codex** — 方案類型、5 小時和每週用量以及額度餘額，使用 `~/.codex/auth.json` 從 ChatGPT 後端（`wham/usage`）取得；API 無法使用時回退到 Codex 工作階段紀錄中最新的 `rate_limits`（標題顯示 `Codex` 或 `Codex (session)`）。
+
+**自動刷新 token。** 對這兩個 provider，當 token 接近過期或被拒絕時，vct 會刷新它並把新的 token 寫回該 provider 自己的憑證檔案（採用該 CLI 的原始格式），因此 token 會在多次檢查之間重複使用，而不是每次都重新刷新。如果刷新失敗，面板會顯示 `run: <provider> auth login` 提示，而不會直接中斷。
+
+只有在某個 provider 的憑證存在時，才會顯示對應的面板。額度面板僅在互動式 TUI 中顯示；`--table`、`--text`、`--json` 不受影響。
 
-額度面板僅在互動式 TUI 中顯示；`--table`、`--text`、`--json` 不受影響。
+> **平台說明：** 在 macOS 上，Claude Code 會把 OAuth 憑證儲存在系統 Keychain 中，而不是 `~/.claude/.credentials.json`，因此在 macOS 上不會顯示 Claude 面板。
 
 ---
 
@@ -320,35 +327,6 @@ vct analysis --output today.json --daily
 
 ---
 
-## Statusline 指令
-
-**將 Claude Code 的額度資訊接入 `usage` 儀表板。**
-
-Claude Code 僅透過 `statusLine` hook 的 stdin JSON 暴露其 5 小時 / 每週額度，因此 `vct` 從那裡擷取並快取到 `~/.vibe_coding_tracker/claude_rate_limits.json`，供 Claude 額度面板讀取。
-
-### 如果你已有 statusLine
-
-在現有 statusLine 腳本中加一行背景指令。它對目前顯示零影響，且相互隔離，vct 出錯也絕不會干擾 statusLine：
-
-```bash
-printf '%s' "$input" | vct statusline ingest >/dev/null 2>&1 &
-```
-
-### 如果你還沒有 statusLine
-
-讓 Claude Code 的 `~/.claude/settings.json` 直接指向 vct，它會快取額度並印出一行精簡狀態：
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "vct statusline"
-  }
-}
-```
-
----
-
 ## Update 指令
 
 **自動保持安裝為最新版本。**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mai0313/vibe-coding-tracker",
-  "version": "0.16.0",
+  "version": "1.0.0",
   "description": "Vibe Coding Tracker - AI coding assistant telemetry/usage parser, aggregate JSONL events into CodeAnalysis results",
   "author": "Wei Lee <mai@mai0313.com>",
   "license": "MIT",