@mai0313/vct 0.12.1 → 0.14.0

package/README.md

@@ -143,6 +143,7 @@ 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)
@@ -234,6 +235,24 @@ The tool automatically scans these directories:
 - `~/.gemini/tmp/<project_hash>/chats/*.jsonl` (Gemini CLI)
 - `~/.local/share/opencode/opencode.db` (OpenCode — SQLite database; honors `$XDG_DATA_HOME`)
 
+### 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:
+
+```
+┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
+│ Claude    1.2M  $3.00  4d │ 5h ▰▰▱▱▱  16%  │ Plan: plus      │
+│ Codex      800K $0.00  6d │    ↻ 4h13m     │ 5h ▰▰▱▱▱  27%   │
+│ ...                       │ 7d ▰▰▰▱▱  28%  │ 7d ▱▱▱▱▱   4%   │
+│                           │ updated 2m ago │ Credits: 0  +2  │
+└───────────────────────────┴────────────────┴─────────────────┘
+```
+
+- **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)`).
+
+Quota panels appear only in the interactive TUI; `--table`, `--text`, and `--json` are unchanged.
+
 ---
 
 ## Analysis Command
@@ -311,6 +330,35 @@ 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,6 +143,7 @@ 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)
@@ -234,6 +235,24 @@ vct usage --json --daily
 - `~/.gemini/tmp/<project_hash>/chats/*.jsonl`（Gemini CLI）
 - `~/.local/share/opencode/opencode.db`（OpenCode，SQLite 数据库；遵循 `$XDG_DATA_HOME`）
 
+### 实时额度面板
+
+在交互式仪表盘底部，左侧是各 provider 统计，右侧是两个实时额度面板：
+
+```
+┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
+│ Claude    1.2M  $3.00  4d │ 5h ▰▰▱▱▱  16%  │ Plan: plus      │
+│ Codex      800K $0.00  6d │    ↻ 4h13m     │ 5h ▰▰▱▱▱  27%   │
+│ ...                       │ 7d ▰▰▰▱▱  28%  │ 7d ▱▱▱▱▱   4%   │
+│                           │ updated 2m ago │ Credits: 0  +2  │
+└───────────────────────────┴────────────────┴─────────────────┘
+```
+
+- **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)`）。
+
+额度面板仅在交互式 TUI 中显示；`--table`、`--text`、`--json` 不受影响。
+
 ---
 
 ## Analysis 命令
@@ -311,6 +330,35 @@ 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,6 +143,7 @@ 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)
@@ -234,6 +235,24 @@ vct usage --json --daily
 - `~/.gemini/tmp/<project_hash>/chats/*.jsonl`（Gemini CLI）
 - `~/.local/share/opencode/opencode.db`（OpenCode，SQLite 資料庫；遵循 `$XDG_DATA_HOME`）
 
+### 即時額度面板
+
+在互動式儀表板底部，左側是各 provider 統計，右側是兩個即時額度面板：
+
+```
+┌ Provider/Tokens/Cost/Days ┬ Claude ────────┬ Codex ──────────┐
+│ Claude    1.2M  $3.00  4d │ 5h ▰▰▱▱▱  16%  │ Plan: plus      │
+│ Codex      800K $0.00  6d │    ↻ 4h13m     │ 5h ▰▰▱▱▱  27%   │
+│ ...                       │ 7d ▰▰▰▱▱  28%  │ 7d ▱▱▱▱▱   4%   │
+│                           │ updated 2m ago │ Credits: 0  +2  │
+└───────────────────────────┴────────────────┴─────────────────┘
+```
+
+- **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)`）。
+
+額度面板僅在互動式 TUI 中顯示；`--table`、`--text`、`--json` 不受影響。
+
 ---
 
 ## Analysis 指令
@@ -311,6 +330,35 @@ 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/vct",
-  "version": "0.12.1",
+  "version": "0.14.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",