agent-usage-report 0.1.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md - agent-usage-report
+
+## Scope
+- This is a standalone TypeScript CLI package intended for `pnpm`, `bun`, `node`, and eventual `npx` usage.
+
+## Purpose
+- Generate a self-contained local agent usage HTML report and JSON payload
+- Maintain feature parity with the Python implementation in the sibling local project
+- Support current local providers:
+  - Codex
+  - Claude Code
+  - OpenCode
+  - Pi Coding Agent
+- Preserve provider-aware reporting:
+  - per-provider views
+  - combined view
+  - daily totals
+  - monthly rollups
+  - Codex and Claude monthly spend-vs-plan comparison
+  - Claude `history.jsonl` activity-only fallback days
+
+## Primary Entry Points
+- CLI entry: `src/cli.ts`
+- Core logic: `src/generator.ts`
+- HTML template: `src/template.html`
+- Tests: `test/generator.test.ts`
+
+## Build And Test
+- Install: `pnpm install`
+- Typecheck: `pnpm run typecheck`
+- Test: `pnpm run test`
+- Build: `pnpm run build`
+- Smoke run:
+  - `node dist/cli.js --help`
+  - `bun run src/cli.ts --help`
+
+## Packaging Expectations
+- Package name: `agent-usage-report`
+- Intended runner UX:
+  - `npx agent-usage-report@latest`
+  - `bunx agent-usage-report@latest`
+- Do not introduce native dependencies unless strictly required for distribution.
+- Prefer Node built-ins over native modules when possible so package-runner adoption stays easy.
+
+## Current CLI Surface
+- `--codex-home`
+- `--claude-config-dir`
+- `--opencode-dir`
+- `--pi-agent-dir`
+- `--timezone`
+- `--output-html`
+- `--output-json`
+- `--skip-archived`
+
+## Implementation Notes
+- Keep the JSON payload shape aligned with the Python project:
+  - `schemaVersion`
+  - `providerOrder`
+  - `providers`
+  - `combined`
+  - top-level default-provider mirrors
+- Claude `history.jsonl` days are activity-only:
+  - they should render in the heatmap
+  - they must not contribute to token totals or spend
+- OpenCode should prefer `opencode.db` when available and fall back to `storage/message/**/*.json`
+
+## Editing Guidance
+- Prefer targeted edits in `src/generator.ts` until the port stabilizes
+- If changing the UI, edit `src/template.html` or the template-loading flow carefully
+- After behavior changes:
+  - rerun `pnpm run typecheck`
+  - rerun `pnpm run test`
+  - rerun `pnpm run build`
+
+## Non-Goals
+- Do not turn this into a monorepo unless clearly needed
+- Do not add a backend here
+- Do not reduce current provider/report parity with the Python version

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ignacio Alonso
+
+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,77 @@
+# agent-usage-report
+
+`agent-usage-report` scans local agent usage data on your machine and generates a self-contained HTML report you can open directly in the browser.
+
+Current providers:
+- Codex
+- Claude Code
+- OpenCode
+- Pi Coding Agent
+
+Features:
+- GitHub-style daily heatmap
+- Per-provider and combined views
+- Estimated token-cost reporting
+- Daily cost tables
+- Monthly spend-vs-plan comparison for Codex and Claude
+- Claude legacy activity fallback from `history.jsonl`
+
+## Quick Start
+
+Run without installing globally:
+
+```bash
+npx agent-usage-report@latest
+```
+
+With Bun:
+
+```bash
+bunx agent-usage-report@latest
+```
+
+Local development:
+
+```bash
+pnpm install
+pnpm run build
+node dist/cli.js
+```
+
+## Usage
+
+```bash
+agent-usage-report \
+  --codex-home ~/.codex \
+  --claude-config-dir ~/.config/claude,~/.claude \
+  --opencode-dir ~/.local/share/opencode \
+  --pi-agent-dir ~/.pi/agent \
+  --timezone America/Mexico_City \
+  --output-html agent-usage-report.html \
+  --output-json agent-usage-data.json
+```
+
+Flags:
+- `--codex-home`: Codex home directory
+- `--claude-config-dir`: Claude config directory or comma-separated directories
+- `--opencode-dir`: OpenCode data directory
+- `--pi-agent-dir`: Pi Coding Agent directory or sessions directory
+- `--timezone`: IANA timezone for day bucketing
+- `--output-html`: HTML output path
+- `--output-json`: JSON output path
+- `--skip-archived`: skip `~/.codex/archived_sessions`
+
+## Privacy
+
+The CLI reads local usage data and generates local files.
+
+The generated HTML and JSON reports stay on your machine unless you choose to share them manually.
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run test
+pnpm run build
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "./generator.js";
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/generator.d.ts

