tokenmax-collector 0.1.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/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "tokenmax-collector",
+  "version": "0.1.0",
+  "description": "Report local ccusage token usage to a tokenmax instance",
+  "type": "module",
+  "bin": {
+    "tokenmax": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "!src/**/*.spec.ts",
+    "!src/test/**"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cgaravitoq/tokenmax.git",
+    "directory": "packages/collector"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "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.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  }
+}

package/src/ccusage.ts

@@ -0,0 +1,80 @@
+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;
+
+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 sinceArgument(today: Date, timezone: string): string {
+  const calendarDate = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(today);
+  const [year, month, day] = calendarDate.split("-").map(Number);
+  const start = new Date(Date.UTC(year, month - 1, day - (windowDays - 1)));
+  return start.toISOString().slice(0, 10).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),
+  ]);
+  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,113 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { collect, type Fetcher } from "./collect";
+import type { CommandRunner } from "./command";
+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") {
+    io.stdout(`accepted ${result.accepted} days for ${result.machine}`);
+    return 0;
+  }
+  if (result.kind === "empty") {
+    io.stdout("nothing to report");
+    return 0;
+  }
+  if (result.kind === "missing-config") {
+    io.stderr(
+      `no tokenmax config at ${result.configFile}; run: tokenmax install --url <url> --key <key>`,
+    );
+    return 2;
+  }
+  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("tokenmax-collector")
+    .description("Report local token usage to a tokenmax 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 tokenmax config and the local schedule")
+    .requiredOption("--url <url>", "tokenmax base url")
+    .requiredOption("--key <key>", "tokenmax 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,
+  });
+}

package/src/collect.ts

