@token-dashboard/codex-usage-uploader 0.1.2 → 0.1.3

package/README.md

@@ -4,7 +4,7 @@
 
 - 后台常驻运行，增量扫描本地 Codex session 数据
 - 首次安装自动补采全量历史
-- macOS launchd 托管，开机自启
+- macOS launchd 托管，登录自启动可选
 
 > 仅支持 macOS，需要 Node.js >= 22.13.0。
 
@@ -16,7 +16,7 @@
 npx @token-dashboard/codex-usage-uploader init
 ```
 
-安装过程中会自动读取 Codex 登录态（`~/.codex/auth.json`）获取身份信息。如果读取不到邮箱，会在终端交互式提示你手动填写。
+安装过程中会自动读取 Codex 登录态（`~/.codex/auth.json`）获取身份信息。如果读取不到邮箱，会在终端交互式提示你手动填写；同时会询问是否在这台 Mac 上启用登录自启动。
 
 安装完成后，`codex-usage-uploader` 命令会被写入 `~/bin/`，后续可直接使用。
 
@@ -28,7 +28,7 @@ npx @token-dashboard/codex-usage-uploader init
 codex-usage-uploader init
 ```
 
-首次运行时完成安装与配置；重复运行会升级本地版本并重启后台服务。后端地址默认为 `http://101.126.66.51:8086`，如需自定义可通过 `--backend-url` 指定。
+首次运行时完成安装与配置；重复运行会升级本地版本并重启后台服务，同时可重新选择是否启用登录自启动。后端地址默认为 `http://101.126.66.51:8086`，如需自定义可通过 `--backend-url` 指定。
 
 ### 绑定身份
 
@@ -50,6 +50,24 @@ codex-usage-uploader bind --email you@company.com --yes
 | `codex-usage-uploader logs`             | 查看服务日志（默认最近 100 行） |
 | `codex-usage-uploader logs --lines 500` | 查看更多日志                    |
 
+### 查看本机 token 用量
+
+```bash
+codex-usage-uploader usage
+codex-usage-uploader usage --period today
+codex-usage-uploader usage --period 7d
+codex-usage-uploader usage --from 2026-04-01 --to 2026-04-17
+```
+
+`usage` 是一个纯本地只读命令，不依赖后端查询，也不要求先执行 `init`。它会重新扫描当前机器上的 Codex rollout 文件，默认同时包含：
+
+- `~/.codex/sessions`
+- 同级的 `~/.codex/archived_sessions`
+
+默认输出是一张纯文本表格，列为 `Date`、`Models`、`Input`、`Output`、`Reasoning`、`Cache Read`、`Total Tokens`，最后一行固定为 `Total`。默认 `--period=all` 时，表格覆盖全历史所有有 token 使用的日期。
+
+统计口径与现有 uploader/后端保持一致，使用 `token_count` 事件中的 `last_*` token 字段，而不是累计 `total_*` 字段。切天时区使用当前机器时区。
+
 ### 清除本地状态
 
 ```bash
@@ -81,16 +99,20 @@ codex-usage-uploader uninstall
 | `--employee-name <name>` | 绑定姓名                                               |
 | `--employee-id <id>`     | 绑定工号                                               |
 | `--interval <seconds>`   | 扫描间隔秒数（默认 30）                                |
+| `--period <value>`       | `usage` 时间范围：`today`、`7d`、`30d`、`all`          |
+| `--from <date>`          | `usage` 开始日期（`YYYY-MM-DD`）                       |
+| `--to <date>`            | `usage` 结束日期（`YYYY-MM-DD`）                       |
 | `--yes`                  | 跳过所有交互确认                                       |
 | `--lines <n>`            | `logs` 命令输出行数（默认 100）                        |
 | `-h, --help`             | 显示帮助                                               |
 
 ## 工作原理
 
-1. **init** 将包安装到 `~/.codex-usage-uploader/`，绑定身份后前台执行一次全量历史补采，完成后启动 macOS launchd 后台服务。
+1. **init** 将包安装到 `~/.codex-usage-uploader/`，绑定身份后前台执行一次全量历史补采，完成后启动 macOS launchd 后台服务，并按交互选择决定是否启用登录自启动。
 2. 后台服务每 30 秒（可通过 `--interval` 调整）增量扫描 `~/.codex/sessions/` 下的 rollout 文件。
 3. 扫描到的 token 用量数据暂存在本地 SQLite 队列中，满足条件后自动封批上传至后端。
-4. 所有数据在上报前已做去敏处理，仅包含 session 元信息、turn 上下文摘要和 token 计数。
+4. `usage` 命令会按需重扫本地 `sessions + archived_sessions`，直接在终端计算并展示本机 token 用量，不写入本地状态库，也不访问后端。
+5. 所有数据在上报前已做去敏处理，仅包含 session 元信息、turn 上下文摘要和 token 计数。
 
 ## 本地文件
 
@@ -99,6 +121,7 @@ codex-usage-uploader uninstall
 | `~/.codex-usage-uploader/config.json`  | 运行配置       |
 | `~/.codex-usage-uploader/state.sqlite` | 本地状态数据库 |
 | `~/.codex-usage-uploader/logs/`        | 服务日志       |
+| `~/.codex-usage-uploader/launchd/`     | launchd service plist |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@token-dashboard/codex-usage-uploader",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Codex 用量上报 CLI",
   "type": "module",
   "bin": {
@@ -12,8 +12,15 @@
     "README.md"
   ],
   "scripts": {
-    "dev": "node bin/codex-usage-uploader.js init --backend-url http://localhost:8086",
-    "test": "node --no-warnings --test tests/*.test.mjs"
+    "init": "node bin/codex-usage-uploader.js init --backend-url http://localhost:8086",
+    "start": "node bin/codex-usage-uploader.js start",
+    "stop": "node bin/codex-usage-uploader.js stop",
+    "restart": "node bin/codex-usage-uploader.js restart",
+    "status": "node bin/codex-usage-uploader.js status",
+    "usage": "node bin/codex-usage-uploader.js usage",
+    "logs": "node bin/codex-usage-uploader.js logs",
+    "clear": "node bin/codex-usage-uploader.js clear",
+    "uninstall": "node bin/codex-usage-uploader.js uninstall"
   },
   "engines": {
     "node": ">=22.13.0"

package/src/cli.js

@@ -3,9 +3,10 @@ import path from 'node:path';
 import { CodexUsageUploader } from './collector.js';
 import { identityIsBound, promptConfirm } from './auth.js';
 import { CLI_NAME, DEFAULT_BACKEND_URL, DEFAULT_CONFIG_FILE, PRODUCT_NAME } from './constants.js';
-import { findPackageRoot, installCurrentPackage } from './install.js';
+import { ensurePathInShellConfigs, findPackageRoot, installCurrentPackage, removePathFromShellConfigs } from './install.js';
 import { LaunchdServiceManager } from './launchd.js';
-import { formatStatusOutput, mergeRuntimeConfig } from './runtime-config.js';
+import { collectLocalUsage, getLocalTimeZone } from './local-usage.js';
+import { formatStatusOutput, mergeRuntimeConfig, saveRuntimeConfig } from './runtime-config.js';
 import { StateDb } from './state-db.js';
 
 const HELP_TEXT = `${PRODUCT_NAME}