@@ -0,0 +1,112 @@
+declare const FREE_MODEL_PRICING: {
+    inputCostPerMToken: number;
+    cachedInputCostPerMToken: number;
+    outputCostPerMToken: number;
+};
+declare const SCAN_OUTPUT_KEYS: readonly ["filesScanned", "jsonlFilesScanned", "jsonFilesScanned", "parseErrors", "nullInfoEventsSkipped", "duplicateEventsSkipped", "syntheticEventsSkipped", "zeroTotalEventsSkipped", "tokenEventsCounted", "unsupportedLegacyFiles", "activityOnlyDays"];
+type Pricing = typeof FREE_MODEL_PRICING;
+type ScanKey = (typeof SCAN_OUTPUT_KEYS)[number];
+export interface CliArgs {
+    codexHome: string;
+    claudeConfigDir: string | null;
+    opencodeDir: string | null;
+    piAgentDir: string | null;
+    timezone: string;
+    outputHtml: string;
+    outputJson: string;
+    skipArchived: boolean;
+}
+interface UsageTotals {
+    input_tokens: number;
+    cached_input_tokens: number;
+    output_tokens: number;
+    reasoning_output_tokens: number;
+    total_tokens: number;
+}
+interface CostBreakdown {
+    inputUSD: number;
+    cachedInputUSD: number;
+    outputUSD: number;
+    totalUSD: number;
+}
+interface ModelUsageAccumulator extends UsageTotals {
+    events: number;
+    is_fallback_model: boolean;
+}
+interface DailyUsageAccumulator extends UsageTotals {
+    events: number;
+    model_usage: Record<string, ModelUsageAccumulator>;
+}
+export interface DailyReportRow {
+    date: string;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+    events: number;
+    costBreakdownUSD: CostBreakdown;
+    costUSD: number;
+    modelTotals: Record<string, number>;
+    modelBreakdown: Array<Record<string, unknown>>;
+    displayValue: number;
+}
+export interface MonthlyReportRow {
+    month: string;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+    events: number;
+    activeDays: number;
+    costBreakdownUSD: CostBreakdown;
+    costUSD: number;
+    modelTotals: Record<string, number>;
+    modelBreakdown: Array<Record<string, unknown>>;
+}
+interface ProviderReport {
+    providerId: string;
+    providerLabel: string;
+    providerShortLabel: string;
+    sourceHome: string | null;
+    days: DailyReportRow[];
+    monthly: MonthlyReportRow[];
+    pricing: {
+        source: string;
+        sourceLabel: string;
+        url: string;
+        missingModels: string[];
+    };
+    costTotalsUSD: CostBreakdown;
+    scan: Record<ScanKey, number>;
+}
+interface ProviderScanResult {
+    providerId: string;
+    providerLabel: string;
+    providerShortLabel: string;
+    sourceHome: string | null;
+    dailyUsage: Map<string, DailyUsageAccumulator>;
+    displayValuesByDay: Map<string, number>;
+    stats: Record<ScanKey, number>;
+}
+interface ResolvedPricing {
+    requestedModel: string;
+    resolvedModel: string | null;
+    pricing: Pricing;
+    isMissing: boolean;
+    isAlias: boolean;
+    source: string;
+}
+export declare function fetchLiteLLMPricingDataset(): Promise<Record<string, Record<string, unknown>>>;
+export declare function resolveModelPricing(model: string, dataset: Record<string, Record<string, unknown>> | null): ResolvedPricing;
+export declare function calculateCostBreakdown(usage: UsageTotals, pricing: Pricing): CostBreakdown;
+export declare function providerScanHasUsage(scan: ProviderScanResult): boolean;
+export declare function buildMonthlyRollups(reportDays: DailyReportRow[]): MonthlyReportRow[];
+export declare function buildCombinedReport(providerReports: ProviderReport[]): ProviderReport;
+export declare function buildReportPayload(providerScans: ProviderScanResult[], timeZone: string): Promise<Record<string, unknown>>;
+export declare function writeOutput(report: Record<string, unknown>, outputHtml: string, outputJson: string): Promise<void>;
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export declare function generateReport(args: CliArgs): Promise<Record<string, unknown>>;
+export declare function main(argv?: string[]): Promise<void>;
+export {};