@mai0313/vct 1.12.0 → 2.1.0

package/README.md

@@ -19,7 +19,7 @@
 
 </div>
 
-**Track your AI coding costs in real-time.** Vibe Coding Tracker is a lightweight, high-performance CLI tool built in Rust that monitors and analyzes your Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, and Hermes usage — with detailed cost breakdowns, token statistics, and code operation insights, all while keeping the memory footprint minimal.
+**Track your AI coding costs in real-time.** Vibe Coding Tracker is a lightweight, high-performance CLI tool built in Rust that monitors and analyzes your Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, Hermes, and Grok usage — with detailed cost breakdowns, token statistics, and code operation insights, all while keeping the memory footprint minimal.
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
 
@@ -41,14 +41,14 @@ Built with Rust for minimal resource footprint. The interactive TUI dashboard ty
 
 Choose your preferred view:
 
-- **Interactive Dashboard**: Auto-refreshing terminal UI with live updates, scrollable model list (arrow keys), and compact K/M/B number formatting
+- **Interactive Dashboard**: Auto-refreshing terminal UI with live updates, scrollable model list (arrow keys), a live per-process CPU/memory readout, and compact K/M/B number formatting
 - **Static Reports**: Professional tables for documentation
 - **Script-Friendly**: Plain text and JSON for automation
 - **Full Precision**: Export exact costs for accounting
 
 ### Zero Configuration
 