@@ -18,6 +19,7 @@ Usage:
   ${CLI_NAME} stop
   ${CLI_NAME} restart
   ${CLI_NAME} status
+  ${CLI_NAME} usage [--period <today|7d|30d|all>] [--from <date>] [--to <date>]
   ${CLI_NAME} logs [--lines 100]
   ${CLI_NAME} uninstall
 
@@ -33,6 +35,9 @@ Common options:
   --employee-name <name>     Bind employee name
   --device-id <id>           Override device ID
   --hostname <name>          Override hostname
+  --period <value>           Usage range: today, 7d, 30d, or all
+  --from <date>              Usage range start date (YYYY-MM-DD)
+  --to <date>                Usage range end date (YYYY-MM-DD)
   --yes                      Skip interactive prompts
   --package-spec <spec>      npm install spec used by init
   --lines <n>                Number of log lines for service logs
@@ -50,6 +55,9 @@ class CliOperationalError extends Error {
 export const cliDeps = {
   findPackageRoot,
   installCurrentPackage,
+  ensurePathInShellConfigs,
+  removePathFromShellConfigs,
+  promptConfirm,
   createUploader(runtime) {
     return new CodexUsageUploader({
       sessionsDir: runtime.sessionsDir,
@@ -57,6 +65,7 @@ export const cliDeps = {
       backendUrl: runtime.backendUrl,
       intervalSeconds: runtime.intervalSeconds,
       codexAuthPath: runtime.codexAuthPath,
+      persistentCollectorIdPath: runtime.persistentCollectorIdPath,
     });
   },
   createServiceManager(runtime) {
@@ -102,6 +111,9 @@ export function parseCliArgs(argv) {
       '--employee-name',
       '--device-id',
       '--hostname',
+      '--period',
+      '--from',
+      '--to',
       '--package-spec',
       '--lines',
     ]);
@@ -158,6 +170,15 @@ function assignOption(options, key, value) {
     case '--hostname':
       options.hostname = value;
       break;
+    case '--period':
+      options.period = value;
+      break;
+    case '--from':
+      options.from = value;
+      break;
+    case '--to':
+      options.to = value;
+      break;
     case '--package-spec':
       options.packageSpec = value;
       break;
@@ -285,17 +306,21 @@ function wrapCatchUpFailure(error) {
   );
 }
 
-function printPathHint(runtime) {
-  const linkDir = path.dirname(runtime.homeBinLink);
-  const dirs = (process.env.PATH || '').split(path.delimiter);
-  if (dirs.includes(linkDir)) return;
-  console.log('');
-  console.log(
-    `Note: ${linkDir} is not in your PATH. To use \`${CLI_NAME}\` directly, run:`,
+function wrapUsageFailure(error) {
+  return new CliOperationalError(
+    `Usage query failed: ${
+      error instanceof Error ? error.message : String(error)
+    }`,
   );
-  console.log(`  export PATH="${linkDir}:$PATH"`);
-  console.log(
-    'You can add this line to ~/.zshrc or ~/.bashrc to make it permanent.',
+}
+
+async function resolveAutoStartOnLogin(runtime, options) {
+  if (options.yes) {
+    return runtime.autoStartOnLogin;
+  }
+  return cliDeps.promptConfirm(
+    'Start automatically when you log in on this Mac?',
+    runtime.autoStartOnLogin,
   );
 }
 
@@ -317,7 +342,7 @@ async function runInit(options) {
     nodePath: process.execPath,
   });
 
-  const manager = cliDeps.createServiceManager(runtime);
+  let manager = cliDeps.createServiceManager(runtime);
   manager.stop();
 
   const uploader = cliDeps.createUploader(runtime);
@@ -339,20 +364,126 @@ async function runInit(options) {
       throw wrapCatchUpFailure(error);
     }
 
+    runtime.autoStartOnLogin = await resolveAutoStartOnLogin(runtime, options);
+    runtime = saveRuntimeConfig(runtime);
+    manager = cliDeps.createServiceManager(runtime);
     manager.start();
     console.log(`${PRODUCT_NAME} initialized and started.`);
+    console.log(
+      runtime.autoStartOnLogin
+        ? 'Login auto-start is enabled.'
+        : 'Login auto-start is disabled for future logins.',
+    );
     if (scanResult.pendingBatches > 0) {
       console.log(
         `Background service is uploading ${scanResult.pendingBatches} batch(es) with ${scanResult.pendingEvents} event(s).`,
       );
     }
     console.log(`Use \`${CLI_NAME} status\` to check the local service.`);
-    printPathHint(runtime);
+    const linkDir = path.dirname(runtime.homeBinLink);
+    const pathDirs = (process.env.PATH || '').split(path.delimiter);
+    if (!pathDirs.includes(linkDir)) {
+      cliDeps.ensurePathInShellConfigs(linkDir);
+      console.log(`Open a new terminal to use \`${CLI_NAME}\` directly.`);
+    }
   } finally {
     uploader.close();
   }
 }
 
+function formatCount(value) {
+  return Number(value ?? 0).toLocaleString('en-US');
+}
+
+function renderTable(headers, rows, alignments = []) {
+  const widths = headers.map((header, index) =>
+    Math.max(
+      header.length,
+      ...rows.map((row) => String(row[index] ?? '').length),
+    ),
+  );
+  const formatCell = (cell, index) => {
+    const text = String(cell ?? '');
+    return alignments[index] === 'right'
+      ? text.padStart(widths[index])
+      : text.padEnd(widths[index]);
+  };
+  const formatRow = (row) =>
+    row
+      .map((cell, index) => formatCell(cell, index))
+      .join('  ')
+      .trimEnd();
+  return [
+    formatRow(headers),
+    ...rows.map((row) => formatRow(row)),
+  ].join('\n');
+}
+
+function formatUsageDate(dateString) {
+  const [year, month, day] = dateString.split('-').map(Number);
+  return new Intl.DateTimeFormat('en-US', {
+    timeZone: 'UTC',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  }).format(new Date(Date.UTC(year, month - 1, day)));
+}
+
+function printUsageReport(report) {
+  if (report.tokenEventCount === 0) {
+    console.log('No local Codex usage found for selected range.');
+    return;
+  }
+
+  const rows = report.days.map((row) => [
+    formatUsageDate(row.date),
+    row.models.join(', '),
+    formatCount(row.inputTokens),
+    formatCount(row.outputTokens),
+    formatCount(row.reasoningOutputTokens),
+    formatCount(row.cachedInputTokens),
+    formatCount(row.totalTokens),
+  ]);
+  rows.push([
+    'Total',
+    '',
+    formatCount(report.summary.inputTokens),
+    formatCount(report.summary.outputTokens),
+    formatCount(report.summary.reasoningOutputTokens),
+    formatCount(report.summary.cachedInputTokens),
+    formatCount(report.summary.totalTokens),
+  ]);
+
+  console.log(
+    renderTable(
+      ['Date', 'Models', 'Input', 'Output', 'Reasoning', 'Cache Read', 'Total Tokens'],
+      rows,
+      ['left', 'left', 'right', 'right', 'right', 'right', 'right'],
+    ),
+  );
+}
+
+async function runUsage(options) {
+  const runtime = mergeRuntimeConfig(options.configFile, runtimeOverrides(options));
+
+  console.log('Scanning local Codex usage...');
+
+  let report;
+  try {
+    report = await collectLocalUsage({
+      sessionsDir: runtime.sessionsDir,
+      period: options.period,
+      from: options.from,
+      to: options.to,
+      timeZone: getLocalTimeZone(),
+    });
+  } catch (error) {
+    throw wrapUsageFailure(error);
+  }
+
+  printUsageReport(report);
+}
+
 async function runBind(options) {
   const runtime = mergeRuntimeConfig(options.configFile, runtimeOverrides(options));
   const uploader = cliDeps.createUploader(runtime);
@@ -386,6 +517,7 @@ async function runInternalWorker(options) {
 function loadQueueStats(stateDbPath) {
   if (!fs.existsSync(stateDbPath)) {
     return {
+      collectorId: null,
       bufferingBatchCount: 0,
       pendingBatchCount: 0,
       retryingBatchCount: 0,
@@ -397,7 +529,11 @@ function loadQueueStats(stateDbPath) {
   }
   const stateDb = new StateDb(stateDbPath);
   try {
-    return stateDb.getQueueStats();
+    const identity = stateDb.getIdentity();
+    return {
+      collectorId: identity.collectorId ?? null,
+      ...stateDb.getQueueStats(),
+    };
   } finally {
     stateDb.close();
   }
@@ -412,10 +548,13 @@ function printStatus(runtime, status) {
     ['Config exists', payload.configExists ? 'yes' : 'no'],
     ['Loaded', payload.loaded ? 'yes' : 'no'],
     ['Running', payload.running ? 'yes' : 'no'],
+    ['Auto start on login', payload.autoStartOnLogin ? 'yes' : 'no'],
     ['PID', payload.pid ?? '-'],
     ['State', payload.state ?? '-'],
     ['Last exit code', payload.lastExitCode ?? '-'],
-    ['Backend URL', payload.backendUrl ?? '-'],
+    ['Collector ID', payload.collectorId ?? '-'],
+    ['Upload URL', payload.backendUrl ? `${payload.backendUrl}/codex-usage/upload` : '-'],
+    ['Register URL', payload.backendUrl ? `${payload.backendUrl}/codex-usage/collectors/register` : '-'],
     ['Interval', `${payload.intervalSeconds}s`],
     ['Buffering batches', payload.bufferingBatchCount],
     ['Pending batches', payload.pendingBatchCount],
@@ -433,7 +572,8 @@ function printStatus(runtime, status) {
     ['State DB', payload.stateDbPath],
     ['Stdout log', payload.stdoutLogPath],
     ['Stderr log', payload.stderrLogPath],
-    ['Plist', payload.plistPath],
+    ['Service plist', payload.plistPath],
+    ['LaunchAgent plist', payload.launchAgentPath],
     ['Label', payload.label],
   ];
   for (const [label, value] of lines) {
@@ -462,7 +602,7 @@ async function runClear(options) {
   }
 
   if (!options.yes) {
-    const confirmed = await promptConfirm(
+    const confirmed = await cliDeps.promptConfirm(
       'Clear local backfill state and queued uploads?',
       false,
     );
@@ -533,6 +673,7 @@ function runLifecycleCommand(action, options) {
     }
     case 'uninstall':
       manager.uninstall();
+      cliDeps.removePathFromShellConfigs();
       fs.rmSync(runtime.installRoot, { recursive: true, force: true });
       console.log(`${PRODUCT_NAME} uninstalled from ${runtime.installRoot}`);
       return;
@@ -557,6 +698,7 @@ export async function main(argv = process.argv.slice(2)) {
       'stop',
       'restart',
       'status',
+      'usage',
       'logs',
       'uninstall',
       'run',
@@ -577,6 +719,9 @@ export async function main(argv = process.argv.slice(2)) {
       case 'clear':
         await runClear(options);
         return 0;
+      case 'usage':
+        await runUsage(options);
+        return 0;
       case 'run':
         await runInternalWorker(options);
         return 0;

package/src/collector.js

@@ -5,11 +5,12 @@ import { createInterface } from 'node:readline';
 import { loadCodexAuthIdentity, identityIsBound, promptValue } from './auth.js';
 import { RolloutParser } from './parser.js';
 import { StateDb } from './state-db.js';
-import { nowTs, sleep, stableStringify } from './utils.js';
+import { nowTs, sleep, stableStringify, readPersistentCollectorId, writePersistentCollectorId } from './utils.js';
 import {
   ARCHIVED_SESSIONS_SOURCE_ROOT,
   MAX_BATCH_BYTES,
   MAX_EVENTS_PER_BATCH,
+  PERSISTENT_COLLECTOR_ID_PATH,
   REGISTER_REFRESH_SECONDS,
   SCAN_CHUNK_MAX_BYTES,
   SCAN_CHUNK_MAX_EVENTS,
@@ -23,6 +24,7 @@ export class CodexUsageUploader {
     backendUrl,
     intervalSeconds,
     codexAuthPath,
+    persistentCollectorIdPath = PERSISTENT_COLLECTOR_ID_PATH,
     scanChunkMaxEvents = SCAN_CHUNK_MAX_EVENTS,
     scanChunkMaxBytes = SCAN_CHUNK_MAX_BYTES,
   }) {
@@ -31,6 +33,7 @@ export class CodexUsageUploader {
     this.backendUrl = backendUrl?.replace(/\/+$/, '') || null;
     this.intervalSeconds = intervalSeconds;
     this.codexAuthPath = codexAuthPath;
+    this.persistentCollectorIdPath = persistentCollectorIdPath;
     this.scanChunkMaxEvents = scanChunkMaxEvents;
     this.scanChunkMaxBytes = scanChunkMaxBytes;
     this.identity = this.ensureIdentity();
@@ -43,10 +46,12 @@ export class CodexUsageUploader {
   ensureIdentity() {
     const identity = this.stateDb.getIdentity();
     if (!identity.collectorId) {
-      identity.collectorId = `${Date.now().toString(16)}${Math.random()
+      const persisted = readPersistentCollectorId(this.persistentCollectorIdPath);
+      identity.collectorId = persisted ?? `${Date.now().toString(16)}${Math.random()
         .toString(16)
         .slice(2, 14)}`;
     }
+    writePersistentCollectorId(this.persistentCollectorIdPath, identity.collectorId);
     if (!identity.deviceId) {
       identity.deviceId = `${os.hostname()}-${Math.random()
         .toString(16)

package/src/constants.js

@@ -20,11 +20,20 @@ export const DEFAULT_LOCAL_BIN_PATH = path.join(DEFAULT_LOCAL_BIN_DIR, CLI_NAME)
 export const DEFAULT_HOME_BIN_LINK = path.join(os.homedir(), 'bin', CLI_NAME);
 export const DEFAULT_LAUNCHD_LABEL = 'com.token-dashboard.codex-usage-uploader';
 export const DEFAULT_PLIST_PATH = path.join(
+  DEFAULT_INSTALL_ROOT,
+  'launchd',
+  `${DEFAULT_LAUNCHD_LABEL}.plist`,
+);
+export const DEFAULT_LAUNCH_AGENT_PATH = path.join(
   os.homedir(),
   'Library',
   'LaunchAgents',
   `${DEFAULT_LAUNCHD_LABEL}.plist`,
 );
+export const PERSISTENT_COLLECTOR_ID_PATH = path.join(
+  os.homedir(),
+  '.codex-usage-uploader-collector-id',
+);
 export const DEFAULT_BACKEND_URL = 'http://101.126.66.51:8086';
 export const SCAN_CHUNK_MAX_EVENTS = 50;
 export const SCAN_CHUNK_MAX_BYTES = 256 * 1024;

package/src/install.js

@@ -1,10 +1,17 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { CLI_NAME } from './constants.js';
 import { saveRuntimeConfig } from './runtime-config.js';
 
+const SHELL_CONFIG_MARKER = '# Added by codex-usage-uploader';
+const SHELL_CONFIG_FILES = [
+  path.join(os.homedir(), '.zshrc'),
+  path.join(os.homedir(), '.bash_profile'),
+];
+
 export function findPackageRoot(startUrl = import.meta.url) {
   let current = path.dirname(fileURLToPath(startUrl));
   while (true) {
@@ -99,3 +106,45 @@ export function ensureHomeBinLink(runtime) {
   }
   fs.symlinkSync(runtime.localBinPath, runtime.homeBinLink);
 }
+
+export function ensurePathInShellConfigs(binDir) {
+  const exportLine = `export PATH="${binDir}:$PATH"`;
+  for (const configFile of SHELL_CONFIG_FILES) {
+    try {
+      if (!fs.existsSync(configFile)) continue;
+      const content = fs.readFileSync(configFile, 'utf8');
+      if (content.includes(SHELL_CONFIG_MARKER)) continue;
+      const prefix = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+      fs.appendFileSync(configFile, `${prefix}\n${SHELL_CONFIG_MARKER}\n${exportLine}\n`);
+    } catch {
+      // best-effort, ignore errors
+    }
+  }
+}
+
+export function removePathFromShellConfigs() {
+  for (const configFile of SHELL_CONFIG_FILES) {
+    try {
+      if (!fs.existsSync(configFile)) continue;
+      const content = fs.readFileSync(configFile, 'utf8');
+      if (!content.includes(SHELL_CONFIG_MARKER)) continue;
+      const lines = content.split('\n');
+      const filtered = [];
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i] === SHELL_CONFIG_MARKER) {
+          if (i + 1 < lines.length && lines[i + 1].startsWith('export PATH=')) {
+            i += 1;
+          }
+          if (filtered.length > 0 && filtered[filtered.length - 1] === '') {
+            filtered.pop();
+          }
+          continue;
+        }
+        filtered.push(lines[i]);
+      }
+      fs.writeFileSync(configFile, filtered.join('\n'));
+    } catch {
+      // best-effort, ignore errors
+    }
+  }
+}

package/src/launchd.js

@@ -96,21 +96,37 @@ export class LaunchdServiceManager {
     if (!this.runtime.entryFile || !fs.existsSync(this.runtime.entryFile)) {
       throw new Error(`installed runtime entry not found: ${this.runtime.entryFile || '(empty)'}`);
     }
+    const plist = buildLaunchdPlist(this.runtime);
     fs.mkdirSync(path.dirname(this.runtime.plistPath), { recursive: true });
     fs.mkdirSync(path.dirname(this.runtime.stdoutLogPath), { recursive: true });
-    fs.writeFileSync(this.runtime.plistPath, buildLaunchdPlist(this.runtime));
+    fs.writeFileSync(this.runtime.plistPath, plist);
+    this.syncLaunchAgent(plist);
+  }
+
+  syncLaunchAgent(plist) {
+    const launchAgentPath = this.runtime.launchAgentPath;
+    if (!launchAgentPath) {
+      return;
+    }
+    if (this.runtime.autoStartOnLogin) {
+      fs.mkdirSync(path.dirname(launchAgentPath), { recursive: true });
+      fs.writeFileSync(launchAgentPath, plist);
+      return;
+    }
+    if (fs.existsSync(launchAgentPath)) {
+      fs.rmSync(launchAgentPath, { force: true });
+    }
   }
 
   start() {
     this.ensurePlist();
     this.stop();
     this.run(['launchctl', 'bootstrap', this.domainTarget(), this.runtime.plistPath]);
-    this.run(['launchctl', 'kickstart', '-k', this.serviceTarget()], { check: false });
   }
 
   stop() {
     this.ensureMacos();
-    this.run(['launchctl', 'bootout', this.domainTarget(), this.runtime.plistPath], { check: false });
+    this.run(['launchctl', 'bootout', this.serviceTarget()], { check: false });
   }
 
   restart() {
@@ -137,6 +153,9 @@ export class LaunchdServiceManager {
     if (fs.existsSync(this.runtime.plistPath)) {
       fs.unlinkSync(this.runtime.plistPath);
     }
+    if (this.runtime.launchAgentPath && fs.existsSync(this.runtime.launchAgentPath)) {
+      fs.unlinkSync(this.runtime.launchAgentPath);
+    }
     if (fs.existsSync(this.runtime.homeBinLink) && fs.lstatSync(this.runtime.homeBinLink).isSymbolicLink()) {
       try {
         const target = fs.realpathSync.native(this.runtime.homeBinLink);

package/src/local-usage.js

@@ -0,0 +1,342 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import {
+  ARCHIVED_SESSIONS_SOURCE_ROOT,
+  SESSIONS_SOURCE_ROOT,
+} from './constants.js';
+import { RolloutParser } from './parser.js';
+
+const LOCAL_USAGE_COLLECTOR = Object.freeze({ collectorId: 'local-usage' });
+const VALID_PERIODS = new Set(['today', '7d', '30d', 'all']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function getLocalTimeZone() {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+
+export function resolveUsageQuery({
+  period,
+  from,
+  to,
+  now = Date.now(),
+  timeZone = getLocalTimeZone(),
+} = {}) {
+  if (period && (from || to)) {
+    throw new Error('--period cannot be combined with --from or --to');
+  }
+
+  if (period && !VALID_PERIODS.has(period)) {
+    throw new Error(`--period must be one of: today, 7d, 30d, all`);
+  }
+
+  const today = formatDateInTimeZone(now, timeZone);
+
+  if (period === 'today') {
+    return {
+      mode: 'today',
+      from: today,
+      to: today,
+      trendFrom: today,
+      trendTo: today,
+    };
+  }
+
+  if (period === '7d') {
+    return {
+      mode: '7d',
+      from: addDays(today, -6),
+      to: today,
+      trendFrom: addDays(today, -6),
+      trendTo: today,
+    };
+  }
+
+  if (period === '30d') {
+    return {
+      mode: '30d',
+      from: addDays(today, -29),
+      to: today,
+      trendFrom: addDays(today, -29),
+      trendTo: today,
+    };
+  }
+
+  if (period === 'all' || (!period && !from && !to)) {
+    return {
+      mode: 'all',
+      from: null,
+      to: null,
+      trendFrom: addDays(today, -29),
+      trendTo: today,
+    };
+  }
+
+  const normalizedFrom = from == null ? null : normalizeDateString(from, '--from');
+  const normalizedTo = to == null ? null : normalizeDateString(to, '--to');
+
+  if (normalizedFrom && normalizedTo && normalizedFrom > normalizedTo) {
+    throw new Error('--from cannot be later than --to');
+  }
+
+  return {
+    mode: 'custom',
+    from: normalizedFrom,
+    to: normalizedTo,
+    trendFrom: normalizedFrom,
+    trendTo: normalizedTo,
+  };
+}
+
+export async function collectLocalUsage({
+  sessionsDir,
+  period,
+  from,
+  to,
+  now = Date.now(),
+  timeZone = getLocalTimeZone(),
+  includeArchived = true,
+} = {}) {
+  const range = resolveUsageQuery({ period, from, to, now, timeZone });
+  const archivedSessionsDir = path.join(
+    path.dirname(sessionsDir),
+    ARCHIVED_SESSIONS_SOURCE_ROOT,
+  );
+
+  const roots = [
+    { sourceRoot: SESSIONS_SOURCE_ROOT, dir: sessionsDir },
+  ];
+  if (includeArchived) {
+    roots.push({
+      sourceRoot: ARCHIVED_SESSIONS_SOURCE_ROOT,
+      dir: archivedSessionsDir,
+    });
+  }
+
+  const entries = roots.flatMap((root) =>
+    iterRolloutFiles(root.dir).map((filePath) => ({
+      ...root,
+      filePath,
+      relpath: path.relative(root.dir, filePath).split(path.sep).join('/'),
+    })),
+  );
+
+  entries.sort((left, right) => left.filePath.localeCompare(right.filePath));
+
+  const summary = emptyUsageRow();
+  const dayMap = new Map();
+  const trendMap = new Map();
+  const modelMap = new Map();
+  let tokenEventCount = 0;
+
+  for (const entry of entries) {
+    const parser = new RolloutParser(
+      LOCAL_USAGE_COLLECTOR,
+      `${entry.sourceRoot}/${entry.relpath}`,
+    );
+    const input = fs.createReadStream(entry.filePath, { encoding: 'utf8' });
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    let lineNo = 0;
+
+    try {
+      for await (const line of rl) {
+        lineNo += 1;
+        if (!line) continue;
+        const parsed = parser.processLine(lineNo, line);
+        for (const event of parsed.events) {
+          const eventDate = formatDateInTimeZone(event.timestamp, timeZone);
+          if (!isWithinDateRange(eventDate, range.from, range.to)) {
+            continue;
+          }
+
+          const usage = usageFromEvent(event);
+          tokenEventCount += 1;
+          accumulateUsage(summary, usage);
+
+          const currentDay = dayMap.get(eventDate) ?? {
+            date: eventDate,
+            eventCount: 0,
+            models: new Set(),
+            ...emptyUsageRow(),
+          };
+          currentDay.eventCount += 1;
+          currentDay.models.add(usage.model);
+          accumulateUsage(currentDay, usage);
+          dayMap.set(eventDate, currentDay);
+
+          const currentModel = modelMap.get(usage.model) ?? {
+            model: usage.model,
+            eventCount: 0,
+            ...emptyUsageRow(),
+          };
+          currentModel.eventCount += 1;
+          accumulateUsage(currentModel, usage);
+          modelMap.set(usage.model, currentModel);
+
+          if (isWithinDateRange(eventDate, range.trendFrom, range.trendTo)) {
+            const currentDate = trendMap.get(eventDate) ?? {
+              date: eventDate,
+              eventCount: 0,
+              ...emptyUsageRow(),
+            };
+            currentDate.eventCount += 1;
+            accumulateUsage(currentDate, usage);
+            trendMap.set(eventDate, currentDate);
+          }
+        }
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  const days = [...dayMap.values()]
+    .sort((left, right) => left.date.localeCompare(right.date))
+    .map((row) => ({
+      ...row,
+      models: [...row.models].sort((left, right) => left.localeCompare(right)),
+    }));
+  const trend = materializeTrendRows(range, trendMap);
+  const byModel = [...modelMap.values()].sort((left, right) => {
+    if (right.totalTokens !== left.totalTokens) {
+      return right.totalTokens - left.totalTokens;
+    }
+    return left.model.localeCompare(right.model);
+  });
+
+  return {
+    scope: 'local-machine',
+    timezone: timeZone,
+    range,
+    sources: {
+      sessionsDir,
+      archivedSessionsDir,
+      includeArchived,
+    },
+    filesScanned: entries.length,
+    tokenEventCount,
+    summary,
+    days,
+    trend,
+    byModel,
+  };
+}
+
+function iterRolloutFiles(rootDir) {
+  if (!fs.existsSync(rootDir)) return [];
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) {
+        files.push(fullPath);
+      }
+    }
+  };
+  walk(rootDir);
+  return files;
+}
+
+function emptyUsageRow() {
+  return {
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    outputTokens: 0,
+    reasoningOutputTokens: 0,
+    totalTokens: 0,
+  };
+}
+
+function materializeTrendRows(range, trendMap) {
+  const rows = [...trendMap.values()].sort((left, right) =>
+    left.date.localeCompare(right.date),
+  );
+  if (rows.length === 0) {
+    return [];
+  }
+  if (!range.trendFrom || !range.trendTo || range.trendFrom > range.trendTo) {
+    return rows;
+  }
+  const materialized = [];
+  for (let date = range.trendFrom; date <= range.trendTo; date = addDays(date, 1)) {
+    materialized.push(
+      trendMap.get(date) ?? {
+        date,
+        eventCount: 0,
+        ...emptyUsageRow(),
+      },
+    );
+  }
+  return materialized;
+}
+
+function usageFromEvent(event) {
+  return {
+    model: event.model ?? '(unknown)',
+    inputTokens: numberOrZero(event.lastInputTokens),
+    cachedInputTokens: numberOrZero(event.lastCachedInputTokens),
+    outputTokens: numberOrZero(event.lastOutputTokens),
+    reasoningOutputTokens: numberOrZero(event.lastReasoningOutputTokens),
+    totalTokens: numberOrZero(event.lastTotalTokens),
+  };
+}
+
+function accumulateUsage(target, usage) {
+  target.inputTokens += usage.inputTokens;
+  target.cachedInputTokens += usage.cachedInputTokens;
+  target.outputTokens += usage.outputTokens;
+  target.reasoningOutputTokens += usage.reasoningOutputTokens;
+  target.totalTokens += usage.totalTokens;
+}
+
+function numberOrZero(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function formatDateInTimeZone(timestampMs, timeZone) {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(new Date(timestampMs));
+  const values = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+  return `${values.year}-${values.month}-${values.day}`;
+}
+
+function normalizeDateString(value, label) {
+  if (!DATE_RE.test(String(value))) {
+    throw new Error(`${label} must be in YYYY-MM-DD format`);
+  }
+  const [yearRaw, monthRaw, dayRaw] = String(value).split('-');
+  const year = Number(yearRaw);
+  const month = Number(monthRaw);
+  const day = Number(dayRaw);
+  const normalized = new Date(Date.UTC(year, month - 1, day));
+  if (
+    Number.isNaN(normalized.getTime()) ||
+    normalized.getUTCFullYear() !== year ||
+    normalized.getUTCMonth() !== month - 1 ||
+    normalized.getUTCDate() !== day
+  ) {
+    throw new Error(`${label} must be a valid calendar date`);
+  }
+  return `${yearRaw}-${monthRaw}-${dayRaw}`;
+}
+
+function addDays(dateString, deltaDays) {
+  const [year, month, day] = dateString.split('-').map(Number);
+  const shifted = new Date(Date.UTC(year, month - 1, day + deltaDays));
+  const nextYear = shifted.getUTCFullYear();
+  const nextMonth = String(shifted.getUTCMonth() + 1).padStart(2, '0');
+  const nextDay = String(shifted.getUTCDate()).padStart(2, '0');
+  return `${nextYear}-${nextMonth}-${nextDay}`;
+}
+
+function isWithinDateRange(date, from, to) {
+  if (from && date < from) return false;
+  if (to && date > to) return false;
+  return true;
+}

package/src/runtime-config.js

@@ -9,6 +9,7 @@ import {
   DEFAULT_CURRENT_APP_DIR,
   DEFAULT_HOME_BIN_LINK,
   DEFAULT_INSTALL_ROOT,
+  DEFAULT_LAUNCH_AGENT_PATH,
   DEFAULT_LAUNCHD_LABEL,
   DEFAULT_LOCAL_BIN_DIR,
   DEFAULT_LOCAL_BIN_PATH,
@@ -26,6 +27,7 @@ export function defaultRuntimeConfig(configFile = DEFAULT_CONFIG_FILE) {
   const installRoot = path.dirname(configFile);
   const appRoot = path.join(installRoot, 'app');
   const currentAppDir = path.join(appRoot, 'current');
+  const launchdLabel = DEFAULT_LAUNCHD_LABEL;
   return {
     configFile,
     installRoot,
@@ -44,8 +46,13 @@ export function defaultRuntimeConfig(configFile = DEFAULT_CONFIG_FILE) {
     homeBinLink: DEFAULT_HOME_BIN_LINK,
     stdoutLogPath: path.join(installRoot, 'logs', path.basename(DEFAULT_STDOUT_LOG_PATH)),
     stderrLogPath: path.join(installRoot, 'logs', path.basename(DEFAULT_STDERR_LOG_PATH)),
-    launchdLabel: DEFAULT_LAUNCHD_LABEL,
-    plistPath: DEFAULT_PLIST_PATH,
+    launchdLabel,
+    plistPath: path.join(installRoot, 'launchd', `${launchdLabel}.plist`),
+    launchAgentPath: path.join(
+      path.dirname(DEFAULT_LAUNCH_AGENT_PATH),
+      `${launchdLabel}.plist`,
+    ),
+    autoStartOnLogin: true,
   };
 }
 
@@ -65,6 +72,17 @@ export function normalizeRuntimeConfig(runtime) {
   const appRoot = runtime.appRoot || path.join(installRoot, 'app');
   const currentAppDir = runtime.currentAppDir || path.join(appRoot, 'current');
   const localBinDir = runtime.localBinDir || DEFAULT_LOCAL_BIN_DIR;
+  const launchdLabel = runtime.launchdLabel || DEFAULT_LAUNCHD_LABEL;
+  const defaultPlistPath = path.join(installRoot, 'launchd', `${launchdLabel}.plist`);
+  const defaultLaunchAgentPath = path.join(
+    path.dirname(DEFAULT_LAUNCH_AGENT_PATH),
+    `${launchdLabel}.plist`,
+  );
+  const legacyLaunchAgentPath = path.join(
+    path.dirname(DEFAULT_LAUNCH_AGENT_PATH),
+    `${launchdLabel}.plist`,
+  );
+  const rawPlistPath = runtime.plistPath || defaultPlistPath;
   return {
     ...runtime,
     configFile: runtime.configFile || DEFAULT_CONFIG_FILE,
@@ -84,8 +102,14 @@ export function normalizeRuntimeConfig(runtime) {
     homeBinLink: runtime.homeBinLink || DEFAULT_HOME_BIN_LINK,
     stdoutLogPath: runtime.stdoutLogPath || path.join(installRoot, 'logs', 'stdout.log'),
     stderrLogPath: runtime.stderrLogPath || path.join(installRoot, 'logs', 'stderr.log'),
-    launchdLabel: runtime.launchdLabel || DEFAULT_LAUNCHD_LABEL,
-    plistPath: runtime.plistPath || DEFAULT_PLIST_PATH,
+    launchdLabel,
+    plistPath:
+      rawPlistPath === legacyLaunchAgentPath
+        ? defaultPlistPath
+        : rawPlistPath,
+    launchAgentPath: runtime.launchAgentPath || defaultLaunchAgentPath,
+    autoStartOnLogin:
+      runtime.autoStartOnLogin === undefined ? true : Boolean(runtime.autoStartOnLogin),
   };
 }
 
@@ -112,6 +136,8 @@ export function saveRuntimeConfig(runtime) {
     stderrLogPath: normalized.stderrLogPath,
     launchdLabel: normalized.launchdLabel,
     plistPath: normalized.plistPath,
+    launchAgentPath: normalized.launchAgentPath,
+    autoStartOnLogin: normalized.autoStartOnLogin,
   })}\n`);
   return normalized;
 }
@@ -136,7 +162,9 @@ export function formatStatusOutput(runtime, status) {
     stdoutLogPath: runtime.stdoutLogPath,
     stderrLogPath: runtime.stderrLogPath,
     plistPath: runtime.plistPath,
+    launchAgentPath: runtime.launchAgentPath,
     label: runtime.launchdLabel,
+    autoStartOnLogin: runtime.autoStartOnLogin,
     onlineThresholdSeconds: STATUS_ONLINE_THRESHOLD_SECONDS,
   };
 }

package/src/utils.js

@@ -51,3 +51,18 @@ export function computeEventUid(collectorId, relpath, lineNo) {
   const raw = Buffer.from(`${collectorId}|${relpath}|${lineNo}`, 'utf8');
   return createHash('sha1').update(raw).digest('hex');
 }
+
+export function readPersistentCollectorId(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    return content || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writePersistentCollectorId(filePath, id) {
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, id, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}