@cgaravitoq/aiusage 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Garavito Quispe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @cgaravitoq/aiusage
+
+Report local token usage to an [aiusage](https://github.com/cgaravitoq/aiusage) instance.
+
+The collector requires Bun 1.4.0 or newer, which ships `node:sqlite`, and supports macOS and Linux.
+Windows is unsupported, and npm refuses the install there.
+
+## Install
+
+```bash
+bun add -g @cgaravitoq/aiusage
+aiusage install --url <url> --key <key>
+```
+
+`install` writes `~/.config/aiusage/config.json` with mode 600 and a launchd agent on macOS or a systemd user timer on Linux that runs `aiusage collect` every five minutes.
+Pass `--timezone <zone>` to override the machine's IANA timezone, or `--dry-run` to print the files without writing them.
+Non-dry `install` refuses Bun paths containing `/install/cache/` or a `bunx-<digits>-<package>` directory segment, because those paths can disappear while a schedule still points to them.
+
+Running `install` with a new url adds a target and keeps the existing ones, and running it again with a configured url replaces that target's key, so one machine can feed a personal instance and a team board at once.
+The config is `{ "targets": [{ "url": "...", "key": "..." }], "timezone": "..." }`, and the single-target shape written before targets existed still reads.
+
+## Report
+
+`aiusage collect` reports the last 14 calendar days to `POST /api/report` of every configured target.
+The rows come from ccusage for every agent it detects, plus two sources ccusage has no adapter for: the Antigravity CLI conversations under `~/.gemini/antigravity-cli/conversations`, reported as `antigravity`, and the Devin CLI transcripts under `~/.local/share/devin/cli/transcripts`, reported as `devin` with the effort suffix of each model collapsed into its LiteLLM name.
+Both are priced from the LiteLLM table cached for a day at `~/.config/aiusage/litellm-prices.json`.
+
+`collect` prints one `accepted <n> days for <machine> at <url>` line per target, where `<n>` is the number of usage rows the instance stored rather than a count of calendar days, and exits 1 when any target rejects the report.
+
+## Upgrade
+
+```bash
+bun add -g @cgaravitoq/aiusage@latest
+aiusage install --url <url> --key <existing-key>
+```
+
+On macOS, run `launchctl bootout gui/<uid>/dev.aiusage.collector`, then run the printed `launchctl bootstrap` command.
+On Linux, run `systemctl --user daemon-reload`, then run the printed `systemctl --user enable --now aiusage.timer` command.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cgaravitoq/aiusage",
+  "version": "0.4.0",
+  "description": "Report local ccusage token usage to an aiusage instance",
+  "type": "module",
+  "bin": {
+    "aiusage": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "!src/**/*.spec.ts",
+    "!src/test/**"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cgaravitoq/aiusage.git",
+    "directory": "packages/collector"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --exclude src/package.e2e.spec.ts",
+    "test:package": "vitest run src/package.e2e.spec.ts",
+    "test:watch": "vitest --exclude src/package.e2e.spec.ts"
+  },
+  "dependencies": {
+    "ccusage": "20.0.20",
+    "commander": "^15.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  }
+}

package/src/antigravity.ts

@@ -0,0 +1,191 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { type ReaderSteps, readDirectorySteps } from "./devin";
+
+export interface AntigravityStep {
+  at: Date;
+  cacheRead: number;
+  input: number;
+  model: string;
+  output: number;
+}
+
+export interface AntigravityUsage {
+  failures: string[];
+  steps: AntigravityStep[];
+}
+
+interface ProtoField {
+  number: number;
+  value: bigint | Uint8Array;
+}
+
+interface RawStep {
+  at: Date;
+  cacheRead: number;
+  input: number;
+  modelCode: number;
+  output: number;
+}
+
+const unknownModel = "gemini-unknown";
+
+const usageField = 9;
+const createdField = 1;
+const generationField = 1;
+const generationUsageField = 4;
+const generationModelField = 19;
+const modelCodeField = 1;
+const inputField = 2;
+const outputField = 3;
+const cacheReadField = 5;
+
+export function antigravityConversationsDir(home: string): string {
+  return resolve(home, ".gemini", "antigravity-cli", "conversations");
+}
+
+function decodeMessage(bytes: Uint8Array): ProtoField[] {
+  const fields: ProtoField[] = [];
+  let offset = 0;
+  const truncated = (): never => {
+    throw new Error("truncated protobuf message");
+  };
+  const varint = (): bigint => {
+    let result = 0n;
+    let shift = 0n;
+    for (;;) {
+      if (offset >= bytes.length) {
+        truncated();
+      }
+      const byte = bytes[offset++];
+      result |= BigInt(byte & 0x7f) << shift;
+      if (byte < 0x80) {
+        return result;
+      }
+      shift += 7n;
+    }
+  };
+  const bytesOf = (length: number): Uint8Array => {
+    if (offset + length > bytes.length) {
+      truncated();
+    }
+    const slice = bytes.subarray(offset, offset + length);
+    offset += length;
+    return slice;
+  };
+  while (offset < bytes.length) {
+    const tag = varint();
+    const number = Number(tag >> 3n);
+    const wireType = Number(tag & 7n);
+    if (wireType === 0) {
+      fields.push({ number, value: varint() });
+    } else if (wireType === 1) {
+      fields.push({ number, value: bytesOf(8) });
+    } else if (wireType === 2) {
+      fields.push({ number, value: bytesOf(Number(varint())) });
+    } else if (wireType === 5) {
+      fields.push({ number, value: bytesOf(4) });
+    } else {
+      throw new Error(`unsupported protobuf wire type ${wireType}`);
+    }
+  }
+  return fields;
+}
+
+function nested(fields: ProtoField[], number: number): ProtoField[] | null {
+  const field = fields.find(
+    (candidate) =>
+      candidate.number === number && candidate.value instanceof Uint8Array,
+  );
+  return field === undefined ? null : decodeMessage(field.value as Uint8Array);
+}
+
+function integer(fields: ProtoField[], number: number): number | null {
+  const field = fields.find(
+    (candidate) =>
+      candidate.number === number && typeof candidate.value === "bigint",
+  );
+  return field === undefined ? null : Number(field.value);
+}
+
+function text(fields: ProtoField[], number: number): string | null {
+  const field = fields.find(
+    (candidate) =>
+      candidate.number === number && candidate.value instanceof Uint8Array,
+  );
+  return field === undefined
+    ? null
+    : new TextDecoder().decode(field.value as Uint8Array);
+}
+
+function openReadOnly(file: string): DatabaseSync {
+  const location = existsSync(`${file}-wal`)
+    ? file
+    : `file:${file.split("/").map(encodeURIComponent).join("/")}?immutable=1`;
+  const db = new DatabaseSync(location, { readOnly: true });
+  db.exec("PRAGMA busy_timeout = 5000");
+  return db;
+}
+
+function readConversation(
+  file: string,
+  names: Map<number, string>,
+): ReaderSteps<RawStep> {
+  const db = openReadOnly(file);
+  try {
+    const generations = db.prepare("SELECT data FROM gen_metadata").all() as {
+      data: Uint8Array;
+    }[];
+    for (const row of generations) {
+      const generation = nested(decodeMessage(row.data), generationField);
+      const usage =
+        generation === null ? null : nested(generation, generationUsageField);
+      const code = usage === null ? null : integer(usage, modelCodeField);
+      const name =
+        generation === null ? null : text(generation, generationModelField);
+      if (code !== null && name !== null) {
+        names.set(code, name);
+      }
+    }
+    const steps: RawStep[] = [];
+    const rows = db
+      .prepare("SELECT metadata FROM steps WHERE metadata IS NOT NULL")
+      .all() as { metadata: Uint8Array }[];
+    for (const row of rows) {
+      const fields = decodeMessage(row.metadata);
+      const usage = nested(fields, usageField);
+      const created = nested(fields, createdField);
+      const seconds = created === null ? null : integer(created, 1);
+      if (usage === null || seconds === null) {
+        continue;
+      }
+      steps.push({
+        at: new Date(seconds * 1000),
+        cacheRead: integer(usage, cacheReadField) ?? 0,
+        input: integer(usage, inputField) ?? 0,
+        modelCode: integer(usage, modelCodeField) ?? 0,
+        output: integer(usage, outputField) ?? 0,
+      });
+    }
+    return { failures: [], steps };
+  } finally {
+    db.close();
+  }
+}
+
+export async function readAntigravitySteps(
+  dir: string,
+): Promise<AntigravityUsage> {
+  const names = new Map<number, string>();
+  const read = await readDirectorySteps(dir, ".db", async (file) =>
+    readConversation(file, names),
+  );
+  return {
+    failures: read.failures,
+    steps: read.steps.map(({ modelCode, ...step }) => ({
+      ...step,
+      model: names.get(modelCode) ?? unknownModel,
+    })),
+  };
+}

package/src/ccusage.ts

@@ -0,0 +1,91 @@
+import { createRequire } from "node:module";
+import { z } from "zod";
+import type { CommandRunner } from "./command";
+
+const modelBreakdown = z.object({
+  cacheCreationTokens: z.int(),
+  cacheReadTokens: z.int(),
+  cost: z.number(),
+  inputTokens: z.int(),
+  modelName: z.string(),
+  outputTokens: z.int(),
+});
+
+const agentUsage = z.object({
+  agent: z.string(),
+  modelBreakdowns: z.array(modelBreakdown),
+});
+
+const dailyUsage = z.object({
+  agents: z.array(agentUsage),
+  period: z.string(),
+});
+
+const ccusageDaily = z.object({
+  daily: z.array(dailyUsage),
+});
+
+export type CcusageDaily = z.infer<typeof ccusageDaily>;
+
+const windowDays = 14;
+const commandTimeoutMs = 60_000;
+
+export function parseCcusageDaily(source: string): CcusageDaily {
+  return ccusageDaily.parse(JSON.parse(source));
+}
+
+export function ccusageCliPath(): string {
+  return createRequire(import.meta.url).resolve("ccusage/src/cli.js");
+}
+
+export function calendarDate(at: Date, timezone: string): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(at);
+}
+
+export function windowStart(today: Date, timezone: string): string {
+  const [year, month, day] = calendarDate(today, timezone)
+    .split("-")
+    .map(Number);
+  const start = new Date(Date.UTC(year, month - 1, day - (windowDays - 1)));
+  return start.toISOString().slice(0, 10);
+}
+
+export function sinceArgument(today: Date, timezone: string): string {
+  return windowStart(today, timezone).replaceAll("-", "");
+}
+
+export function ccusageArguments(since: string, timezone: string): string[] {
+  return [
+    "daily",
+    "--json",
+    "--breakdown",
+    "--by-agent",
+    "-z",
+    timezone,
+    "--since",
+    since,
+  ];
+}
+
+export async function readCcusageDaily(
+  runner: CommandRunner,
+  since: string,
+  timezone: string,
+): Promise<CcusageDaily> {
+  const result = await runner(
+    process.execPath,
+    [ccusageCliPath(), ...ccusageArguments(since, timezone)],
+    commandTimeoutMs,
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `ccusage exited with ${result.exitCode}: ${result.stderr.trim()}`,
+    );
+  }
+  return parseCcusageDaily(result.stdout);
+}