@@ -0,0 +1,129 @@
+import { readCcusageDaily, sinceArgument } from "./ccusage";
+import { type CommandRunner, runCommand } from "./command";
+import { readConfig, runtimeTimezone } from "./config";
+import { type MachineIdentity, machineId } from "./machine";
+import { mapCcusageDays } from "./mapping";
+import { type CollectorEnv, collectorPaths, processEnv } from "./paths";
+import type { UsageDay, UsageReport } from "./usage";
+
+export interface HttpResponse {
+  status: number;
+  text(): Promise<string>;
+}
+
+export type Fetcher = (url: string, init: RequestInit) => Promise<HttpResponse>;
+
+export interface CollectOptions {
+  identity: MachineIdentity;
+  env?: CollectorEnv;
+  fetcher?: Fetcher;
+  runner?: CommandRunner;
+  today?: Date;
+  timezone?: string;
+}
+
+export type CollectResult =
+  | { kind: "reported"; accepted: number; machine: string }
+  | { kind: "empty" }
+  | { kind: "missing-config"; configFile: string }
+  | { kind: "failed"; message: string };
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const reportUrl = (baseUrl: string): string =>
+  `${baseUrl.replace(/\/+$/, "")}/api/report`;
+
+function acceptedCount(body: string): number | null {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    !("accepted" in payload)
+  ) {
+    return null;
+  }
+  const accepted = payload.accepted;
+  return typeof accepted === "number" ? accepted : null;
+}
+
+async function report(
+  fetcher: Fetcher,
+  url: string,
+  key: string,
+  usage: UsageReport,
+): Promise<CollectResult> {
+  const response = await fetcher(reportUrl(url), {
+    body: JSON.stringify(usage),
+    headers: {
+      Authorization: `Bearer ${key}`,
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+  const body = await response.text();
+  if (response.status !== 200) {
+    return {
+      kind: "failed",
+      message: `tokenmax responded ${response.status}: ${body}`,
+    };
+  }
+  const accepted = acceptedCount(body);
+  if (accepted === null) {
+    return {
+      kind: "failed",
+      message: `tokenmax responded an unexpected body: ${body}`,
+    };
+  }
+  return { accepted, kind: "reported", machine: usage.machine };
+}
+
+export async function collect(options: CollectOptions): Promise<CollectResult> {
+  const paths = collectorPaths(options.env ?? processEnv());
+  const config = await readConfig(paths.configFile);
+  if (config.kind === "missing") {
+    return { configFile: paths.configFile, kind: "missing-config" };
+  }
+  if (config.kind === "invalid") {
+    return { kind: "failed", message: config.message };
+  }
+
+  const machine = machineId(
+    options.identity.hostname,
+    options.identity.platformUuid,
+  );
+  const timezone =
+    config.config.timezone ?? options.timezone ?? runtimeTimezone();
+  const runner = options.runner ?? runCommand;
+
+  let days: UsageDay[];
+  try {
+    const daily = await readCcusageDaily(
+      runner,
+      sinceArgument(options.today ?? new Date(), timezone),
+      timezone,
+    );
+    days = mapCcusageDays(daily);
+  } catch (error) {
+    return { kind: "failed", message: messageOf(error) };
+  }
+  if (days.length === 0) {
+    return { kind: "empty" };
+  }
+
+  try {
+    return await report(
+      options.fetcher ?? fetch,
+      config.config.url,
+      config.config.key,
+      { days, machine, timezone },
+    );
+  } catch (error) {
+    return { kind: "failed", message: messageOf(error) };
+  }
+}

package/src/command.ts

@@ -0,0 +1,38 @@
+import { spawn } from "node:child_process";
+
+export interface CommandResult {
+  exitCode: number;
+  stderr: string;
+  stdout: string;
+}
+
+export type CommandRunner = (
+  command: string,
+  args: string[],
+) => Promise<CommandResult>;
+
+const toText = (chunks: Buffer[]): string =>
+  Buffer.concat(chunks).toString("utf8");
+
+export function runCommand(
+  command: string,
+  args: string[],
+): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout?.on("data", (chunk: Buffer) => stdout.push(chunk));
+    child.stderr?.on("data", (chunk: Buffer) => stderr.push(chunk));
+    child.on("error", (error: Error) => {
+      resolve({ exitCode: 1, stderr: error.message, stdout: "" });
+    });
+    child.on("close", (exitCode: number | null) => {
+      resolve({
+        exitCode: exitCode ?? 1,
+        stderr: toText(stderr),
+        stdout: toText(stdout),
+      });
+    });
+  });
+}

package/src/config.ts

@@ -0,0 +1,82 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+
+export const collectorConfig = z.object({
+  key: z.string().min(1),
+  timezone: z.string().min(1).optional(),
+  url: z.url({ protocol: /^https?$/ }),
+});
+
+export type CollectorConfig = z.infer<typeof collectorConfig>;
+
+export function canonicalTimezone(value: string): string | null {
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: value,
+    }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+export function runtimeTimezone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+export type ConfigReadResult =
+  | { kind: "ok"; config: CollectorConfig }
+  | { kind: "missing" }
+  | { kind: "invalid"; message: string };
+
+const issueText = (error: z.ZodError): string =>
+  error.issues
+    .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+    .join("; ");
+
+export async function readConfig(
+  configFile: string,
+): Promise<ConfigReadResult> {
+  let source: string;
+  try {
+    source = await readFile(configFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "invalid",
+      message: `could not read tokenmax config at ${configFile}: ${message}`,
+    };
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "invalid",
+      message: `could not parse tokenmax config at ${configFile}: ${message}`,
+    };
+  }
+
+  const parsed = collectorConfig.safeParse(payload);
+  if (!parsed.success) {
+    return {
+      kind: "invalid",
+      message: `invalid tokenmax config at ${configFile}: ${issueText(parsed.error)}`,
+    };
+  }
+  return { kind: "ok", config: parsed.data };
+}
+
+export async function writeConfig(
+  configFile: string,
+  config: CollectorConfig,
+): Promise<void> {
+  await mkdir(dirname(configFile), { recursive: true });
+  await writeFile(configFile, `${JSON.stringify(config, null, 2)}\n`);
+  await chmod(configFile, 0o600);
+}

