vibeusage 0.3.4 → 0.3.5

package/README.md

@@ -5,7 +5,7 @@
 # VibeUsage
 
 **Track token usage across AI coding CLIs.**  
-Local parsing, minimal data collection, and a shareable dashboard for Codex CLI, Claude Code, Gemini CLI, OpenCode, OpenClaw, and more.
+Local parsing, minimal data collection, and a shareable dashboard for Codex CLI, Claude Code, Gemini CLI, OpenCode, Hermes, OpenClaw, and more.
 
 [![npm version](https://img.shields.io/npm/v/vibeusage.svg)](https://www.npmjs.com/package/vibeusage)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
@@ -32,7 +32,7 @@ Give the install guide to ChatGPT, Claude, Codex, or your preferred agent — it
 
 VibeUsage is a **token usage tracker for AI agent CLIs**. It installs lightweight local hooks/plugins, reads usage from local logs or local databases, aggregates usage into time buckets on your machine, and syncs only the data needed to power a dashboard, cost breakdowns, project usage views, public profiles, and leaderboards.
 
-It is currently **macOS-first**, with support focused on real developer workflows around **Codex CLI, Every Code, Claude Code, Gemini CLI, OpenCode, and OpenClaw**.
+It is currently **macOS-first**, with support focused on real developer workflows around **Codex CLI, Every Code, Claude Code, Gemini CLI, OpenCode, Hermes, and OpenClaw**.
 
 ## Why VibeUsage
 
@@ -87,8 +87,19 @@ This is useful when you want to copy an install command from the dashboard or le
 | **Claude Code** | Auto-detected | `Stop` + `SessionEnd` hooks | local hook output |
 | **Gemini CLI** | Auto-detected | `SessionEnd` hook | `~/.gemini/tmp/**/chats/session-*.json` |
 | **OpenCode** | Auto-detected | plugin + local parsing | `~/.local/share/opencode/opencode.db` (legacy message files are fallback only) |
+| **Hermes** | Auto-detected when installed | plugin + local parsing | `~/.vibeusage/tracker/hermes.usage.jsonl` |
 | **OpenClaw** | Auto-detected when installed | session plugin | local sanitized usage ledger |
 
+### Hermes note
+
+Hermes uses a dedicated plugin-ledger path:
+
+**`vibeusage init` installs Hermes plugin → Hermes lifecycle hooks append `~/.vibeusage/tracker/hermes.usage.jsonl` → `vibeusage sync` parses only that ledger**
+
+- no prompt / response content upload
+- no fallback parsing of `~/.hermes/state.db`, `~/.hermes/sessions/`, or trajectory files
+- plugin hooks collect locally only; upload still happens in `vibeusage sync`
+
 ### OpenClaw note
 
 OpenClaw uses a dedicated privacy-preserving path:
@@ -140,12 +151,13 @@ graph LR
     C[Claude Code] --> G
     D[Gemini CLI] --> G
     E[OpenCode] --> G
-    F[OpenClaw] --> G
-    G --> H[Local aggregation into 30-min UTC buckets]
-    H --> I[VibeUsage backend]
-    I --> J[Dashboard]
-    I --> K[Project usage]
-    I --> L[Public profile / leaderboard]
+    F[Hermes] --> G
+    H[OpenClaw] --> G
+    G --> I[Local aggregation into 30-min UTC buckets]
+    I --> J[VibeUsage backend]
+    J --> K[Dashboard]
+    J --> L[Project usage]
+    J --> M[Public profile / leaderboard]
 ```
 
 At a high level:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "bin": {

package/src/commands/init.js

@@ -190,7 +190,7 @@ function renderWelcome() {
       DIVIDER,
       "",
       "This tool will:",
-      "  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode, OpenClaw)",
+      "  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode, Hermes, OpenClaw)",
       "  - Set up lightweight hooks to track your flow state",
       "  - Link your device to your VibeScore account",
       "",

package/src/commands/status.js

@@ -6,6 +6,7 @@ const { readJson } = require("../lib/fs");
 const { collectLocalSubscriptions } = require("../lib/subscriptions");
 const { normalizeState: normalizeUploadState } = require("../lib/upload-throttle");
 const { collectTrackerDiagnostics } = require("../lib/diagnostics");
+const { readLastHermesUsageEvent, resolveHermesUsageLedgerPaths } = require("../lib/hermes-usage-ledger");
 const { createIntegrationContext, listIntegrations, probeIntegrations } = require("../lib/integrations");
 const { resolveTrackerPaths } = require("../lib/tracker-paths");
 
@@ -20,6 +21,7 @@ async function cmdStatus(argv = []) {
   const home = os.homedir();
   const { trackerDir } = await resolveTrackerPaths({ home });
   const configPath = path.join(trackerDir, "config.json");
+  const { ledgerPath: hermesLedgerPath } = resolveHermesUsageLedgerPaths({ trackerDir });
   const queuePath = path.join(trackerDir, "queue.jsonl");
   const queueStatePath = path.join(trackerDir, "queue.state.json");
   const cursorsPath = path.join(trackerDir, "cursors.json");
@@ -80,8 +82,10 @@ async function cmdStatus(argv = []) {
   const claudeProbe = probeByName.get("claude");
   const geminiProbe = probeByName.get("gemini");
   const opencodeProbe = probeByName.get("opencode");
+  const hermesProbe = probeByName.get("hermes");
   const openclawSessionProbe = probeByName.get("openclaw-session");
   const opencodeDbPresent = Boolean((await safeStat(opencodeDbPath))?.isFile?.());
+  const hermesLedgerPresent = Boolean((await safeStat(hermesLedgerPath))?.isFile?.());
   const opencodeSqliteState =
     cursors?.opencodeSqlite && typeof cursors.opencodeSqlite === "object"
       ? cursors.opencodeSqlite
@@ -90,6 +94,15 @@ async function cmdStatus(argv = []) {
     typeof opencodeSqliteState.lastStatus === "string" && opencodeSqliteState.lastStatus.trim()
       ? opencodeSqliteState.lastStatus.trim()
       : "never_checked";
+  const hermesLedgerState =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
+  const hermesLastLedgerEvent = await readLastHermesUsageEvent({ trackerDir });
+  const hermesLastEventAt =
+    typeof hermesLastLedgerEvent?.emitted_at === "string"
+      ? hermesLastLedgerEvent.emitted_at
+      : typeof hermesLedgerState.lastEventAt === "string"
+        ? hermesLedgerState.lastEventAt
+        : "never";
 
   process.stdout.write(
     [
@@ -111,6 +124,9 @@ async function cmdStatus(argv = []) {
       `- Claude plugin: ${renderIntegrationStatus(descriptors.get("claude"), claudeProbe)}`,
       `- Gemini hooks: ${renderIntegrationStatus(descriptors.get("gemini"), geminiProbe)}`,
       `- Opencode plugin: ${renderIntegrationStatus(descriptors.get("opencode"), opencodeProbe)}`,
+      `- Hermes plugin: ${renderIntegrationStatus(descriptors.get("hermes"), hermesProbe)}`,
+      `- Hermes ledger: ${hermesLedgerPresent ? "present" : "missing"}`,
+      `- Hermes last ledger event: ${hermesLastEventAt}`,
       `- OpenCode SQLite DB: ${opencodeDbPresent ? "present" : "missing"}`,
       `- OpenCode SQLite reader: ${opencodeSqliteReader}`,
       `- OpenClaw session plugin: ${renderIntegrationStatus(

package/src/commands/sync.js

@@ -22,6 +22,7 @@ const {
 } = require("../lib/rollout");
 const { drainQueueToCloud } = require("../lib/uploader");
 const { readOpenclawUsageLedger } = require("../lib/openclaw-usage-ledger");
+const { readHermesUsageLedger } = require("../lib/hermes-usage-ledger");
 const { collectLocalSubscriptions } = require("../lib/subscriptions");
 const { createProgress, renderBar, formatNumber, formatBytes } = require("../lib/progress");
 const { syncHeartbeat } = require("../lib/vibeusage-api");
@@ -114,6 +115,12 @@ async function cmdSync(argv) {
       },
     });
 
+    const hermesResult = await parseHermesUsageLedger({
+      trackerDir,
+      cursors,
+      queuePath,
+    });
+
     const openclawResult = opts.fromOpenclaw
       ? await parseOpenclawSanitizedLedger({
           trackerDir,
@@ -369,12 +376,14 @@ async function cmdSync(argv) {
     if (!opts.auto) {
       const totalParsed =
         parseResult.filesProcessed +
+        hermesResult.filesProcessed +
         openclawResult.filesProcessed +
         claudeResult.filesProcessed +
         geminiResult.filesProcessed +
         opencodeResult.filesProcessed;
       const totalBuckets =
         parseResult.bucketsQueued +
+        hermesResult.bucketsQueued +
         openclawResult.bucketsQueued +
         claudeResult.bucketsQueued +
         geminiResult.bucketsQueued +
@@ -436,6 +445,78 @@ function parseArgs(argv) {
 
 module.exports = { cmdSync };
 
+async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
+  const ledgerCursor =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
+  const offset = Math.max(0, Number(ledgerCursor.offset || 0));
+  const { events, endOffset } = await readHermesUsageLedger({ trackerDir, offset });
+
+  const hourlyState = normalizeHourlyState(cursors?.hourly);
+  const touchedBuckets = new Set();
+  let eventsAggregated = 0;
+
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    if (event.type !== "usage") continue;
+    const bucketStart = toUtcHalfHourStart(event.emitted_at);
+    if (!bucketStart) continue;
+
+    const model =
+      typeof event.model === "string" && event.model.trim() ? event.model.trim() : "unknown";
+    const source = "hermes";
+    const delta = {
+      input_tokens: Math.max(0, Number(event.input_tokens || 0)),
+      cached_input_tokens: Math.max(
+        0,
+        Number(event.cache_read_tokens || 0) + Number(event.cache_write_tokens || 0),
+      ),
+      output_tokens: Math.max(0, Number(event.output_tokens || 0)),
+      reasoning_output_tokens: Math.max(0, Number(event.reasoning_tokens || 0)),
+      total_tokens: Math.max(0, Number(event.total_tokens || 0)),
+    };
+
+    if (
+      delta.input_tokens === 0 &&
+      delta.cached_input_tokens === 0 &&
+      delta.output_tokens === 0 &&
+      delta.reasoning_output_tokens === 0 &&
+      delta.total_tokens === 0
+    ) {
+      continue;
+    }
+
+    const bucket = getHourlyBucket(hourlyState, source, model, bucketStart);
+    addTotals(bucket.totals, delta);
+    touchedBuckets.add(bucketKey(source, model, bucketStart));
+    eventsAggregated += 1;
+  }
+
+  const bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
+  const lastUsageEvent = [...events].reverse().find((event) => {
+    if (!event || event.type !== "usage") return false;
+    return Boolean(toUtcHalfHourStart(event.emitted_at));
+  });
+  hourlyState.updatedAt = new Date().toISOString();
+  cursors.hourly = hourlyState;
+  cursors.hermesLedger = {
+    version: 1,
+    offset: endOffset,
+    updatedAt: new Date().toISOString(),
+    lastEventAt:
+      typeof lastUsageEvent?.emitted_at === "string"
+        ? lastUsageEvent.emitted_at
+        : typeof ledgerCursor.lastEventAt === "string"
+          ? ledgerCursor.lastEventAt
+          : null,
+  };
+
+  return {
+    filesProcessed: endOffset > offset ? 1 : 0,
+    eventsAggregated,
+    bucketsQueued,
+  };
+}
+
 async function parseOpenclawSanitizedLedger({ trackerDir, cursors, queuePath }) {
   const ledgerCursor =
     cursors?.openclawLedger && typeof cursors.openclawLedger === "object"

package/src/commands/uninstall.js

@@ -21,6 +21,7 @@ async function cmdUninstall(argv) {
   const claudeConfigExists = await isDir(integrationContext.claude.configDir);
   const geminiConfigExists = await isDir(integrationContext.gemini.configDir);
   const opencodeConfigExists = await isDir(integrationContext.opencode.configDir);
+  const hermesConfigExists = await isDir(integrationContext.hermes.hermesHome);
   const integrationResults = await uninstallIntegrations(integrationContext);
   const resultByName = new Map(integrationResults.map((result) => [result.name, result]));
 
@@ -82,6 +83,15 @@ async function cmdUninstall(argv) {
         noChangeText: "- Opencode plugin: no change",
         skippedText: "- Opencode plugin: skipped (unexpected content)",
       }),
+      renderHookLine({
+        exists: hermesConfigExists,
+        result: resultByName.get("hermes"),
+        missingText: `- Hermes plugin: skipped (${integrationContext.hermes.hermesHome} not found)`,
+        removedText: (result) =>
+          `- Hermes plugin removed: ${result.detail || integrationContext.hermes.pluginDir}`,
+        noChangeText: "- Hermes plugin: no change",
+        skippedText: "- Hermes plugin: skipped (unexpected content)",
+      }),
       renderHookLine({
         exists: true,
         result: resultByName.get("openclaw-session"),

package/src/lib/diagnostics.js

@@ -3,6 +3,7 @@ const path = require("node:path");
 const fs = require("node:fs/promises");
 
 const { readJson } = require("./fs");
+const { readLastHermesUsageEvent, resolveHermesUsageLedgerPaths } = require("./hermes-usage-ledger");
 const { normalizeState: normalizeUploadState } = require("./upload-throttle");
 const { createIntegrationContext, probeIntegrations } = require("./integrations");
 
@@ -25,6 +26,7 @@ async function collectTrackerDiagnostics({
   });
   const trackerDir = integrationContext.trackerPaths.trackerDir;
   const configPath = path.join(trackerDir, "config.json");
+  const { ledgerPath: hermesLedgerPath } = resolveHermesUsageLedgerPaths({ trackerDir });
   const queuePath = path.join(trackerDir, "queue.jsonl");
   const queueStatePath = path.join(trackerDir, "queue.state.json");
   const cursorsPath = path.join(trackerDir, "cursors.json");
@@ -45,7 +47,10 @@ async function collectTrackerDiagnostics({
   const probeByName = new Map(probes.map((probe) => [probe.name, probe]));
   const opencodeSqliteCursor =
     cursors?.opencodeSqlite && typeof cursors.opencodeSqlite === "object" ? cursors.opencodeSqlite : {};
+  const hermesLedgerCursor =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
   const opencodeDbStat = await safeStat(opencodeDbPath);
+  const hermesLedgerStat = await safeStat(hermesLedgerPath);
 
   const queueSize = await safeStatSize(queuePath);
   const offsetBytes = Number(queueState.offset || 0);
@@ -60,6 +65,7 @@ async function collectTrackerDiagnostics({
   const claudeProbe = probeByName.get("claude");
   const geminiProbe = probeByName.get("gemini");
   const opencodeProbe = probeByName.get("opencode");
+  const hermesProbe = probeByName.get("hermes");
   const openclawSessionProbe = probeByName.get("openclaw-session");
 
   const codexNotify = Array.isArray(codexProbe?.currentNotify)
@@ -73,6 +79,7 @@ async function collectTrackerDiagnostics({
     ? new Date(uploadThrottle.lastSuccessMs).toISOString()
     : null;
   const autoRetryAt = parseEpochMsToIso(autoRetry?.retryAtMs);
+  const hermesLastLedgerEvent = await readLastHermesUsageEvent({ trackerDir });
 
   return {
     ok: true,
@@ -92,6 +99,9 @@ async function collectTrackerDiagnostics({
       claude_config: redactValue(integrationContext.claude.settingsPath, home),
       gemini_config: redactValue(integrationContext.gemini.settingsPath, home),
       opencode_config: redactValue(integrationContext.opencode.configDir, home),
+      hermes_home: redactValue(integrationContext.hermes.hermesHome, home),
+      hermes_plugin_dir: redactValue(integrationContext.hermes.pluginDir, home),
+      hermes_ledger: redactValue(hermesLedgerPath, home),
     },
     config: {
       base_url: typeof config?.baseUrl === "string" ? config.baseUrl : null,
@@ -131,6 +141,22 @@ async function collectTrackerDiagnostics({
           ? opencodeSqliteCursor.lastErrorCode
           : null,
     },
+    hermes: {
+      ledger_present: Boolean(hermesLedgerStat?.isFile?.()),
+      ledger_size_bytes: hermesLedgerStat?.isFile?.() ? Number(hermesLedgerStat.size || 0) : 0,
+      ledger_offset:
+        Number.isFinite(Number(hermesLedgerCursor.offset)) ? Math.max(0, Number(hermesLedgerCursor.offset)) : 0,
+      ledger_updated_at:
+        typeof hermesLedgerCursor.updatedAt === "string" ? hermesLedgerCursor.updatedAt : null,
+      last_event_at:
+        typeof hermesLastLedgerEvent?.emitted_at === "string"
+          ? hermesLastLedgerEvent.emitted_at
+          : typeof hermesLedgerCursor.lastEventAt === "string"
+            ? hermesLedgerCursor.lastEventAt
+            : null,
+      last_event_type:
+        typeof hermesLastLedgerEvent?.type === "string" ? hermesLastLedgerEvent.type : null,
+    },
     notify: {
       last_notify: lastNotify,
       last_openclaw_triggered_sync: lastOpenclawSync,
@@ -147,6 +173,8 @@ async function collectTrackerDiagnostics({
       gemini_hook_configured: Boolean(geminiProbe?.configured),
       opencode_plugin_status: opencodeProbe?.status || "unknown",
       opencode_plugin_configured: Boolean(opencodeProbe?.configured),
+      hermes_plugin_status: hermesProbe?.status || "unknown",
+      hermes_plugin_configured: Boolean(hermesProbe?.configured),
       openclaw_session_plugin_status: openclawSessionProbe?.status || "unknown",
       openclaw_session_plugin_configured: Boolean(openclawSessionProbe?.configured),
       openclaw_session_plugin_linked: Boolean(openclawSessionProbe?.linked),

package/src/lib/hermes-config.js

@@ -0,0 +1,172 @@
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+const fssync = require("node:fs");
+
+const { ensureDir, writeFileAtomic } = require("./fs");
+
+const HERMES_PLUGIN_ID = "vibeusage";
+const HERMES_PLUGIN_MARKER = "VIBEUSAGE_HERMES_PLUGIN";
+const HERMES_PLUGIN_TEMPLATE_VERSION = 1;
+
+function resolveHermesHome({ home = os.homedir(), env = process.env } = {}) {
+  const explicit = typeof env.HERMES_HOME === "string" ? env.HERMES_HOME.trim() : "";
+  if (explicit) return path.resolve(explicit);
+  return path.join(home, ".hermes");
+}
+
+function resolveHermesPluginPaths({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  if (!trackerDir) throw new Error("trackerDir is required");
+
+  const hermesHome = resolveHermesHome({ home, env });
+  const pluginDir = path.join(hermesHome, "plugins", HERMES_PLUGIN_ID);
+  return {
+    hermesHome,
+    pluginId: HERMES_PLUGIN_ID,
+    pluginDir,
+    pluginYamlPath: path.join(pluginDir, "plugin.yaml"),
+    pluginInitPath: path.join(pluginDir, "__init__.py"),
+    ledgerPath: path.join(trackerDir, "hermes.usage.jsonl"),
+  };
+}
+
+async function probeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const expectedYaml = buildHermesPluginYaml();
+  const expectedInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
+  const hermesHomeExists = await pathExists(paths.hermesHome);
+
+  if (!hermesHomeExists) {
+    return {
+      configured: false,
+      status: "not_installed",
+      detail: "Hermes home not found",
+      initPreviewStatus: "updated",
+      initPreviewDetail: "Will install plugin",
+      ...paths,
+    };
+  }
+
+  const pluginDirExists = await pathExists(paths.pluginDir);
+  if (!pluginDirExists) {
+    return {
+      configured: false,
+      status: "not_installed",
+      detail: "Plugin not installed",
+      initPreviewStatus: "updated",
+      initPreviewDetail: "Will install plugin",
+      ...paths,
+    };
+  }
+
+  const yamlState = await readTextStrict(paths.pluginYamlPath);
+  const initState = await readTextStrict(paths.pluginInitPath);
+  if (yamlState.status === "error" || initState.status === "error") {
+    return {
+      configured: false,
+      status: "unreadable",
+      detail: yamlState.error || initState.error || "Plugin unreadable",
+      ...paths,
+    };
+  }
+  if (yamlState.status === "missing" || initState.status === "missing") {
+    return {
+      configured: false,
+      status: "drifted",
+      detail: "Run vibeusage init to reconcile plugin",
+      ...paths,
+    };
+  }
+
+  const configured = yamlState.value === expectedYaml && initState.value === expectedInit;
+  return {
+    configured,
+    status: configured ? "ready" : "drifted",
+    detail: configured ? "Plugin installed" : "Run vibeusage init to reconcile plugin",
+    ...paths,
+  };
+}
+
+async function installHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const nextYaml = buildHermesPluginYaml();
+  const nextInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
+  const currentYaml = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
+  const currentInit = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
+  const changed = currentYaml !== nextYaml || currentInit !== nextInit;
+
+  await ensureDir(paths.pluginDir);
+  await writeFileAtomic(paths.pluginYamlPath, nextYaml);
+  await writeFileAtomic(paths.pluginInitPath, nextInit);
+  return { configured: true, changed, ...paths };
+}
+
+async function removeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const hadPluginDir = await pathExists(paths.pluginDir);
+  if (!hadPluginDir) {
+    return { removed: false, skippedReason: "plugin-missing", ...paths };
+  }
+
+  const yamlText = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
+  const initText = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
+  const markerPresent = hasHermesPluginMarker(yamlText) && hasHermesPluginMarker(initText);
+  if (!markerPresent) {
+    return { removed: false, skippedReason: "unexpected-content", ...paths };
+  }
+
+  await fs.rm(paths.pluginDir, { recursive: true, force: true }).catch(() => {});
+  return { removed: true, ...paths };
+}
+
+function buildHermesPluginYaml() {
+  return readTemplateFile("plugin.yaml");
+}
+
+function buildHermesPluginInit({ ledgerPath }) {
+  const safeLedgerPath = typeof ledgerPath === "string" ? ledgerPath : "";
+  return readTemplateFile("__init__.py").replace("__LEDGER_PATH__", safeLedgerPath);
+}
+
+function hasHermesPluginMarker(text) {
+  return typeof text === "string" && text.includes(HERMES_PLUGIN_MARKER);
+}
+
+async function readTextStrict(filePath) {
+  try {
+    return { status: "ok", value: await fs.readFile(filePath, "utf8"), error: null };
+  } catch (err) {
+    if (err?.code === "ENOENT" || err?.code === "ENOTDIR") {
+      return { status: "missing", value: null, error: null };
+    }
+    return { status: "error", value: null, error: err?.message || String(err) };
+  }
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.stat(targetPath);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+function readTemplateFile(name) {
+  const templatePath = path.join(__dirname, "..", "templates", "hermes-vibeusage-plugin", name);
+  return fssync.readFileSync(templatePath, "utf8");
+}
+
+module.exports = {
+  HERMES_PLUGIN_ID,
+  HERMES_PLUGIN_MARKER,
+  HERMES_PLUGIN_TEMPLATE_VERSION,
+  resolveHermesHome,
+  resolveHermesPluginPaths,
+  probeHermesPlugin,
+  installHermesPlugin,
+  removeHermesPlugin,
+  buildHermesPluginYaml,
+  buildHermesPluginInit,
+  hasHermesPluginMarker,
+};

package/src/lib/hermes-usage-ledger.js

@@ -0,0 +1,123 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const ALLOWED_HERMES_LEDGER_FIELDS = [
+  "version",
+  "type",
+  "source",
+  "session_id",
+  "platform",
+  "model",
+  "provider",
+  "api_mode",
+  "api_call_count",
+  "input_tokens",
+  "output_tokens",
+  "cache_read_tokens",
+  "cache_write_tokens",
+  "reasoning_tokens",
+  "total_tokens",
+  "finish_reason",
+  "emitted_at",
+];
+
+function resolveHermesUsageLedgerPaths({ trackerDir } = {}) {
+  if (!trackerDir) throw new Error("trackerDir is required");
+  return {
+    ledgerPath: path.join(trackerDir, "hermes.usage.jsonl"),
+  };
+}
+
+async function readHermesUsageLedger({ trackerDir, offset = 0 } = {}) {
+  const { ledgerPath } = resolveHermesUsageLedgerPaths({ trackerDir });
+  const buffer = await fs.readFile(ledgerPath).catch((err) => {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  });
+
+  if (!buffer) {
+    return { events: [], endOffset: 0 };
+  }
+
+  const startOffset = Math.max(0, Number(offset || 0));
+  const fileEndOffset = buffer.length;
+  if (startOffset >= fileEndOffset) {
+    return { events: [], endOffset: fileEndOffset };
+  }
+
+  const newlineIndex = buffer.lastIndexOf(0x0a);
+  if (newlineIndex < startOffset) {
+    return { events: [], endOffset: startOffset };
+  }
+
+  const endOffset = newlineIndex + 1;
+  const raw = buffer.subarray(startOffset, endOffset).toString("utf8");
+  const events = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch (_err) {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .map(stripToAllowedHermesFields)
+    .filter(isHermesLedgerEvent);
+
+  return { events, endOffset };
+}
+
+async function readLastHermesUsageEvent({ trackerDir } = {}) {
+  const { ledgerPath } = resolveHermesUsageLedgerPaths({ trackerDir });
+  const text = await fs.readFile(ledgerPath, "utf8").catch((err) => {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  });
+  if (!text) return null;
+
+  const lines = text.split(/\r?\n/);
+  for (let idx = lines.length - 1; idx >= 0; idx -= 1) {
+    const line = String(lines[idx] || "").trim();
+    if (!line) continue;
+    try {
+      const parsed = stripToAllowedHermesFields(JSON.parse(line));
+      if (isHermesLedgerEvent(parsed)) return parsed;
+    } catch (_err) {
+      // ignore malformed line
+    }
+  }
+  return null;
+}
+
+function stripToAllowedHermesFields(event) {
+  const out = {};
+  for (const field of ALLOWED_HERMES_LEDGER_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(event, field)) continue;
+    out[field] = event[field];
+  }
+  return out;
+}
+
+function isHermesLedgerEvent(event) {
+  if (!event || typeof event !== "object") return false;
+  if (normalizeString(event.source) !== "hermes") return false;
+  const type = normalizeString(event.type);
+  if (!type || !["session_start", "usage", "session_end"].includes(type)) return false;
+  return true;
+}
+
+function normalizeString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+module.exports = {
+  ALLOWED_HERMES_LEDGER_FIELDS,
+  resolveHermesUsageLedgerPaths,
+  readHermesUsageLedger,
+  readLastHermesUsageEvent,
+};

package/src/lib/integrations/context.js

@@ -9,6 +9,7 @@ const {
 } = require("../gemini-config");
 const { resolveOpencodeConfigDir } = require("../opencode-config");
 const { resolveOpenclawSessionPluginPaths } = require("../openclaw-session-plugin");
+const { resolveHermesPluginPaths } = require("../hermes-config");
 const { resolveTrackerPaths } = require("../tracker-paths");
 
 async function createIntegrationContext({
@@ -57,6 +58,11 @@ async function createIntegrationContext({
     opencode: {
       configDir: opencodeConfigDir,
     },
+    hermes: resolveHermesPluginPaths({
+      home,
+      env,
+      trackerDir: resolvedTrackerPaths.trackerDir,
+    }),
     openclawSession: resolveOpenclawSessionPluginPaths({
       home,
       trackerDir: resolvedTrackerPaths.trackerDir,

package/src/lib/integrations/hermes.js

@@ -0,0 +1,96 @@
+const { isDir } = require("./utils");
+const { probeHermesPlugin, installHermesPlugin, removeHermesPlugin } = require("../hermes-config");
+
+module.exports = {
+  name: "hermes",
+  summaryLabel: "Hermes Plugin",
+  statusLabel: "Hermes plugin",
+  async probe(ctx) {
+    const hermesHomeExists = await isDir(ctx.hermes.hermesHome);
+    if (!hermesHomeExists) {
+      return baseProbe(this, {
+        status: "not_installed",
+        detail: "Hermes home not found",
+        initPreviewStatus: "skipped",
+        initPreviewDetail: "Hermes not detected",
+      });
+    }
+
+    const state = await probeHermesPlugin({
+      home: ctx.home,
+      env: ctx.env,
+      trackerDir: ctx.trackerPaths.trackerDir,
+    });
+    return baseProbe(this, state);
+  },
+  async install(ctx) {
+    if (!(await isDir(ctx.hermes.hermesHome))) {
+      return action(this, "skipped", false, "Hermes home not found");
+    }
+    const result = await installHermesPlugin({
+      home: ctx.home,
+      env: ctx.env,
+      trackerDir: ctx.trackerPaths.trackerDir,
+    });
+    return action(
+      this,
+      result.changed ? "installed" : "set",
+      Boolean(result.changed),
+      result.changed ? "Plugin installed" : "Plugin already installed",
+    );
+  },
+  async uninstall(ctx) {
+    if (!(await isDir(ctx.hermes.hermesHome))) {
+      return action(this, "skipped", false, "Hermes home not found", {
+        skippedReason: "hermes-home-missing",
+      });
+    }
+    const result = await removeHermesPlugin({
+      home: ctx.home,
+      env: ctx.env,
+      trackerDir: ctx.trackerPaths.trackerDir,
+    });
+    if (result.removed) {
+      return action(this, "removed", true, result.pluginDir || ctx.hermes.pluginDir);
+    }
+    if (result.skippedReason === "plugin-missing") {
+      return action(this, "unchanged", false, "no change", {
+        skippedReason: result.skippedReason,
+      });
+    }
+    if (result.skippedReason === "unexpected-content") {
+      return action(this, "skipped", false, "unexpected content", {
+        skippedReason: result.skippedReason,
+      });
+    }
+    return action(this, "skipped", false, "Hermes home not found", {
+      skippedReason: result.skippedReason || "hermes-home-missing",
+    });
+  },
+  renderStatusValue(probe) {
+    if (probe.status === "ready") return "set";
+    if (probe.status === "not_installed") return "unset";
+    return probe.status;
+  },
+};
+
+function baseProbe(descriptor, values) {
+  return {
+    name: descriptor.name,
+    summaryLabel: descriptor.summaryLabel,
+    statusLabel: descriptor.statusLabel,
+    configured: false,
+    ...values,
+  };
+}
+
+function action(descriptor, status, changed, detail, extras = {}) {
+  return {
+    name: descriptor.name,
+    label: descriptor.summaryLabel,
+    status,
+    changed,
+    detail,
+    ...extras,
+  };
+}

package/src/lib/integrations/index.js

@@ -4,6 +4,7 @@ const everyCode = require("./every-code");
 const claude = require("./claude");
 const gemini = require("./gemini");
 const opencode = require("./opencode");
+const hermes = require("./hermes");
 const openclawSession = require("./openclaw-session");
 
 const INTEGRATIONS = [
@@ -12,6 +13,7 @@ const INTEGRATIONS = [
   claude,
   gemini,
   opencode,
+  hermes,
   openclawSession,
 ];
 

package/src/templates/hermes-vibeusage-plugin/__init__.py

@@ -0,0 +1,75 @@
+# VIBEUSAGE_HERMES_PLUGIN
+# Generated by VibeUsage. Do not edit manually.
+import json
+import os
+from datetime import datetime, timezone
+
+LEDGER_PATH = "__LEDGER_PATH__"
+SOURCE = "hermes"
+VERSION = 1
+
+
+def _iso_now():
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _safe_int(value):
+    try:
+        return max(0, int(value or 0))
+    except Exception:
+        return 0
+
+
+def _append_record(record):
+    try:
+        os.makedirs(os.path.dirname(LEDGER_PATH), exist_ok=True)
+        with open(LEDGER_PATH, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception:
+        return None
+    return None
+
+
+def _base_record(record_type, session_id="", platform="", model="", provider=""):
+    return {
+        "version": VERSION,
+        "type": str(record_type or ""),
+        "source": SOURCE,
+        "session_id": str(session_id or ""),
+        "platform": str(platform or ""),
+        "model": str(model or ""),
+        "provider": str(provider or ""),
+        "emitted_at": _iso_now(),
+    }
+
+
+def on_session_start(session_id="", model="", platform="", **_kwargs):
+    return _append_record(_base_record("session_start", session_id=session_id, platform=platform, model=model))
+
+
+def post_api_request(session_id="", platform="", model="", provider="", api_mode="", api_call_count=0, finish_reason="", usage=None, **_kwargs):
+    if not isinstance(usage, dict):
+        return None
+    record = _base_record("usage", session_id=session_id, platform=platform, model=model, provider=provider)
+    record.update({
+        "api_mode": str(api_mode or ""),
+        "api_call_count": _safe_int(api_call_count),
+        "input_tokens": _safe_int(usage.get("input_tokens")),
+        "output_tokens": _safe_int(usage.get("output_tokens")),
+        "cache_read_tokens": _safe_int(usage.get("cache_read_tokens")),
+        "cache_write_tokens": _safe_int(usage.get("cache_write_tokens")),
+        "reasoning_tokens": _safe_int(usage.get("reasoning_tokens")),
+        "total_tokens": _safe_int(usage.get("total_tokens")),
+        "finish_reason": str(finish_reason or ""),
+    })
+    return _append_record(record)
+
+
+def on_session_end(session_id="", model="", platform="", **_kwargs):
+    return _append_record(_base_record("session_end", session_id=session_id, platform=platform, model=model))
+
+
+def register(ctx):
+    ctx.register_hook("on_session_start", on_session_start)
+    ctx.register_hook("post_api_request", post_api_request)
+    ctx.register_hook("on_session_end", on_session_end)

package/src/templates/hermes-vibeusage-plugin/plugin.yaml

@@ -0,0 +1,9 @@
+# VIBEUSAGE_HERMES_PLUGIN
+name: vibeusage
+version: "1"
+description: "VibeUsage Hermes usage ledger plugin"
+author: "VibeUsage"
+provides_hooks:
+  - "on_session_start"
+  - "post_api_request"
+  - "on_session_end"