vibe-coding-tracker 1.11.0__tar.gz → 2.0.0__tar.gz

{vibe_coding_tracker-1.11.0 → vibe_coding_tracker-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: vibe-coding-tracker
-Version: 1.11.0
+Version: 2.0.0
 Summary: Vibe Coding Tracker - AI coding assistant telemetry/usage parser, aggregate JSONL events into CodeAnalysis results
 Keywords: cli,ai,coding-assistant,telemetry,claude,codex,gemini,usage-tracker,analytics
 Author: Wei Lee
@@ -45,7 +45,7 @@ Description-Content-Type: text/markdown
 
 </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)
 
@@ -74,7 +74,7 @@ Choose your preferred view:
 
 ### 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
 
@@ -88,15 +88,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          |
 
 ---
 
@@ -170,7 +170,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
@@ -202,7 +202,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)                                              |
 
@@ -221,8 +220,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
@@ -318,6 +317,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
 
@@ -350,19 +352,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
 
@@ -376,20 +377,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`)
@@ -416,7 +421,7 @@ vct analysis --output today.json --daily
 
 ### 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
@@ -430,23 +435,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
@@ -575,6 +602,15 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+hermes = true
+grok = true
+
+[logging]
+# Minimum level written to ~/.vct/logs/vct-YYYY-MM-DD.log.
+# One of: "off" | "error" | "warn" | "info" | "debug" | "trace".
+level = "warn"
+# Days of daily log files to keep; older files are pruned on startup. 0 keeps every file.
+retention_days = 7
 ```
 
 | Setting                        | Effect                                                                                                                       |
@@ -586,10 +622,15 @@ cursor = true
 | `usage.quota.refresh_interval` | Poll cadence for every live quota panel (seconds); higher is safer against a provider's rate limits.                         |
 | `analysis.refresh_interval`    | Redraw cadence of the `analysis` dashboard (seconds).                                                                        |
 | `providers.*`                  | Skip a provider entirely (no scan, no API) when `false` — handy if you don't use one.                                        |
+| `logging.level`                | Minimum severity written to the log file (`off`..`trace`); never printed to the terminal.                                    |
+| `logging.retention_days`       | Days of daily log files to keep; older `vct-*.log` are pruned on startup (`0` keeps all).                                    |
 
 > [!NOTE]
 > Cursor `usage` is a **local estimate** from the chat stores, so it behaves like Claude Code / Codex / Copilot / Gemini (all computed from local session files) and needs no network. It undercounts Cursor's real spend, because much of it is billed under Cursor-internal model names the local data cannot price — treat Cursor cost as approximate.
 
+> [!NOTE]
+> vct writes diagnostics to `~/.vct/logs/vct-YYYY-MM-DD.log` (plain text, file only — never shown in the dashboard). It stays quiet when healthy (default level `warn`) and the file is created lazily, so a healthy run leaves nothing behind. When a quota fetch fails or a session is skipped, that is where the reason is recorded — bump `logging.level` to `debug` for the full detail.
+
 ### Managing the file
 
 ```bash
@@ -635,6 +676,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.
 
 ---

{vibe_coding_tracker-1.11.0 → vibe_coding_tracker-2.0.0}/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)
 
@@ -48,7 +48,7 @@ Choose your preferred view:
 
 ### 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
@@ -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`)
@@ -390,7 +395,7 @@ vct analysis --output today.json --daily
 
 ### 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,15 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+hermes = true
+grok = true
+
+[logging]
+# Minimum level written to ~/.vct/logs/vct-YYYY-MM-DD.log.
+# One of: "off" | "error" | "warn" | "info" | "debug" | "trace".
+level = "warn"
+# Days of daily log files to keep; older files are pruned on startup. 0 keeps every file.
+retention_days = 7
 ```
 
 | Setting                        | Effect                                                                                                                       |
@@ -560,10 +596,15 @@ cursor = true
 | `usage.quota.refresh_interval` | Poll cadence for every live quota panel (seconds); higher is safer against a provider's rate limits.                         |
 | `analysis.refresh_interval`    | Redraw cadence of the `analysis` dashboard (seconds).                                                                        |
 | `providers.*`                  | Skip a provider entirely (no scan, no API) when `false` — handy if you don't use one.                                        |
+| `logging.level`                | Minimum severity written to the log file (`off`..`trace`); never printed to the terminal.                                    |
+| `logging.retention_days`       | Days of daily log files to keep; older `vct-*.log` are pruned on startup (`0` keeps all).                                    |
 
 > [!NOTE]
 > Cursor `usage` is a **local estimate** from the chat stores, so it behaves like Claude Code / Codex / Copilot / Gemini (all computed from local session files) and needs no network. It undercounts Cursor's real spend, because much of it is billed under Cursor-internal model names the local data cannot price — treat Cursor cost as approximate.
 
+> [!NOTE]
+> vct writes diagnostics to `~/.vct/logs/vct-YYYY-MM-DD.log` (plain text, file only — never shown in the dashboard). It stays quiet when healthy (default level `warn`) and the file is created lazily, so a healthy run leaves nothing behind. When a quota fetch fails or a session is skipped, that is where the reason is recorded — bump `logging.level` to `debug` for the full detail.
+
 ### Managing the file
 
 ```bash
@@ -609,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.
 
 ---

{vibe_coding_tracker-1.11.0 → vibe_coding_tracker-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vibe_coding_tracker"
-version = "1.11.0"
+version = "2.0.0"
 description = "Vibe Coding Tracker - AI coding assistant telemetry/usage parser, aggregate JSONL events into CodeAnalysis results"
 authors = [
     { name = "Wei Lee", email = "mai@mai0313.com" }