package/src/install.ts

@@ -0,0 +1,128 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  type CollectorConfig,
+  canonicalTimezone,
+  collectorConfig,
+  runtimeTimezone,
+  writeConfig,
+} from "./config";
+import { type CollectorEnv, collectorPaths, processEnv } from "./paths";
+import {
+  launchAgentPlist,
+  loadCommand,
+  type ScheduleOptions,
+  type SupportedPlatform,
+  systemdService,
+  systemdTimer,
+} from "./schedule";
+
+export interface ScheduleFile {
+  contents: string;
+  path: string;
+}
+
+export interface InstallPlan {
+  config: CollectorConfig;
+  configFile: string;
+  files: ScheduleFile[];
+  loadCommand: string;
+}
+
+export interface InstallOptions {
+  key: string;
+  url: string;
+  cliPath?: string;
+  dryRun?: boolean;
+  env?: CollectorEnv;
+  execPath?: string;
+  log?: (line: string) => void;
+  platform?: NodeJS.Platform;
+  timezone?: string;
+  uid?: number;
+}
+
+const resolvePlatform = (value: NodeJS.Platform): SupportedPlatform => {
+  if (value === "darwin" || value === "linux") {
+    return value;
+  }
+  throw new Error(`unsupported platform: ${value}`);
+};
+
+const resolveCliPath = (): string =>
+  fileURLToPath(new URL("./cli.ts", import.meta.url));
+
+function scheduleFiles(
+  platform: SupportedPlatform,
+  paths: { plist: string; service: string; timer: string },
+  options: ScheduleOptions,
+): ScheduleFile[] {
+  if (platform === "darwin") {
+    return [{ contents: launchAgentPlist(options), path: paths.plist }];
+  }
+  return [
+    { contents: systemdService(options), path: paths.service },
+    { contents: systemdTimer(), path: paths.timer },
+  ];
+}
+
+export async function install(options: InstallOptions): Promise<InstallPlan> {
+  const env = options.env ?? processEnv();
+  const platform = resolvePlatform(options.platform ?? process.platform);
+  const paths = collectorPaths(env);
+  const requestedTimezone = options.timezone ?? runtimeTimezone();
+  const timezone = canonicalTimezone(requestedTimezone);
+  if (timezone === null) {
+    throw new Error(`invalid timezone: ${requestedTimezone}`);
+  }
+  const config = collectorConfig.parse({
+    key: options.key,
+    timezone,
+    url: options.url,
+  });
+  const cliPath = options.cliPath ?? resolveCliPath();
+  if (
+    options.dryRun !== true &&
+    (cliPath.includes("/install/cache/") || /\/bunx-\d+-[^/]+\//.test(cliPath))
+  ) {
+    throw new Error(
+      "refusing to schedule from a bunx path; install globally: bun add -g tokenmax-collector, then run: tokenmax install --url <url> --key <key>",
+    );
+  }
+  const files = scheduleFiles(platform, paths, {
+    cliPath,
+    execPath: options.execPath ?? process.execPath,
+    stderrLog: paths.stderrLog,
+    stdoutLog: paths.stdoutLog,
+  });
+  const uid = options.uid ?? process.getuid?.() ?? 0;
+  const plan: InstallPlan = {
+    config,
+    configFile: paths.configFile,
+    files,
+    loadCommand: loadCommand(platform, paths.plist, uid),
+  };
+  const log = options.log ?? console.log;
+
+  log(`config: ${plan.configFile} (600, key redacted)`);
+  for (const file of plan.files) {
+    log(`schedule: ${file.path}`);
+  }
+
+  if (options.dryRun === true) {
+    for (const file of plan.files) {
+      log(`--- ${file.path} ---`);
+      log(file.contents.trimEnd());
+    }
+  } else {
+    await writeConfig(plan.configFile, plan.config);
+    for (const file of plan.files) {
+      await mkdir(dirname(file.path), { recursive: true });
+      await writeFile(file.path, file.contents);
+    }
+  }
+
+  log(`load: ${plan.loadCommand}`);
+  return plan;
+}

package/src/machine.ts

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { runCommand } from "./command";
+
+export interface MachineIdentity {
+  hostname: string;
+  platformUuid: string | null;
+}
+
+const disallowed = /[^A-Za-z0-9._-]/g;
+
+const platformUuidPattern = /"IOPlatformUUID"\s*=\s*"([^"]+)"/;
+
+export function machineId(
+  hostnameValue: string,
+  platformUuid: string | null,
+): string {
+  const raw =
+    platformUuid === null ? hostnameValue : `${hostnameValue}-${platformUuid}`;
+  return raw.replace(disallowed, "-").slice(0, 64);
+}
+
+export function platformUuidFromIoreg(source: string): string | null {
+  return platformUuidPattern.exec(source)?.[1] ?? null;
+}
+
+async function readDarwinPlatformUuid(): Promise<string | null> {
+  const result = await runCommand("ioreg", [
+    "-rd1",
+    "-c",
+    "IOPlatformExpertDevice",
+  ]);
+  return result.exitCode === 0 ? platformUuidFromIoreg(result.stdout) : null;
+}
+
+async function readLinuxPlatformUuid(): Promise<string | null> {
+  try {
+    const value = (await readFile("/etc/machine-id", "utf8")).trim();
+    return value === "" ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+export async function readMachineIdentity(
+  platform: NodeJS.Platform = process.platform,
+): Promise<MachineIdentity> {
+  const platformUuid =
+    platform === "darwin"
+      ? await readDarwinPlatformUuid()
+      : platform === "linux"
+        ? await readLinuxPlatformUuid()
+        : null;
+  return { hostname: hostname(), platformUuid };
+}

package/src/mapping.ts

@@ -0,0 +1,55 @@
+import type { CcusageDaily } from "./ccusage";
+import type { UsageDay } from "./usage";
+
+const agentModelPrefix = /^\[[^\]]*\]\s*/;
+
+const rowKey = (day: UsageDay): string =>
+  `${day.date}\u0000${day.provider}\u0000${day.model}`;
+
+const isEmptyRow = (row: UsageDay): boolean =>
+  row.input === 0 &&
+  row.output === 0 &&
+  row.cache_create === 0 &&
+  row.cache_read === 0;
+
+export function mapCcusageDays(output: CcusageDaily): UsageDay[] {
+  const rows = new Map<string, UsageDay>();
+
+  for (const day of output.daily) {
+    for (const agent of day.agents) {
+      for (const breakdown of agent.modelBreakdowns) {
+        const row: UsageDay = {
+          cache_create: breakdown.cacheCreationTokens,
+          cache_read: breakdown.cacheReadTokens,
+          cost_usd: breakdown.cost,
+          date: day.period,
+          input: breakdown.inputTokens,
+          model: breakdown.modelName.replace(agentModelPrefix, ""),
+          output: breakdown.outputTokens,
+          provider: agent.agent,
+        };
+        if (isEmptyRow(row)) {
+          continue;
+        }
+        const key = rowKey(row);
+        const existing = rows.get(key);
+        if (existing === undefined) {
+          rows.set(key, row);
+          continue;
+        }
+        existing.cache_create += row.cache_create;
+        existing.cache_read += row.cache_read;
+        existing.cost_usd += row.cost_usd;
+        existing.input += row.input;
+        existing.output += row.output;
+      }
+    }
+  }
+
+  return [...rows.values()].sort(
+    (a, b) =>
+      a.date.localeCompare(b.date) ||
+      a.provider.localeCompare(b.provider) ||
+      a.model.localeCompare(b.model),
+  );
+}

package/src/paths.ts

@@ -0,0 +1,62 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export interface CollectorEnv {
+  home: string;
+  platform?: NodeJS.Platform;
+  tokenmaxHome?: string;
+  xdgConfigHome?: string;
+  xdgStateHome?: string;
+}
+
+export interface CollectorPaths {
+  configFile: string;
+  plist: string;
+  service: string;
+  stderrLog: string;
+  stdoutLog: string;
+  timer: string;
+}
+
+export function processEnv(): CollectorEnv {
+  return {
+    home: homedir(),
+    platform: process.platform,
+    tokenmaxHome: process.env.TOKENMAX_HOME,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    xdgStateHome: process.env.XDG_STATE_HOME,
+  };
+}
+
+function logDirFor(env: CollectorEnv, home: string): string {
+  if (env.platform !== "linux") {
+    return resolve(home, "Library", "Logs", "tokenmax");
+  }
+  if (env.tokenmaxHome === undefined && env.xdgStateHome !== undefined) {
+    return resolve(env.xdgStateHome, "tokenmax", "logs");
+  }
+  return resolve(home, ".local", "state", "tokenmax", "logs");
+}
+
+export function collectorPaths(env: CollectorEnv): CollectorPaths {
+  const home = resolve(env.tokenmaxHome ?? env.home);
+  const configHome =
+    env.tokenmaxHome === undefined && env.xdgConfigHome !== undefined
+      ? resolve(env.xdgConfigHome)
+      : resolve(home, ".config");
+  const logDir = logDirFor(env, home);
+
+  return {
+    configFile: resolve(configHome, "tokenmax", "config.json"),
+    plist: resolve(
+      home,
+      "Library",
+      "LaunchAgents",
+      "dev.tokenmax.collector.plist",
+    ),
+    service: resolve(home, ".config", "systemd", "user", "tokenmax.service"),
+    stderrLog: resolve(logDir, "tokenmax.err.log"),
+    stdoutLog: resolve(logDir, "tokenmax.log"),
+    timer: resolve(home, ".config", "systemd", "user", "tokenmax.timer"),
+  };
+}

package/src/schedule.ts

@@ -0,0 +1,68 @@
+export interface ScheduleOptions {
+  cliPath: string;
+  execPath: string;
+  stderrLog: string;
+  stdoutLog: string;
+}
+
+export type SupportedPlatform = "darwin" | "linux";
+
+export function launchAgentPlist(options: ScheduleOptions): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.tokenmax.collector</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${options.execPath}</string>
+    <string>${options.cliPath}</string>
+    <string>collect</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>300</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${options.stdoutLog}</string>
+  <key>StandardErrorPath</key>
+  <string>${options.stderrLog}</string>
+</dict>
+</plist>
+`;
+}
+
+export function systemdService(options: ScheduleOptions): string {
+  return `[Unit]
+Description=Report local token usage to tokenmax
+
+[Service]
+Type=oneshot
+ExecStart="${options.execPath}" "${options.cliPath}" collect
+`;
+}
+
+export function systemdTimer(): string {
+  return `[Unit]
+Description=Report local token usage to tokenmax every five minutes
+
+[Timer]
+Unit=tokenmax.service
+OnBootSec=1min
+OnUnitActiveSec=5min
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+export function loadCommand(
+  platform: SupportedPlatform,
+  plistPath: string,
+  uid: number,
+): string {
+  return platform === "darwin"
+    ? `launchctl bootstrap gui/${uid} ${plistPath}`
+    : "systemctl --user enable --now tokenmax.timer";
+}

package/src/usage.ts

@@ -0,0 +1,16 @@
+export interface UsageDay {
+  cache_create: number;
+  cache_read: number;
+  cost_usd: number;
+  date: string;
+  input: number;
+  model: string;
+  output: number;
+  provider: string;
+}
+
+export interface UsageReport {
+  days: UsageDay[];
+  machine: string;
+  timezone: string;
+}