@osovv/vv-opencode 1.2.11 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.3.0 (2026-08-19)
+
+### Summary
+
+Version 1.3.0 introduces a new analytics system to help users understand and optimize token usage and prompt-cache effectiveness. A new AnalyticsPlugin collects per-step token and cache telemetry with vvoc and OpenCode version attribution into local-only JSONL files, the new `vvoc analytics cache-hit-rate` command aggregates and compares cache hit rates by day, week, month, model, provider, project, session, or vvoc/OpenCode version with date/project filters and JSON output, and the TUI gains a live per-session cache percentage indicator plus a vvoc version footer. A new vvoc-usage-analytics managed skill lets users ask usage, cache, and cost questions conversationally during a session, including historical comparisons from opencode.db that predate the plugin. All telemetry stays on the machine, and analytics collection can be disabled via the plugin toggle.
+
+* feat(analytics): add analytics types, JSONL store, metrics, and version helper export ([a709547](https://github.com/osovv/vv-opencode/commit/a709547))
+* feat(analytics): add cache-hit-rate CLI command with grouping and JSON output ([8d0e70f](https://github.com/osovv/vv-opencode/commit/8d0e70f))
+* feat(analytics): add live cache indicator and vvoc version footer for the TUI ([8098f10](https://github.com/osovv/vv-opencode/commit/8098f10))
+* feat(analytics): add server plugin collecting step-finish telemetry with version attribution ([9db2cb3](https://github.com/osovv/vv-opencode/commit/9db2cb3))
+* feat(analytics): register analytics toggle, CLI command, and TUI wiring ([e54d4b0](https://github.com/osovv/vv-opencode/commit/e54d4b0))
+* feat(skills): add vvoc-usage-analytics managed skill with read-only opencode.db queries ([d61cda0](https://github.com/osovv/vv-opencode/commit/d61cda0))
+* docs(analytics): document cache hit rate analytics in README and stabilize CLI exit-code tests ([8519eab](https://github.com/osovv/vv-opencode/commit/8519eab))
+
 ## <small>1.2.11 (2026-08-18)</small>
 
 ### Summary

package/README.md

@@ -166,10 +166,11 @@ OpenCode is a strong, flexible base for agentic coding, but it intentionally lea
 | **Workflow Tracking** | Replace free-form multi-agent chaos with explicit work items, bounded review rounds, reviewer result collection, and hard stops when more context is needed |
 | **Unified Web Tools** | Replace provider-specific search and reader schemas with the canonical `web_search` and `web_fetch` tools, configurable for Exa, Brave, native retrieval, or Spider extraction |
 | **Context Inspector** | Run `/context` in an active OpenCode TUI session for Overview, Tools, and MCP tabs with provider-reported usage, approximate context-window percentages, active post-compaction tool history, and deterministic source attribution |
+| **Cache Analytics** | Watch a live per-session `cache NN%` indicator in the TUI and compare cache hit rates across vvoc releases, OpenCode versions, models, and projects with `vvoc analytics cache-hit-rate` |
 
 ---
 
-## The Nine Plugins
+## The Ten Plugins
 
 | Plugin | What it helps you do |
 |---|---|
@@ -182,6 +183,7 @@ OpenCode is a strong, flexible base for agentic coding, but it intentionally lea
 | **WebToolsPlugin** | Register the provider-neutral `web_search` and `web_fetch` tools, return direct image/PDF attachments, and hide OpenCode's built-in web tools at runtime unless the user explicitly configured their permissions. |
 | **ContextTuiPlugin** | Add a native scrollable `/context` dialog with measured usage plus detailed observable per-tool and per-MCP schema/history estimates, explicitly marking data that OpenCode does not expose. |
 | **ToolHistoryCompactionPlugin** | Shrink the replayed conversation context non-destructively by compacting old tool outputs in the model replay (old reads to `[Read <file>, lines X-Y]`, over-budget ephemeral outputs pruned), while retaining web/search/skill knowledge results. |
+| **AnalyticsPlugin** | Persist per-step token and cache telemetry with vvoc/OpenCode version attribution, show a live `cache NN%` indicator next to the session prompt plus a `vvoc vX.Y.Z` sidebar footer, and answer "did my cache optimizations help?" via `vvoc analytics cache-hit-rate`. |
 
 Workflow work items are opened with explicit intent. For implementation loops, controllers use:
 
@@ -259,6 +261,26 @@ Config lives in `vvoc.json` under `plugins["tool-history-compaction"]` (boolean
 
 Set `outputMaxChars` to `0` to disable pruning, or `"enabled": false` to disable the plugin entirely. Changes require an OpenCode restart.
 
+### Cache Hit Rate Analytics
+
+`AnalyticsPlugin` records one line per completed model step — fresh input, cache read, cache write, output, reasoning, recorded cost — to `$XDG_DATA_HOME/vvoc/analytics/usage-YYYY-MM.jsonl`, attributed with the vvoc version, the OpenCode version (from session telemetry), project, provider, model, and agent. Telemetry never leaves the machine; disable collection with `"plugins": { "analytics": false }` and delete old monthly files freely.
+
+In the TUI you get a live `cache NN%` indicator next to the session prompt (green at 80%+, yellow at 50%+, red below, muted `n/a` before the first cache-eligible step) and a `vvoc vX.Y.Z` label in the sidebar footer. The indicator is per-session and computed in memory.
+
+Retrospective analysis lives in the CLI:
+
+```bash
+vvoc analytics cache-hit-rate --group-by day                       # daily trend
+vvoc analytics cache-hit-rate --group-by vvoc --since 30d         # compare vvoc releases
+vvoc analytics cache-hit-rate --group-by opencode --since 30d     # compare OpenCode upgrades
+vvoc analytics cache-hit-rate --group-by session|model|provider|project|week|month
+vvoc analytics cache-hit-rate --project my-repo --order hit-rate --limit 10 --json
+```
+
+The hit rate is token-weighted: `cacheRead / (cacheRead + cacheWrite + input)` over cache-eligible steps; `COVERAGE` shows the share of steps whose provider reported cache tokens at all, so providers without prompt caching read as `n/a` instead of a misleading `0%`. `--since`/`--until` accept `Nd`/`Nw`/`Nm` or `YYYY-MM-DD`.
+
+Agents can run this analysis conversationally too: the managed `vvoc-usage-analytics` skill answers usage, cache, and cost questions inside a session — including historical comparisons from `opencode.db` that predate the analytics plugin (see Managed Skills).
+
 ### Web Tools
 
 `WebToolsPlugin` exposes exactly two canonical model-facing tools:
@@ -339,6 +361,7 @@ The `context` vvoc plugin toggle defaults to enabled. Disable it with `vvoc plug
 | `vvoc patch-provider stepfun-ai\|codex\|deepseek\|kimi\|alibaba\|all` | Patch OpenCode providers; `codex` adds subscription-safe OpenAI aliases (also accepts `openai`), `deepseek`/`kimi`/`alibaba` add vv- reasoning-effort aliases, `all` patches every provider at once |
 | `vvoc completion` | Install shell completions |
 | `vvoc upgrade` | Upgrade global package and run follow-up sync; sync failure is reported as a partial upgrade |
+| `vvoc analytics cache-hit-rate` | Aggregate persisted cache hit rate by day, week, month, session, model, provider, project, vvoc version, or OpenCode version |
 | `vvoc version` | Print installed version |
 
 Guardian duration overrides use positive whole milliseconds. Both `--timeout-ms` and
@@ -475,6 +498,7 @@ Spec documents           → ./.vvoc/specs/YYYY-MM-DD-<slug>/spec.xml
 Optional design context  → ./.vvoc/specs/YYYY-MM-DD-<slug>/design-context.xml
 Implementation plans     → ./.vvoc/specs/YYYY-MM-DD-<slug>/plan.xml
 Persisted data           → $XDG_DATA_HOME/vvoc/
+Usage analytics          → $XDG_DATA_HOME/vvoc/analytics/usage-YYYY-MM.jsonl  (local-only cache telemetry)
 Repository memory       → ./.vvoc/lessons/*.xml              (lazy vv-reflect fallback)
                            ./.vvoc/runbooks/*.xml             (lazy vv-reflect fallback)
 Session handoff notes   → ./.vvoc/handoff/YYYY-MM-DD-<session-slug>/handoff.xml
@@ -546,7 +570,7 @@ All prompt files are scaffolded by `vvoc install` / `vvoc sync`:
 
 ## Managed Skills
 
-Six workflow skills are scaffolded alongside agents:
+Managed skills come in two families: `vv-*` skills guide the work protocol (spec, plan, execute, review, reflect, handoff), while `vvoc-*` skills operate and observe the vvoc/OpenCode tooling itself. Seven skills are scaffolded alongside agents:
 
 | Skill | When to use it | What it gives you |
 |---|---|---|
@@ -556,6 +580,7 @@ Six workflow skills are scaffolded alongside agents:
 | `vv-review` | You want findings, not fixes | A review-only workflow that reports spec/code issues and stops before implementation |
 | `vv-reflect` | A long development, debugging, ops, or investigation session produced reusable knowledge | Durable notes in existing docs or `.vvoc/lessons` / `.vvoc/runbooks` for future agents |
 | `vv-handoff` | You are ending a session and want the visible context preserved for a future session | A redacted XML note at `.vvoc/handoff/YYYY-MM-DD-<session-slug>/handoff.xml`, without running new checks or collecting fresh context |
+| `vvoc-usage-analytics` | You ask about token usage, cache hit rate, costs, or whether a vvoc/OpenCode upgrade changed caching | An agent-run read-only analysis across `vvoc analytics`, the analytics JSONL, and historical `opencode.db` data (validated SQL snippets included) |
 
 Spec and plan artifacts stay XML so requirements, tasks, acceptance criteria, and dependencies remain easy to grep and review.
 

package/dist/cli.js

@@ -4,7 +4,7 @@
 // START_MODULE_CONTRACT
 //   PURPOSE: Assemble and run the vvoc CLI entrypoint.
 //   SCOPE: Package version lookup, top-level command registration, and main command execution.
-//   DEPENDS: [citty, src/commands/completion.ts, src/commands/config.ts, src/commands/doctor.ts, src/commands/guardian.ts, src/commands/init.ts, src/commands/install.ts, src/commands/launch.ts, src/commands/orchestration.ts, src/commands/patch-provider.ts, src/commands/preset.ts, src/commands/plugin.ts, src/commands/role.ts, src/commands/status.ts, src/commands/sync.ts, src/commands/upgrade.ts, src/commands/version.ts, src/lib/package.ts]
+//   DEPENDS: [citty, src/commands/analytics.ts, src/commands/completion.ts, src/commands/config.ts, src/commands/doctor.ts, src/commands/guardian.ts, src/commands/init.ts, src/commands/install.ts, src/commands/launch.ts, src/commands/orchestration.ts, src/commands/patch-provider.ts, src/commands/preset.ts, src/commands/plugin.ts, src/commands/role.ts, src/commands/status.ts, src/commands/sync.ts, src/commands/upgrade.ts, src/commands/version.ts, src/lib/package.ts]
 //   LINKS: [M-CLI-COMMANDS]
 //   ROLE: SCRIPT
 //   MAP_MODE: LOCALS
@@ -16,9 +16,10 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.2.11 - Aligned meta description with package.json, README, and GitHub repo; license and badge polish.]
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Registered the analytics command in the CLI tree.]
 // END_CHANGE_SUMMARY
 import { defineCommand, runMain } from "citty";
+import analytics from "./commands/analytics.js";
 import completion from "./commands/completion.js";
 import config from "./commands/config.js";
 import doctor from "./commands/doctor.js";
@@ -45,6 +46,7 @@ const main = defineCommand({
         description: "Portable OpenCode workflow toolkit — 6 plugins, managed agents & skills, a spec-to-code pipeline, security, and the vvoc CLI.",
     },
     subCommands: {
+        analytics,
         completion,
         config,
         doctor,

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,+FAA+F;AAC/F,2bAA2b;AAC3b,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,4HAA4H;AAC5H,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,+HAA+H;KAClI;IACD,WAAW,EAAE;QACX,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,MAAM;QACN,aAAa;QACb,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,+FAA+F;AAC/F,sdAAsd;AACtd,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,2GAA2G;AAC3G,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,SAAS,MAAM,yBAAyB,CAAC;AAChD,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,+HAA+H;KAClI;IACD,WAAW,EAAE;QACX,SAAS;QACT,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,MAAM;QACN,aAAa;QACb,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/commands/analytics.d.ts

@@ -0,0 +1,58 @@
+import type { AnalyticsGroupKey, GroupedMetrics } from "../lib/analytics/types.js";
+export declare const GROUP_BY_VALUES: AnalyticsGroupKey[];
+export declare const ORDER_VALUES: readonly ["date", "steps", "hit-rate"];
+export type CacheHitRateRow = {
+    group: string;
+    steps: number;
+    eligibleSteps: number;
+    coverage: number;
+    hitRate: number | null;
+    cacheRead: number;
+    cacheWrite: number;
+    input: number;
+    output: number;
+    reasoning: number;
+};
+/** Orders groups: date desc (default), steps desc, or hit-rate desc with null lowest. */
+export declare function orderGroups(groups: GroupedMetrics[], order: string): GroupedMetrics[];
+/** Projects grouped metrics into JSON/table rows, labeling session groups with known titles. */
+export declare function buildCacheHitRateRows(groups: GroupedMetrics[], groupBy: AnalyticsGroupKey, sessionTitles: Map<string, string>): CacheHitRateRow[];
+/** Session display label: latest known title plus a short session id. */
+export declare function sessionDisplayLabel(sessionID: string, titles: Map<string, string>): string;
+/** Renders cache hit rate rows as a padded ASCII table. */
+export declare function renderCacheHitRateTable(rows: CacheHitRateRow[]): string;
+export declare const cacheHitRateCommand: import("citty").CommandDef<{
+    readonly since: {
+        readonly type: "string";
+        readonly description: "Include records from this date: Nd/Nw/Nm relative or absolute YYYY-MM-DD.";
+    };
+    readonly until: {
+        readonly type: "string";
+        readonly description: "Include records up to this inclusive date (YYYY-MM-DD).";
+    };
+    readonly "group-by": {
+        readonly type: "string";
+        readonly default: "day";
+        readonly description: `Grouping key: ${string}.`;
+    };
+    readonly project: {
+        readonly type: "string";
+        readonly description: "Case-insensitive project directory substring filter.";
+    };
+    readonly limit: {
+        readonly type: "string";
+        readonly description: "Maximum number of rendered groups (default 30).";
+    };
+    readonly order: {
+        readonly type: "string";
+        readonly default: "date";
+        readonly description: `Row ordering: ${string}.`;
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Print machine-readable JSON instead of a table.";
+    };
+}>;
+declare const _default: import("citty").CommandDef<import("citty").ArgsDef>;
+export default _default;

package/dist/commands/analytics.js

@@ -0,0 +1,220 @@
+// FILE: src/commands/analytics.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Provide the vvoc analytics command with the cache-hit-rate aggregation subcommand.
+//   SCOPE: Flag validation, store reading with env override, dedupe/filter/group pipeline, ordering, limits, JSON and table rendering, and the empty state.
+//   DEPENDS: [citty, src/lib/analytics/store.ts, src/lib/analytics/metrics.ts, src/lib/analytics/types.ts]
+//   LINKS: [M-ANALYTICS-STORE, M-ANALYTICS-METRICS, M-CLI-COMMANDS]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   GROUP_BY_VALUES - Supported --group-by values.
+//   ORDER_VALUES - Supported --order values.
+//   cacheHitRateCommand - cache-hit-rate subcommand definition.
+//   orderGroups - Orders grouped metrics by date, steps, or hit rate.
+//   buildCacheHitRateRows - Projects groups and session titles into JSON/table rows.
+//   renderCacheHitRateTable - Renders rows as a padded ASCII table.
+//   default - analytics parent command registering cache-hit-rate.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Added analytics cache-hit-rate CLI command.]
+// END_CHANGE_SUMMARY
+import { defineCommand } from "citty";
+import { readAnalyticsRecords } from "../lib/analytics/store.js";
+import { computeGroupedMetrics, dedupeUsageRecords, filterUsageRecords, formatHitRate, formatTokenCount, parseSinceUntil, } from "../lib/analytics/metrics.js";
+export const GROUP_BY_VALUES = [
+    "session",
+    "day",
+    "week",
+    "month",
+    "model",
+    "provider",
+    "project",
+    "vvoc",
+    "opencode",
+];
+export const ORDER_VALUES = ["date", "steps", "hit-rate"];
+// START_BLOCK_ORDER_AND_ROWS
+/** Orders groups: date desc (default), steps desc, or hit-rate desc with null lowest. */
+export function orderGroups(groups, order) {
+    const sorted = [...groups];
+    if (order === "steps") {
+        sorted.sort((a, b) => b.steps - a.steps);
+    }
+    else if (order === "hit-rate") {
+        sorted.sort((a, b) => (b.hitRate ?? -1) - (a.hitRate ?? -1));
+    }
+    else {
+        sorted.sort((a, b) => (a.key < b.key ? 1 : a.key > b.key ? -1 : 0));
+    }
+    return sorted;
+}
+/** Projects grouped metrics into JSON/table rows, labeling session groups with known titles. */
+export function buildCacheHitRateRows(groups, groupBy, sessionTitles) {
+    return groups.map((group) => ({
+        group: groupBy === "session" ? sessionDisplayLabel(group.key, sessionTitles) : group.key,
+        steps: group.steps,
+        eligibleSteps: group.eligibleSteps,
+        coverage: group.coverage,
+        hitRate: group.hitRate,
+        cacheRead: group.cacheRead,
+        cacheWrite: group.cacheWrite,
+        input: group.input,
+        output: group.output,
+        reasoning: group.reasoning,
+    }));
+}
+/** Session display label: latest known title plus a short session id. */
+export function sessionDisplayLabel(sessionID, titles) {
+    const title = titles.get(sessionID);
+    const short = sessionID.slice(0, 8);
+    return title ? `${title} ${short}` : short;
+}
+// END_BLOCK_ORDER_AND_ROWS
+// START_BLOCK_RENDER_TABLE
+/** Renders cache hit rate rows as a padded ASCII table. */
+export function renderCacheHitRateTable(rows) {
+    const header = [
+        "GROUP",
+        "STEPS",
+        "COVERAGE",
+        "HIT-RATE",
+        "CACHE-READ",
+        "CACHE-WRITE",
+        "FRESH-IN",
+    ];
+    const lines = rows.map((row) => [
+        row.group,
+        String(row.steps),
+        row.coverage.toFixed(2),
+        formatHitRate(row.hitRate),
+        formatTokenCount(row.cacheRead),
+        formatTokenCount(row.cacheWrite),
+        formatTokenCount(row.input),
+    ]);
+    const widths = header.map((_, index) => Math.max(header[index].length, ...lines.map((line) => line[index].length)));
+    const render = (cells) => cells
+        .map((cell, index) => cell.padEnd(widths[index]))
+        .join("  ")
+        .trimEnd();
+    return [render(header), ...lines.map(render)].join("\n");
+}
+// END_BLOCK_RENDER_TABLE
+// START_BLOCK_CACHE_HIT_RATE_COMMAND
+export const cacheHitRateCommand = defineCommand({
+    meta: {
+        name: "cache-hit-rate",
+        description: "Aggregate cache hit rate from persisted step telemetry.",
+    },
+    args: {
+        since: {
+            type: "string",
+            description: "Include records from this date: Nd/Nw/Nm relative or absolute YYYY-MM-DD.",
+        },
+        until: {
+            type: "string",
+            description: "Include records up to this inclusive date (YYYY-MM-DD).",
+        },
+        "group-by": {
+            type: "string",
+            default: "day",
+            description: `Grouping key: ${GROUP_BY_VALUES.join(", ")}.`,
+        },
+        project: {
+            type: "string",
+            description: "Case-insensitive project directory substring filter.",
+        },
+        limit: {
+            type: "string",
+            description: "Maximum number of rendered groups (default 30).",
+        },
+        order: {
+            type: "string",
+            default: "date",
+            description: `Row ordering: ${ORDER_VALUES.join(", ")}.`,
+        },
+        json: {
+            type: "boolean",
+            default: false,
+            description: "Print machine-readable JSON instead of a table.",
+        },
+    },
+    async run({ args }) {
+        const groupBy = String(args["group-by"] ?? "day");
+        if (!GROUP_BY_VALUES.includes(groupBy)) {
+            console.error(`Invalid --group-by value: ${groupBy} (expected one of ${GROUP_BY_VALUES.join(", ")})`);
+            process.exitCode = 1;
+            return;
+        }
+        const order = String(args.order ?? "date");
+        if (!ORDER_VALUES.includes(order)) {
+            console.error(`Invalid --order value: ${order} (expected one of ${ORDER_VALUES.join(", ")})`);
+            process.exitCode = 1;
+            return;
+        }
+        const now = new Date();
+        const since = parseSinceUntil(args.since === undefined ? undefined : String(args.since), now);
+        if (since === null) {
+            console.error(`Invalid --since value: ${String(args.since)} (expected Nd/Nw/Nm or YYYY-MM-DD)`);
+            process.exitCode = 1;
+            return;
+        }
+        const until = parseSinceUntil(args.until === undefined ? undefined : String(args.until), now);
+        if (until === null) {
+            console.error(`Invalid --until value: ${String(args.until)} (expected YYYY-MM-DD or a relative form)`);
+            process.exitCode = 1;
+            return;
+        }
+        const dataHomeOverride = resolveAnalyticsDataHomeOverride();
+        const records = await readAnalyticsRecords({ dataHomeOverride });
+        const usage = dedupeUsageRecords(records.filter((record) => record.kind === "usage"));
+        const sessionTitles = collectSessionTitles(records);
+        const filtered = filterUsageRecords(usage, {
+            since,
+            until,
+            project: args.project === undefined ? undefined : String(args.project),
+        });
+        const parsedLimit = Number.parseInt(String(args.limit ?? "30"), 10);
+        const limit = Math.max(1, Number.isFinite(parsedLimit) ? parsedLimit : 30);
+        const ordered = orderGroups(computeGroupedMetrics(filtered, groupBy), order).slice(0, limit);
+        const rows = buildCacheHitRateRows(ordered, groupBy, sessionTitles);
+        if (args.json === true) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log("No analytics records matched the given filters.");
+            return;
+        }
+        console.log(renderCacheHitRateTable(rows));
+    },
+});
+// END_BLOCK_CACHE_HIT_RATE_COMMAND
+export default defineCommand({
+    meta: {
+        name: "analytics",
+        description: "Inspect persisted vvoc usage analytics.",
+    },
+    subCommands: {
+        "cache-hit-rate": cacheHitRateCommand,
+    },
+});
+/** Resolves the VVOC_ANALYTICS_DATA_HOME data-home override for tests and sandboxes. */
+function resolveAnalyticsDataHomeOverride() {
+    const value = process.env.VVOC_ANALYTICS_DATA_HOME;
+    return value && value.trim() ? value.trim() : undefined;
+}
+/** Keeps the latest title per sessionID from session records. */
+function collectSessionTitles(records) {
+    const titles = new Map();
+    for (const record of records) {
+        if (record.kind === "session") {
+            titles.set(record.sessionID, record.title);
+        }
+    }
+    return titles;
+}
+//# sourceMappingURL=analytics.js.map

package/dist/commands/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/commands/analytics.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { WorkflowPlugin } from "./plugins/workflow/index.js";
 export { SecretsRedactionPlugin } from "./plugins/secrets-redaction.js";
 export { WebToolsPlugin } from "./plugins/web-tools/index.js";
 export { ToolHistoryCompactionPlugin } from "./plugins/tool-history-compaction/index.js";
+export { AnalyticsPlugin } from "./plugins/analytics/index.js";

package/dist/index.js

@@ -2,19 +2,19 @@
 // VERSION: 1.0.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Re-export the public vv-opencode plugin entrypoints from the package root.
-//   SCOPE: Package-root exports for GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, and ToolHistoryCompactionPlugin.
-//   DEPENDS: [src/plugins/guardian/index.ts, src/plugins/hashline-edit/index.ts, src/plugins/model-roles/index.ts, src/plugins/system-context-injection/index.ts, src/plugins/workflow/index.ts, src/plugins/secrets-redaction.ts, src/plugins/web-tools/index.ts, src/plugins/tool-history-compaction/index.ts]
-//   LINKS: [M-PLUGIN-GUARDIAN, M-PLUGIN-HASHLINE-EDIT, M-PLUGIN-MODEL-ROLES, M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-PLUGIN-WORKFLOW, M-PLUGIN-SECRETS-REDACTION, M-PLUGIN-WEB-TOOLS, M-PLUGIN-TOOL-HISTORY-COMPACTION]
+//   SCOPE: Package-root exports for GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, and AnalyticsPlugin.
+//   DEPENDS: [src/plugins/guardian/index.ts, src/plugins/hashline-edit/index.ts, src/plugins/model-roles/index.ts, src/plugins/system-context-injection/index.ts, src/plugins/workflow/index.ts, src/plugins/secrets-redaction.ts, src/plugins/web-tools/index.ts, src/plugins/tool-history-compaction/index.ts, src/plugins/analytics/index.ts]
+//   LINKS: [M-PLUGIN-GUARDIAN, M-PLUGIN-HASHLINE-EDIT, M-PLUGIN-MODEL-ROLES, M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-PLUGIN-WORKFLOW, M-PLUGIN-SECRETS-REDACTION, M-PLUGIN-WEB-TOOLS, M-PLUGIN-TOOL-HISTORY-COMPACTION, M-PLUGIN-ANALYTICS]
 //   ROLE: BARREL
 //   MAP_MODE: SUMMARY
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin - Public plugin exports available from @osovv/vv-opencode.
+//   GuardianPlugin, HashlineEditPlugin, ModelRolesPlugin, SystemContextInjectionPlugin, WorkflowPlugin, SecretsRedactionPlugin, WebToolsPlugin, ToolHistoryCompactionPlugin, AnalyticsPlugin - Public plugin exports available from @osovv/vv-opencode.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.3.0 - Added ToolHistoryCompactionPlugin to the package-root exports.]
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Added AnalyticsPlugin to the package-root exports.]
 // END_CHANGE_SUMMARY
 export { GuardianPlugin } from "./plugins/guardian/index.js";
 export { HashlineEditPlugin } from "./plugins/hashline-edit/index.js";
@@ -24,4 +24,5 @@ export { WorkflowPlugin } from "./plugins/workflow/index.js";
 export { SecretsRedactionPlugin } from "./plugins/secrets-redaction.js";
 export { WebToolsPlugin } from "./plugins/web-tools/index.js";
 export { ToolHistoryCompactionPlugin } from "./plugins/tool-history-compaction/index.js";
+export { AnalyticsPlugin } from "./plugins/analytics/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,iBAAiB;AACjB,wBAAwB;AACxB,wFAAwF;AACxF,iNAAiN;AACjN,iTAAiT;AACjT,qNAAqN;AACrN,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,0MAA0M;AAC1M,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,2FAA2F;AAC3F,qBAAqB;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,iBAAiB;AACjB,wBAAwB;AACxB,wFAAwF;AACxF,kOAAkO;AAClO,iVAAiV;AACjV,yOAAyO;AACzO,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,wPAAwP;AACxP,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,4GAA4G;AAC5G,qBAAqB;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/lib/analytics/metrics.d.ts

@@ -0,0 +1,33 @@
+import type { AnalyticsGroupKey, GroupedMetrics, UsageRecord } from "./types.js";
+/** Keeps only the last occurrence of each partID in array order (last-write-wins). */
+export declare function dedupeUsageRecords(records: UsageRecord[]): UsageRecord[];
+/** ISO week key "YYYY-Wnn" for a UTC timestamp. */
+export declare function isoWeekKey(ts: string): string;
+/** Group key extraction; day/week/month buckets are UTC-based. */
+export declare function groupKeyOf(record: UsageRecord, groupBy: AnalyticsGroupKey): string;
+/**
+ * Aggregates usage records into per-group metrics.
+ * hitRate = sum(cacheRead) / sum(cacheRead + cacheWrite + input) over eligible
+ * steps (cacheRead + cacheWrite > 0); null when a group has no eligible steps.
+ */
+export declare function computeGroupedMetrics(usage: UsageRecord[], groupBy: AnalyticsGroupKey): GroupedMetrics[];
+export type UsageFilter = {
+    /** Inclusive lower date bound "YYYY-MM-DD" (UTC). */
+    since?: string;
+    /** Inclusive upper date bound "YYYY-MM-DD" (UTC). */
+    until?: string;
+    /** Case-insensitive substring matched against projectDirectory. */
+    project?: string;
+};
+/** Applies inclusive date-range and project-substring filters. */
+export declare function filterUsageRecords(usage: UsageRecord[], filter: UsageFilter): UsageRecord[];
+/**
+ * Parses a --since/--until value. Relative "Nd"/"Nw"/"Nm" resolve against `now`
+ * as a UTC date string; absolute "YYYY-MM-DD" passes through. Returns undefined
+ * for undefined input and null for unparseable input.
+ */
+export declare function parseSinceUntil(raw: string | undefined, now: Date): string | undefined | null;
+/** Compact human token count: 999 -> "999"; 1234 -> "1.2k"; 2100000 -> "2.1M". */
+export declare function formatTokenCount(value: number): string;
+/** "n/a" for null; otherwise a percentage with one decimal. */
+export declare function formatHitRate(rate: number | null): string;