package/src/cli.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { collect } from "./collect";
+import type { CommandRunner } from "./command";
+import type { Fetcher } from "./http";
+import { install } from "./install";
+import { type MachineIdentity, readMachineIdentity } from "./machine";
+import { type CollectorEnv, processEnv } from "./paths";
+
+export interface CliIo {
+  stderr: (line: string) => void;
+  stdout: (line: string) => void;
+  cliPath?: string;
+  env?: CollectorEnv;
+  execPath?: string;
+  fetcher?: Fetcher;
+  identity?: MachineIdentity;
+  platform?: NodeJS.Platform;
+  runner?: CommandRunner;
+  today?: Date;
+  uid?: number;
+}
+
+interface InstallCommandOptions {
+  dryRun: boolean;
+  key: string;
+  timezone?: string;
+  url: string;
+}
+
+async function runCollect(io: CliIo): Promise<number> {
+  const result = await collect({
+    env: io.env ?? processEnv(),
+    fetcher: io.fetcher,
+    identity: io.identity ?? (await readMachineIdentity()),
+    runner: io.runner,
+    today: io.today,
+  });
+  if (result.kind === "reported" || result.kind === "empty") {
+    for (const warning of result.warnings) {
+      io.stderr(warning);
+    }
+    if (result.kind === "empty") {
+      io.stdout("nothing to report");
+      return 0;
+    }
+    let exitCode = 0;
+    for (const target of result.targets) {
+      if ("accepted" in target) {
+        io.stdout(
+          `accepted ${target.accepted} days for ${result.machine} at ${target.url}`,
+        );
+      } else {
+        io.stderr(`${target.url}: ${target.message}`);
+        exitCode = 1;
+      }
+    }
+    return exitCode;
+  }
+  if (result.kind === "missing-config") {
+    io.stderr(
+      `no aiusage config at ${result.configFile}; run: aiusage install --url <url> --key <key>`,
+    );
+    return 2;
+  }
+  for (const warning of result.warnings) {
+    io.stderr(warning);
+  }
+  io.stderr(result.message);
+  return 1;
+}
+
+async function runInstall(
+  options: InstallCommandOptions,
+  io: CliIo,
+): Promise<number> {
+  try {
+    await install({
+      cliPath: io.cliPath,
+      dryRun: options.dryRun,
+      env: io.env ?? processEnv(),
+      execPath: io.execPath,
+      key: options.key,
+      log: io.stdout,
+      platform: io.platform,
+      timezone: options.timezone,
+      uid: io.uid,
+      url: options.url,
+    });
+    return 0;
+  } catch (error) {
+    io.stderr(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+
+export async function runCli(argv: string[], io: CliIo): Promise<number> {
+  let exitCode = 0;
+  const program = new Command()
+    .name("@cgaravitoq/aiusage")
+    .description("Report local token usage to an aiusage instance");
+
+  program
+    .command("collect")
+    .description("Report local usage from the last 14 days")
+    .action(async () => {
+      exitCode = await runCollect(io);
+    });
+
+  program
+    .command("install")
+    .description("Write the aiusage config and the local schedule")
+    .requiredOption("--url <url>", "aiusage base url")
+    .requiredOption("--key <key>", "aiusage api key")
+    .option("--timezone <zone>", "IANA timezone, defaults to the machine zone")
+    .option("--dry-run", "print the files without writing them", false)
+    .action(async (options: InstallCommandOptions) => {
+      exitCode = await runInstall(options, io);
+    });
+
+  await program.parseAsync(argv, { from: "user" });
+  return exitCode;
+}
+
+if (import.meta.main) {
+  process.exitCode = await runCli(process.argv.slice(2), {
+    stderr: console.error,
+    stdout: console.log,
+  });
+}