-Automatically detects and processes logs from Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, and Hermes. No setup required — just run and analyze. A `~/.vct/config.toml` is created with sensible defaults on first run if you ever want to tweak behavior (see [Configuration](#configuration)).
+Automatically detects and processes logs from Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, Hermes, and Grok. No setup required — just run and analyze. A `~/.vct/config.toml` is created with sensible defaults on first run if you ever want to tweak behavior (see [Configuration](#configuration)).
 
 ### Rich Insights
 
@@ -62,15 +62,15 @@ Automatically detects and processes logs from Claude Code, Codex, Copilot, Gemin
 
 ## Key Features
 
-| Feature               | Description                                                                          |
-| --------------------- | ------------------------------------------------------------------------------------ |
-| **Multi-Provider**    | Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, and Hermes — all in one place |
-| **Smart Pricing**     | Fuzzy model matching + daily cache from LiteLLM                                      |
-| **4 Display Modes**   | Interactive TUI, static table, plain text, and JSON                                  |
-| **Dual Analysis**     | Token/cost stats (`usage`) + code operation stats (`analysis`)                       |
-| **Live Quota Panels** | Live remaining quota for Claude, Codex, Copilot, and Cursor                          |
-| **Ultra-Lightweight** | Under ~50 MB RSS in the TUI, streaming JSONL parse — built with Rust                 |
-| **Live Updates**      | Auto-refreshing dashboard (every 10s) with change highlighting                       |
+| Feature               | Description                                                             |
+| --------------------- | ----------------------------------------------------------------------- |
+| **Multi-Provider**    | Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, Hermes, and Grok |
+| **Smart Pricing**     | Fuzzy model matching + daily cache from LiteLLM                         |
+| **4 Display Modes**   | Interactive TUI, static table, plain text, and JSON                     |
+| **Dual Analysis**     | Token/cost stats (`usage`) + code operation stats (`analysis`)          |
+| **Live Quota Panels** | Live remaining quota for Claude, Codex, Copilot, and Cursor             |
+| **Ultra-Lightweight** | Under ~50 MB RSS in the TUI, streaming session parse — built with Rust  |
+| **Live Updates**      | Auto-refreshing dashboard (every 10s) with change highlighting          |
 
 ---
 
@@ -144,7 +144,7 @@ vct <COMMAND> [OPTIONS]
 # Replace with `vibe_coding_tracker` if you are using the full binary name
 
 Commands:
-  analysis    Analyze JSONL conversation files (single file or all sessions)
+  analysis    Analyze local session data (single file or all sessions)
   usage       Display token usage statistics
   version     Display version information
   update      Update to the latest version from GitHub releases
@@ -176,7 +176,6 @@ 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                                                     |
 | `--merge-providers`                            | Merge models sharing a base name across provider prefixes (ignored for `--json`) |
 | `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above)                                              |
 
@@ -195,8 +194,8 @@ 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
+# Save enriched JSON with shell redirection
+vct usage --json > report.json
 
 # Combine time range with output format
 vct usage --weekly
@@ -231,7 +230,7 @@ vct usage --table --merge-providers
 │ Gemini                            207K       $0.40                                          │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB                │
+│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB  |  CPU: 17.9% │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  m merge  r refresh  q quit  |  Star on GitHub
 ```
@@ -292,6 +291,9 @@ The tool automatically scans these directories:
 - `~/.local/share/opencode/opencode.db` (OpenCode — SQLite database; honors `$XDG_DATA_HOME`)
 - `~/.cursor/chats/*/*/store.db` (Cursor — SQLite chat stores, used for `analysis` and a local `usage` estimate consistent with the other providers)
 - `~/.hermes/state.db` (Hermes — SQLite database, honors `$HERMES_HOME`; `usage` only)
+- `$GROK_HOME/sessions/*/*/signals.json` (Grok CLI — defaults to `~/.grok`; sibling `updates.jsonl` supplies `analysis` data)
+
+Grok `usage` is one point-in-time local context estimate: vct records `signals.json`'s `contextTokensUsed` as cache-read tokens and estimates cost at the model's cache-read price. It is not cumulative billed usage. `analysis` reconstructs completed Read / Write / Edit / Bash / TodoWrite operations from the sibling `updates.jsonl`. Grok does not support quota panels or `vct fetch`.
 
 ### Live Quota Panels
 
@@ -324,19 +326,18 @@ A panel appears only for a provider whose credentials are present. When four pan
 
 **Deep dive into code operations — see exactly what your AI assistant did.**
 
-### Flags
+### Arguments and Flags
 
-| Flag                                           | Purpose                                                     |
-| ---------------------------------------------- | ----------------------------------------------------------- |
-| *(none)*                                       | Interactive TUI dashboard over all sessions                 |
-| `--path <FILE>`                                | Analyze a single JSONL/JSON conversation file (prints JSON) |
-| `--table`                                      | Static table with per-provider totals                       |
-| `--text`                                       | Plain text, script-friendly                                 |
-| `--json`                                       | JSON array of aggregated rows printed to stdout             |
-| `--output <FILE>`                              | Save results as pretty-printed JSON                         |
-| `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above)                         |
+| Argument / Flag                                | Purpose                                                                                  |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| *(none)*                                       | Interactive TUI dashboard over all sessions                                              |
+| `<FILE>`                                       | Analyze one JSONL/JSON session file and print its complete `CodeAnalysis` JSON           |
+| `--table`                                      | Static summary table with per-provider totals                                            |
+| `--text`                                       | Plain-text summary, script-friendly                                                      |
+| `--json`                                       | Complete parser results as JSON: one object for `<FILE>`, otherwise an array of objects  |
+| `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter for all-session analysis (see table above; not accepted with `<FILE>`) |
 
-See [`examples/`](examples/) for sample inputs and matching JSON outputs for all four providers.
+See [`examples/`](examples/) for sample inputs and matching JSON outputs for the four JSONL providers, plus the Grok session fixture under [`examples/grok_session/`](examples/grok_session/).
 
 ### Basic Usage
 
@@ -350,20 +351,24 @@ vct analysis --table
 # Plain text for scripts
 vct analysis --text
 
-# JSON of aggregated rows for data processing
+# Complete parser results for every session
 vct analysis --json
 
 # Analyze a single conversation file → stdout JSON
-vct analysis --path ~/.claude/projects/session.jsonl
+vct analysis ~/.claude/projects/session.jsonl
+
+# Summarize only that conversation
+vct analysis ~/.claude/projects/session.jsonl --table
 
-# Save results to JSON
-vct analysis --output report.json
+# Save complete JSON with shell redirection
+vct analysis --json > report.json
+vct analysis ~/.claude/projects/session.jsonl > session-analysis.json
 
 # Combine time range with output format
 vct analysis --weekly
 vct analysis --table --monthly
 vct analysis --json --daily
-vct analysis --output today.json --daily
+vct analysis --json --daily > today.json
 ```
 
 ### Preview: Interactive Dashboard (`vct analysis`)
@@ -383,14 +388,14 @@ vct analysis --output today.json --daily
 │ Gemini                                0            0            0      0      0      0          0      0      1 │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB                                       │
+│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB  |  CPU: 17.9%                        │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  r refresh  q quit  |  Star on GitHub
 ```
 
 ### Preview: Table & JSON (`vct analysis`)
 
-`--table` renders the per-model breakdown plus a per-provider summary (with an Active Days column); `--json` emits one aggregated row per model.
+`--table` renders the per-model breakdown plus a per-provider summary (with an Active Days column). `--text` and `--table` are compact projections of the same normalized parser records. `--json` keeps the complete records, including per-operation details and token usage. With no `<FILE>`, the outer array contains one `CodeAnalysis` object per session; with `<FILE>`, stdout is that single object and matches the corresponding shape under [`examples/`](examples/).
 
 ```text
 Analysis Statistics
@@ -404,23 +409,45 @@ Analysis Statistics
 └─────────────────┴────────────┴────────────┴─────────────┴──────┴──────┴──────┴───────────┴───────┘
 ```
 
-```json
-// vct analysis --json  (one model shown)
+```jsonc
+// vct analysis --json  (one abbreviated session shown)
 [
   {
-    "model": "claude-opus-4-8",
-    "editLines": 1493,
-    "readLines": 15564,
-    "writeLines": 970,
-    "bashCount": 124,
-    "editCount": 134,
-    "readCount": 144,
-    "todoWriteCount": 0,
-    "writeCount": 12
+    "user": "alice",
+    "extensionName": "Claude-Code",
+    "insightsVersion": "...",
+    "machineId": "...",
+    "records": [
+      {
+        "totalUniqueFiles": 3,
+        "totalReadLines": 120,
+        "readFileDetails": [
+          {
+            "filePath": "/repo/src/main.rs",
+            "lineCount": 120,
+            "characterCount": 4102,
+            "timestamp": 1783872000000
+          }
+        ],
+        "toolCallCounts": { "Bash": 1, "Edit": 0, "Read": 1, "TodoWrite": 0, "Write": 0 },
+        "conversationUsage": { "claude-opus-4-8": { "input_tokens": 42, "output_tokens": 18 } }
+      }
+    ]
   }
 ]
 ```
 
+> [!WARNING]
+> Complete analysis JSON can be large and may contain source text, edit bodies, shell commands, absolute paths, repository URLs, user names, machine identifiers, and token metadata. Review it before sharing.
+
+Batch analysis reads live provider stores. If an assistant appends to a session during the scan, later runs can legitimately contain newer data. Unchanged inputs serialize in a deterministic order.
+
+Noninteractive analysis returns an error when every discovered source fails or uses an unrecognized schema. If only some sources fail, successful output is preserved and a warning is written to stderr.
+
+`analysis FILE` follows the same rule for malformed or unsupported records inside one file: parsed JSON/text/table output is preserved on stdout and a generic skipped-record warning is written to stderr.
+
+Codex code-mode sessions expose a completed JavaScript `exec` cell but no structured trace for its nested tools. VCT counts that cell as one Bash call and preserves its source in complete JSON, but does not guess nested Read/Edit/Write operations.
+
 ---
 
 ## Update Command
@@ -549,6 +576,8 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+hermes = true
+grok = true
 
 [logging]
 # Minimum level written to ~/.vct/logs/vct-YYYY-MM-DD.log.
@@ -621,6 +650,7 @@ vct config migrate
 - **Beyond tokens**: Claude web-search tool calls (`server_tool_use.web_search_requests`) are billed per query on top of the token cost; every other model's per-query charge is $0.
 - **OpenCode**: a novel model name is priced from its tokens only on an **exact** LiteLLM match; with no exact match, vct trusts the assistant message's own stored cost instead of guessing from a loosely-similar name.
 - **Hermes**: priced the same way as OpenCode — an **exact** LiteLLM match prices from tokens, otherwise vct uses Hermes's own stored cost.
+- **Grok**: `contextTokensUsed` is priced as cache-read tokens only; this is a point-in-time local context estimate, not cumulative billed usage.
 - **Cache is raw**: the daily cache stores the filtered upstream LiteLLM JSON (not a derived shape), so tiered / batch pricing stays available without re-fetching, and a small in-process LRU keeps repeated lookups cheap during a TUI refresh.
 
 ---

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 
 </div>
 
-**实时追踪你的 AI 编程开销。** Vibe Coding Tracker 是一款基于 Rust 构建的轻量级高性能 CLI 工具，用于监控和分析你在 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 和 Hermes 上的使用情况——提供详细的费用明细、token 统计和代码操作洞察，同时保持极低的内存占用。
+**实时追踪你的 AI 编程开销。** Vibe Coding Tracker 是一款基于 Rust 构建的轻量级高性能 CLI 工具，用于监控和分析你在 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 和 Grok 上的使用情况——提供详细的费用明细、token 统计和代码操作洞察，同时保持极低的内存占用。
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
 
@@ -41,14 +41,14 @@
 
 选择你喜欢的查看方式：
 
-- **交互式面板**：自动刷新的终端 UI，支持实时更新、可滚动的模型列表（方向键），以及 K/M/B 精简数字格式
+- **交互式面板**：自动刷新的终端 UI，支持实时更新、可滚动的模型列表（方向键）、进程级 CPU/内存实时读数，以及 K/M/B 精简数字格式
 - **静态报表**：专业的表格，适合文档记录
 - **脚本友好**：纯文本和 JSON 格式，方便自动化
 - **完整精度**：导出精确费用，满足财务核算需求
 
 ### 零配置
 
-自动检测并处理来自 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 和 Hermes 的日志。无需任何设置——直接运行即可分析。首次运行时会自动生成一个带有合理默认值的 `~/.vct/config.toml`，方便你日后想调整行为时使用（参见 [配置](#%E9%85%8D%E7%BD%AE)）。
+自动检测并处理来自 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 和 Grok 的日志。无需任何设置——直接运行即可分析。首次运行时会自动生成一个带有合理默认值的 `~/.vct/config.toml`，方便你日后想调整行为时使用（参见 [配置](#%E9%85%8D%E7%BD%AE)）。
 
 ### 丰富的洞察
 
@@ -62,15 +62,15 @@
 
 ## 核心特性
 
-| 特性             | 说明                                                                        |
-| ---------------- | --------------------------------------------------------------------------- |
-| **多供应商支持** | Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 和 Hermes——一站式管理 |
-| **智能定价**     | 模糊模型匹配 + 从 LiteLLM 每日缓存更新                                      |
-| **4 种显示模式** | 交互式 TUI、静态表格、纯文本和 JSON                                         |
-| **双维度分析**   | token/费用统计（`usage`）+ 代码操作统计（`analysis`）                       |
-| **实时额度面板** | Claude、Codex、Copilot 和 Cursor 的实时剩余额度                             |
-| **超轻量级**     | TUI 常驻内存 50 MB 以内、流式 JSONL 解析——基于 Rust 构建                    |
-| **实时更新**     | 面板自动刷新（每 10 秒），并高亮变化                                        |
+| 特性             | 说明                                                                  |
+| ---------------- | --------------------------------------------------------------------- |
+| **多供应商支持** | Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 和 Grok |
+| **智能定价**     | 模糊模型匹配 + 从 LiteLLM 每日缓存更新                                |
+| **4 种显示模式** | 交互式 TUI、静态表格、纯文本和 JSON                                   |
+| **双维度分析**   | token/费用统计（`usage`）+ 代码操作统计（`analysis`）                 |
+| **实时额度面板** | Claude、Codex、Copilot 和 Cursor 的实时剩余额度                       |
+| **超轻量级**     | TUI 常驻内存 50 MB 以内、流式 session 解析——基于 Rust 构建            |
+| **实时更新**     | 面板自动刷新（每 10 秒），并高亮变化                                  |
 
 ---
 
@@ -144,7 +144,7 @@ vct <COMMAND> [OPTIONS]
 # Replace with `vibe_coding_tracker` if you are using the full binary name
 
 Commands:
-  analysis    Analyze JSONL conversation files (single file or all sessions)
+  analysis    Analyze local session data (single file or all sessions)
   usage       Display token usage statistics
   version     Display version information
   update      Update to the latest version from GitHub releases
@@ -176,7 +176,6 @@ Commands:
 | `--table`                                      | 静态表格，不启动 TUI                                                          |
 | `--text`                                       | 纯文本，适合脚本处理                                                          |
 | `--json`                                       | JSON 输出，附带定价信息                                                       |
-| `--output <FILE>`                              | 将富化 JSON 保存到文件                                                        |
 | `--merge-providers`                            | 合并共享同一 base 名称、仅 provider 前缀不同的 model（`--json` 会忽略此选项） |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格）                                                    |
 
@@ -195,8 +194,8 @@ vct usage --text
 # JSON 输出，包含 cost_usd 与 matched_model 字段
 vct usage --json
 
-# 直接把富化 JSON 保存到文件
-vct usage --output report.json
+# 通过 shell redirection 保存富化 JSON
+vct usage --json > report.json
 
 # 时间范围与输出格式可自由组合
 vct usage --weekly
@@ -231,7 +230,7 @@ vct usage --table --merge-providers
 │ Gemini                            207K       $0.40                                          │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB                │
+│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB  |  CPU: 17.9% │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  m merge  r refresh  q quit  |  Star on GitHub
 ```
@@ -292,6 +291,9 @@ Totals (by Provider)
 - `~/.local/share/opencode/opencode.db`（OpenCode，SQLite 数据库；遵循 `$XDG_DATA_HOME`）
 - `~/.cursor/chats/*/*/store.db`（Cursor，SQLite 会话库，用于 `analysis`，并给出一个与其他 provider 一致的本地 `usage` 估算）
 - `~/.hermes/state.db`（Hermes，SQLite 数据库，遵循 `$HERMES_HOME`；仅 `usage`）
+- `$GROK_HOME/sessions/*/*/signals.json`（Grok CLI，默认使用 `~/.grok`；同层的 `updates.jsonl` 提供 `analysis` 数据）
+
+Grok 的 `usage` 是单一时点的本地 context 估算：vct 会把 `signals.json` 的 `contextTokensUsed` 记为 cache-read token，并按该 model 的 cache-read 费率估算费用。这不是累计的 billed usage。`analysis` 会从同层的 `updates.jsonl` 还原已完成的 Read / Write / Edit / Bash / TodoWrite 操作。Grok 不支持 quota panel 或 `vct fetch`。
 
 ### 实时额度面板
 
@@ -324,19 +326,18 @@ Totals (by Provider)
 
 **深入了解代码操作——查看你的 AI 助手到底做了什么。**
 
-### Flag 一览
+### 参数与 Flag
 
-| Flag                                           | 用途                                             |
-| ---------------------------------------------- | ------------------------------------------------ |
-| *(不带参数)*                                   | 互动式 TUI 面板，覆盖所有 session                |
-| `--path <FILE>`                                | 分析单一 JSONL/JSON 对话文件（stdout 输出 JSON） |
-| `--table`                                      | 静态表格，附带按供应商的总计                     |
-| `--text`                                       | 纯文本，方便脚本处理                             |
-| `--json`                                       | 将聚合 row 以 JSON 数组输出到 stdout             |
-| `--output <FILE>`                              | 将结果以格式化 JSON 保存到文件                   |
-| `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格）                       |
+| 参数 / Flag                                    | 用途                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------------------- |
+| *(不带参数)*                                   | 互动式 TUI 面板, 覆盖所有 session                                            |
+| `<FILE>`                                       | 分析单一 JSONL/JSON session 文件, 并将完整 `CodeAnalysis` JSON 输出到 stdout |
+| `--table`                                      | 静态摘要表格, 附带 provider 汇总                                             |
+| `--text`                                       | 纯文本摘要, 方便脚本处理                                                     |
+| `--json`                                       | 完整 parser 结果. 搭配 `<FILE>` 时为单一 object, 否则为 object 数组          |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 所有 session 的时间范围筛选. 不可与 `<FILE>` 同时使用, 其他说明见上方表格    |
 
-参见 [`examples/`](examples/) 目录，其中包含四种 provider 的示例输入与对应 JSON 输出。
+参见 [`examples/`](examples/) 目录，其中包含四种 JSONL provider 的示例输入与对应 JSON 输出，以及 [`examples/grok_session/`](examples/grok_session/) 下的 Grok session fixture。
 
 ### 基本用法
 
@@ -350,20 +351,24 @@ vct analysis --table
 # 纯文本输出，方便脚本处理
 vct analysis --text
 
-# 聚合数据以 JSON 输出，方便后续处理
+# 输出所有 session 的完整 parser 结果
 vct analysis --json
 
-# 分析单一对话文件 → stdout JSON
-vct analysis --path ~/.claude/projects/session.jsonl
+# 分析单一对话文件并输出 JSON
+vct analysis ~/.claude/projects/session.jsonl
+
+# 只汇总这个对话文件
+vct analysis ~/.claude/projects/session.jsonl --table
 
-# Save results to JSON
-vct analysis --output report.json
+# 通过 shell redirection 保存完整 JSON
+vct analysis --json > report.json
+vct analysis ~/.claude/projects/session.jsonl > session-analysis.json
 
 # 时间范围与输出格式可自由组合
 vct analysis --weekly
 vct analysis --table --monthly
 vct analysis --json --daily
-vct analysis --output today.json --daily
+vct analysis --json --daily > today.json
 ```
 
 ### 预览：交互式面板（`vct analysis`）
@@ -383,14 +388,14 @@ vct analysis --output today.json --daily
 │ Gemini                                0            0            0      0      0      0          0      0      1 │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB                                       │
+│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB  |  CPU: 17.9%                        │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  r refresh  q quit  |  Star on GitHub
 ```
 
 ### 预览：表格与 JSON（`vct analysis`）
 
-`--table` 会渲染按 model 细分的数据，并附带按 provider 的汇总（含 Active Days 列）；`--json` 则为每个 model 输出一行聚合数据。
+`--table` 会显示各 model 的明细, 并附上各 provider 的汇总, 包含 Active Days 列. `--text` 与 `--table` 都是相同 normalized parser records 的精简 projection. `--json` 会保留完整 records, 包括每次操作的 details 与 token usage. 未提供 `<FILE>` 时, 外层数组中的每个元素都是一个 session 的 `CodeAnalysis` object. 提供 `<FILE>` 时, stdout 只会输出该 object, shape 与 [`examples/`](examples/) 中对应的结果相同.
 
 ```text
 Analysis Statistics
@@ -404,23 +409,45 @@ Analysis Statistics
 └─────────────────┴────────────┴────────────┴─────────────┴──────┴──────┴──────┴───────────┴───────┘
 ```
 
-```json
-// vct analysis --json  (one model shown)
+```jsonc
+// vct analysis --json  (one abbreviated session shown)
 [
   {
-    "model": "claude-opus-4-8",
-    "editLines": 1493,
-    "readLines": 15564,
-    "writeLines": 970,
-    "bashCount": 124,
-    "editCount": 134,
-    "readCount": 144,
-    "todoWriteCount": 0,
-    "writeCount": 12
+    "user": "alice",
+    "extensionName": "Claude-Code",
+    "insightsVersion": "...",
+    "machineId": "...",
+    "records": [
+      {
+        "totalUniqueFiles": 3,
+        "totalReadLines": 120,
+        "readFileDetails": [
+          {
+            "filePath": "/repo/src/main.rs",
+            "lineCount": 120,
+            "characterCount": 4102,
+            "timestamp": 1783872000000
+          }
+        ],
+        "toolCallCounts": { "Bash": 1, "Edit": 0, "Read": 1, "TodoWrite": 0, "Write": 0 },
+        "conversationUsage": { "claude-opus-4-8": { "input_tokens": 42, "output_tokens": 18 } }
+      }
+    ]
   }
 ]
 ```
 
+> [!WARNING]
+> 完整 analysis JSON 可能很大, 也可能包含 source text, edit body, shell command, absolute path, repository URL, user name, machine identifier 与 token metadata. 分享前请先检查内容.
+
+Batch analysis 会读取 Provider 的实时数据. 如果 assistant 在扫描期间继续写入 session, 后续执行可能合理地包含更新数据. 未变动的 input 会产生固定顺序的输出.
+
+如果找到的 source 全部读取失败或使用无法识别的 schema, 非交互式 analysis 会返回 error. 如果只有部分 source 失败, 成功结果会保留, warning 会写入 stderr.
+
+`analysis FILE` 对单一文件内格式错误或不受支持的 record 采用相同行为: 在 stdout 保留已解析的 JSON/text/table 输出, 并将一般性的 skipped-record warning 写入 stderr.
+
+Codex code mode session 会提供已完成的 JavaScript `exec` cell, 但没有 nested tool 的结构化 trace. VCT 会将该 cell 计为一次 Bash call, 并在完整 JSON 中保留 source, 但不会猜测 nested Read/Edit/Write operation.
+
 ---
 
 ## Update 命令
@@ -548,6 +575,8 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+hermes = true
+grok = true
 
 [logging]
 # 写入 ~/.vct/logs/vct-YYYY-MM-DD.log 的最低日志级别。
@@ -620,6 +649,7 @@ vct config migrate
 - **不止 token**：Claude 的 web-search 工具调用（`server_tool_use.web_search_requests`）会在 token 费用之外按每次查询计费；其他所有 model 的每次查询费用均为 $0。
 - **OpenCode**：只有在 LiteLLM 上**精确**匹配时，才会根据 token 为一个全新的 model 名称定价；若没有精确匹配，vct 会信任该 assistant message 自身存储的费用，而不是从一个只是大致相似的名称去猜测。
 - **Hermes**：与 OpenCode 相同，LiteLLM 上**精确**匹配时按 token 定价，否则使用 Hermes 自身存储的费用。
+- **Grok**：只会把 `contextTokensUsed` 作为 cache-read token 计价；这是单一时点的本地 context 估算，不是累计的 billed usage。
 - **缓存为原始数据**：每日缓存存储的是经过筛选的上游 LiteLLM JSON（而非派生后的结构），因此无需重新获取即可保留分层 / 批量定价；此外还有一个小型的进程内 LRU，让 TUI 刷新期间的重复查询保持低开销。
 
 ---

package/README.zh-TW.md

@@ -19,7 +19,7 @@
 
 </div>
 
-**即時追蹤你的 AI 程式設計花費。** Vibe Coding Tracker 是一款以 Rust 打造的輕量、高效能 CLI 工具，能監控與分析你在 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 及 Hermes 的使用狀況——提供詳細的費用明細、token 統計資料與程式碼操作分析，同時維持極低的記憶體使用量。
+**即時追蹤你的 AI 程式設計花費。** Vibe Coding Tracker 是一款以 Rust 打造的輕量、高效能 CLI 工具，能監控與分析你在 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 及 Grok 的使用狀況——提供詳細的費用明細、token 統計資料與程式碼操作分析，同時維持極低的記憶體使用量。
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
 
@@ -41,14 +41,14 @@
 
 選擇你偏好的檢視方式：
 
-- **互動式儀表板**：自動更新的終端機 UI,即時顯示最新資訊、可捲動的 model 清單(方向鍵),以及 K/M/B 精簡數字格式
-- **靜態報表**：專業的表格格式，適合撰寫文件
-- **腳本友好**：純文字及 JSON 輸出，方便自動化處理
-- **完整精度**：匯出精確費用供會計使用
+- **互動式儀表板**:自動更新的終端機 UI,即時顯示最新資訊、可捲動的 model 清單(方向鍵)、process 層級的 CPU/記憶體即時讀數,以及 K/M/B 精簡數字格式
+- **靜態報表**:專業的表格格式,適合撰寫文件
+- **腳本友好**:純文字及 JSON 輸出,方便自動化處理
+- **完整精度**:匯出精確費用供會計使用
 
 ### 零設定
 
-自動偵測並處理 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 及 Hermes 的日誌檔。不需要任何設定——直接執行就能分析。首次執行時會以合理的預設值建立 `~/.vct/config.toml`，日後若想微調行為即可編輯它（見 [設定](#%E8%A8%AD%E5%AE%9A)）。
+自動偵測並處理 Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 及 Grok 的日誌檔。不需要任何設定——直接執行就能分析。首次執行時會以合理的預設值建立 `~/.vct/config.toml`，日後若想微調行為即可編輯它（見 [設定](#%E8%A8%AD%E5%AE%9A)）。
 
 ### 豐富洞察
 
@@ -62,15 +62,15 @@
 
 ## 主要功能
 
-| 功能             | 說明                                                                      |
-| ---------------- | ------------------------------------------------------------------------- |
-| **多供應商支援** | Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor 及 Hermes——一站整合 |
-| **智慧定價**     | 模糊模型比對 + 每日從 LiteLLM cache 更新                                  |
-| **4 種顯示模式** | 互動式 TUI、靜態表格、純文字及 JSON                                       |
-| **雙重分析**     | Token / 費用統計（`usage`）+ 程式碼操作統計（`analysis`）                 |
-| **即時額度面板** | 即時顯示 Claude、Codex、Copilot 與 Cursor 的剩餘額度                      |
-| **超輕量**       | TUI 常駐記憶體 ~50 MB 以內、串流 JSONL 解析——以 Rust 打造                 |
-| **即時更新**     | 每 10 秒自動刷新的儀表板並突顯變更                                        |
+| 功能             | 說明                                                                  |
+| ---------------- | --------------------------------------------------------------------- |
+| **多供應商支援** | Claude Code、Codex、Copilot、Gemini、OpenCode、Cursor、Hermes 及 Grok |
+| **智慧定價**     | 模糊模型比對 + 每日從 LiteLLM cache 更新                              |
+| **4 種顯示模式** | 互動式 TUI、靜態表格、純文字及 JSON                                   |
+| **雙重分析**     | Token / 費用統計（`usage`）+ 程式碼操作統計（`analysis`）             |
+| **即時額度面板** | 即時顯示 Claude、Codex、Copilot 與 Cursor 的剩餘額度                  |
+| **超輕量**       | TUI 常駐記憶體 ~50 MB 以內、串流 session 解析——以 Rust 打造           |
+| **即時更新**     | 每 10 秒自動刷新的儀表板並突顯變更                                    |
 
 ---
 
@@ -144,7 +144,7 @@ vct <COMMAND> [OPTIONS]
 # Replace with `vibe_coding_tracker` if you are using the full binary name
 
 Commands:
-  analysis    Analyze JSONL conversation files (single file or all sessions)
+  analysis    Analyze local session data (single file or all sessions)
   usage       Display token usage statistics
   version     Display version information
   update      Update to the latest version from GitHub releases
@@ -176,7 +176,6 @@ Commands:
 | `--table`                                      | 靜態表格，不啟動 TUI                                                          |
 | `--text`                                       | 純文字，適合腳本處理                                                          |
 | `--json`                                       | JSON 輸出，附帶 pricing 資訊                                                  |
-| `--output <FILE>`                              | 將富化 JSON 存成檔案                                                          |
 | `--merge-providers`                            | 合併共享同一 base 名稱、僅 provider 前綴不同的 model（`--json` 會忽略此選項） |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格）                                                    |
 
@@ -195,8 +194,8 @@ vct usage --text
 # JSON 輸出，包含 cost_usd 與 matched_model 欄位
 vct usage --json
 
-# 直接把富化 JSON 存成檔案
-vct usage --output report.json
+# 透過 shell redirection 儲存富化 JSON
+vct usage --json > report.json
 
 # 時間範圍與輸出格式可自由組合
 vct usage --weekly
@@ -231,7 +230,7 @@ vct usage --table --merge-providers
 │ Gemini                            207K       $0.40                                          │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB                │
+│ Total Cost: $79.33  |  Total Tokens: 49.3M  |  Models: 3  |  Memory: 42.8 MB  |  CPU: 17.9% │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  m merge  r refresh  q quit  |  Star on GitHub
 ```
@@ -292,6 +291,9 @@ Totals (by Provider)
 - `~/.local/share/opencode/opencode.db`（OpenCode，SQLite 資料庫；遵循 `$XDG_DATA_HOME`）
 - `~/.cursor/chats/*/*/store.db`（Cursor，SQLite 對話庫，用於 `analysis`，並產生與其他 provider 一致的本地 `usage` 估算）
 - `~/.hermes/state.db`（Hermes，SQLite 資料庫，遵循 `$HERMES_HOME`；僅 `usage`）
+- `$GROK_HOME/sessions/*/*/signals.json`（Grok CLI，預設使用 `~/.grok`；同層的 `updates.jsonl` 提供 `analysis` 資料）
+
+Grok 的 `usage` 是單一當下的本地 context 估算：vct 會把 `signals.json` 的 `contextTokensUsed` 記為 cache-read token，並以該 model 的 cache-read 費率估算費用。這不是累計的 billed usage。`analysis` 會從同層的 `updates.jsonl` 還原已完成的 Read / Write / Edit / Bash / TodoWrite 操作。Grok 不支援 quota panel 或 `vct fetch`。
 
 ### 即時額度面板
 
@@ -324,19 +326,18 @@ Totals (by Provider)
 
 **深入分析程式碼操作——精確掌握你的 AI 助手做了哪些事。**
 
-### Flag 一覽
+### 參數與 Flag
 
-| Flag                                           | 用途                                             |
-| ---------------------------------------------- | ------------------------------------------------ |
-| *(不帶參數)*                                   | 互動式 TUI 儀表板，涵蓋所有 session              |
-| `--path <FILE>`                                | 分析單一 JSONL/JSON 對話檔案（stdout 輸出 JSON） |
-| `--table`                                      | 靜態表格，附帶供應商總計                         |
-| `--text`                                       | 純文字，方便腳本處理                             |
-| `--json`                                       | 將聚合 row 以 JSON 陣列輸出到 stdout             |
-| `--output <FILE>`                              | 將結果以格式化 JSON 存成檔案                     |
-| `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格）                       |
+| 參數 / Flag                                    | 用途                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------------------- |
+| *(不帶參數)*                                   | 互動式 TUI 儀表板, 涵蓋所有 session                                          |
+| `<FILE>`                                       | 分析單一 JSONL/JSON session 檔案, 並將完整 `CodeAnalysis` JSON 輸出到 stdout |
+| `--table`                                      | 靜態摘要表格, 附帶 provider 總計                                             |
+| `--text`                                       | 純文字摘要, 方便腳本處理                                                     |
+| `--json`                                       | 完整 parser 結果. 搭配 `<FILE>` 時為單一 object, 否則為 object 陣列          |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 所有 session 的時間範圍篩選. 不可與 `<FILE>` 同時使用, 其他說明見上方表格    |
 
-請參考 [`examples/`](examples/) 目錄，裡面有四種 provider 的範例輸入與對應的 JSON 輸出。
+請參考 [`examples/`](examples/) 目錄，裡面有四種 JSONL provider 的範例輸入與對應的 JSON 輸出，以及 [`examples/grok_session/`](examples/grok_session/) 下的 Grok session fixture。
 
 ### 基本用法
 
@@ -350,20 +351,24 @@ vct analysis --table
 # 純文字輸出，方便腳本處理
 vct analysis --text
 
-# 聚合資料以 JSON 輸出，方便後續處理
+# 輸出所有 session 的完整 parser 結果
 vct analysis --json
 
-# 分析單一對話檔案 → stdout JSON
-vct analysis --path ~/.claude/projects/session.jsonl
+# 分析單一對話檔案並輸出 JSON
+vct analysis ~/.claude/projects/session.jsonl
+
+# 只摘要這個對話檔案
+vct analysis ~/.claude/projects/session.jsonl --table
 
-# Save results to JSON
-vct analysis --output report.json
+# 透過 shell redirection 儲存完整 JSON
+vct analysis --json > report.json
+vct analysis ~/.claude/projects/session.jsonl > session-analysis.json
 
 # 時間範圍與輸出格式可自由組合
 vct analysis --weekly
 vct analysis --table --monthly
 vct analysis --json --daily
-vct analysis --output today.json --daily
+vct analysis --json --daily > today.json
 ```
 
 ### 預覽：互動式儀表板（`vct analysis`）
@@ -383,14 +388,14 @@ vct analysis --output today.json --daily
 │ Gemini                                0            0            0      0      0      0          0      0      1 │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB                                       │
+│ Total Lines: 16.1K  |  Total Tools: 619  |  Models: 3  |  Memory: 41.2 MB  |  CPU: 17.9%                        │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
   ↑/↓ scroll  r refresh  q quit  |  Star on GitHub
 ```
 
 ### 預覽：表格與 JSON（`vct analysis`）
 
-`--table` 會呈現每個 model 的明細以及每個供應商的彙總（含 Active Days 欄位）；`--json` 則為每個 model 輸出一列聚合資料。
+`--table` 會顯示各 model 的明細, 並附上各 provider 的摘要, 包含 Active Days 欄位. `--text` 與 `--table` 都是相同 normalized parser records 的精簡 projection. `--json` 會保留完整 records, 包括每次操作的 details 與 token usage. 未提供 `<FILE>` 時, 外層陣列中的每個元素都是一個 session 的 `CodeAnalysis` object. 提供 `<FILE>` 時, stdout 只會輸出該 object, shape 與 [`examples/`](examples/) 中對應的結果相同.
 
 ```text
 Analysis Statistics
@@ -404,23 +409,45 @@ Analysis Statistics
 └─────────────────┴────────────┴────────────┴─────────────┴──────┴──────┴──────┴───────────┴───────┘
 ```
 
-```json
-// vct analysis --json  (one model shown)
+```jsonc
+// vct analysis --json  (one abbreviated session shown)
 [
   {
-    "model": "claude-opus-4-8",
-    "editLines": 1493,
-    "readLines": 15564,
-    "writeLines": 970,
-    "bashCount": 124,
-    "editCount": 134,
-    "readCount": 144,
-    "todoWriteCount": 0,
-    "writeCount": 12
+    "user": "alice",
+    "extensionName": "Claude-Code",
+    "insightsVersion": "...",
+    "machineId": "...",
+    "records": [
+      {
+        "totalUniqueFiles": 3,
+        "totalReadLines": 120,
+        "readFileDetails": [
+          {
+            "filePath": "/repo/src/main.rs",
+            "lineCount": 120,
+            "characterCount": 4102,
+            "timestamp": 1783872000000
+          }
+        ],
+        "toolCallCounts": { "Bash": 1, "Edit": 0, "Read": 1, "TodoWrite": 0, "Write": 0 },
+        "conversationUsage": { "claude-opus-4-8": { "input_tokens": 42, "output_tokens": 18 } }
+      }
+    ]
   }
 ]
 ```
 
+> [!WARNING]
+> 完整 analysis JSON 可能很大, 也可能包含 source text, edit body, shell command, absolute path, repository URL, user name, machine identifier 與 token metadata. 分享前請先檢查內容.
+
+Batch analysis 會讀取 Provider 的即時資料. 如果 assistant 在掃描期間繼續寫入 session, 後續執行可能合理地包含更新資料. 未變動的 input 會產生固定順序的輸出.
+
+如果找到的 source 全部讀取失敗或使用無法辨識的 schema, 非互動式 analysis 會回傳 error. 如果只有部分 source 失敗, 成功結果會保留, warning 會寫入 stderr.
+
+`analysis FILE` 對單一檔案內格式錯誤或不受支援的 record 採用相同行為: 在 stdout 保留已解析的 JSON/text/table 輸出, 並將一般性的 skipped-record warning 寫入 stderr.
+
+Codex code mode session 會提供已完成的 JavaScript `exec` cell, 但沒有 nested tool 的結構化 trace. VCT 會將該 cell 計為一次 Bash call, 並在完整 JSON 中保留 source, 但不會猜測 nested Read/Edit/Write operation.
+
 ---
 
 ## Update 指令
@@ -548,6 +575,8 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+hermes = true
+grok = true
 
 [logging]
 # 寫入 ~/.vct/logs/vct-YYYY-MM-DD.log 的最低日誌等級。
@@ -620,6 +649,7 @@ vct config migrate
 - **不只 token**：Claude 的網頁搜尋工具呼叫（`server_tool_use.web_search_requests`）會在 token 費用之外，按每次查詢計費；其他所有 model 的每次查詢費用皆為 $0。
 - **OpenCode**：只有在 LiteLLM **完全比對**成功時，才會依 token 為新型 model 計價；若沒有完全比對，vct 會採信該 assistant 訊息本身儲存的費用，而不是從名稱相近的 model 去猜測。
 - **Hermes**：與 OpenCode 相同，LiteLLM **完全比對**成功時依 token 計價，否則使用 Hermes 本身儲存的費用。
+- **Grok**：只會把 `contextTokensUsed` 當成 cache-read token 計價；這是單一當下的本地 context 估算，不是累計的 billed usage。
 - **原始 cache**：每日 cache 儲存的是經過篩選的上游 LiteLLM JSON（而非衍生後的結構），因此分層 / 批次定價無需重新抓取即可使用；另外一個小型的行內 LRU 會讓 TUI 刷新期間的重複查詢維持低成本。
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mai0313/vct",
-  "version": "1.12.0",
+  "version": "2.1.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",