claudeusage-sync 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adilbek Bazarkulov
+
+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

@@ -1,5 +1,260 @@
 # claudeusage-sync
 
-Placeholder package. The full CLI for syncing Claude Code usage stats to [claudeusage.com](https://claudeusage.com) is in development.
+Turn your local Claude Code usage into a public profile and leaderboard at [claudeusage.com](https://claudeusage.com) — without uploading a single prompt.
 
-Check back soon.
+[![version](https://img.shields.io/github/package-json/v/bazarkua/claudeusage-sync?label=version)](https://www.npmjs.com/package/claudeusage-sync)
+[![license: MIT](https://img.shields.io/github/license/bazarkua/claudeusage-sync)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+
+```sh
+npx claudeusage-sync
+```
+
+The first run opens your browser for a one-click device approval, reads your local
+Claude Code session files, asks for your consent, and uploads **aggregate numeric
+stats only**. Every later run reuses the cached token and uploads just what is new.
+
+---
+
+## What it does
+
+Claude Code records each session locally as JSONL files under `~/.claude/projects/`.
+Those files contain your full prompts and responses, but they also contain per-message
+token counts. `claudeusage-sync`:
+
+1. Streams every `~/.claude/projects/*/*.jsonl` file line by line.
+2. Extracts **only** the usage numbers from each message (token counts, model id,
+   timestamp, and the ids needed to de-duplicate). Message text is never read.
+3. De-duplicates records by `messageId:requestId`, keeping the highest `output_tokens`
+   (Claude Code writes cumulative streaming values, so the max is the final count).
+4. Groups records by your **local day** and computes WakaTime-style active hours
+   (the sum of gaps shorter than 10 minutes between consecutive messages).
+5. Builds an aggregate payload and `POST`s it to `https://claudeusage.com/api/ingest`.
+
+The result powers your profile (`/u/<username>`), the global leaderboard, your activity
+grid, and an API-equivalent cost estimate. You can sign in with a display name or stay
+anonymous.
+
+---
+
+## Privacy
+
+This is the whole point of the project, so it is worth being precise. The CLI is
+MIT-licensed and source-available — you can read every line in [`src/`](./src) and
+confirm the claims below for yourself.
+
+### What is uploaded
+
+Only aggregate, numeric usage data. The exact shape posted to `/api/ingest` is defined
+in [`src/aggregate/payload.ts`](./src/aggregate/payload.ts):
+
+```ts
+type IngestPayload = {
+  cliVersion: string;
+  schema: 1;
+  os: "darwin" | "linux" | "win32";
+  machineId: string;       // one-way SHA-256 hash, see below
+  windowStart: string;     // ISO timestamp of the earliest record in this sync
+  windowEnd: string;       // ISO timestamp of the latest record in this sync
+  sessionCount: number;    // distinct sessions in the window
+  dailyBuckets: Array<{
+    date: string;          // YYYY-MM-DD, your local day
+    hoursActive: number;
+    sessionCount: number;
+    perModel: Record<string, {
+      inputTokens: number;
+      outputTokens: number;
+      cacheCreateTokens: number;
+      cacheReadTokens: number;
+      messageCount: number;
+      sessionCount: number;
+      hoursActive: number;
+      firstMessageAt: string;  // ISO timestamp
+      lastMessageAt: string;   // ISO timestamp
+    }>;
+  }>;
+};
+```
+
+That is it: token totals, message and session counts, active hours, the per-model mix,
+and day-level activity. No content of any kind is in this object.
+
+### What is never uploaded
+
+Verifiable from [`src/parse/jsonl.ts`](./src/parse/jsonl.ts) (the only code that reads
+your Claude files) and [`src/aggregate/payload.ts`](./src/aggregate/payload.ts):
+
+- **Prompts, responses, or any message content** — the parser reads only token-count
+  fields from each line and discards the rest.
+- **Your code, file contents, or raw JSONL lines** — nothing from the files is forwarded.
+- **File paths, project directory names, or repo names** — project folders are only used
+  to locate files; their names never enter the payload.
+- **Individual message, request, or session ids** — these are used locally for
+  de-duplication and the incremental-sync watermark; the payload carries only *counts*.
+- **Your email address or which provider you signed in with** — the CLI never reads or
+  sends these. Your identity is established entirely in the browser during device approval.
+- **Your raw hostname or OS username** — see `machineId` below.
+
+### Two fields that deserve a plain explanation
+
+- **`machineId`** is `SHA-256(hostname + ":" + osUsername)` — a one-way hash computed on
+  your machine (see [`src/auth/machine.ts`](./src/auth/machine.ts)). Your real hostname and
+  username never leave the device; the server only ever sees the hash, and uses it to
+  group and de-duplicate syncs across the machines you sync from. During the initial
+  device-auth request the CLI also sends `SHA-256(hostname)` for the same purpose.
+- **Timestamps.** The payload contains coarse time bounds only: the `windowStart` /
+  `windowEnd` of the sync, and the first/last message time per model per day. There is no
+  per-message timestamp and no minute-by-minute activity log. Public profile pages round
+  these to the day (and at most the hour for day-detail views).
+
+Your sync token (`cu_live_...`) is your credential. It is stored locally at
+`~/.claudeusage/config.json` with `0600` permissions and sent only as an
+`Authorization: Bearer` header to authenticate uploads.
+
+See the full policy at [claudeusage.com/privacy](https://claudeusage.com/privacy).
+
+---
+
+## Quickstart
+
+```sh
+# first run: opens your browser for a one-click device approval, then asks consent
+npx claudeusage-sync
+
+# later runs: reuses the cached token, uploads only records newer than the last sync
+npx claudeusage-sync
+```
+
+On the first run the CLI prints exactly what will be uploaded and waits for a `y/N`
+confirmation before sending anything. After you approve once, the consent is remembered.
+
+Want to see what would be sent without uploading? Use `--dry-run`:
+
+```sh
+npx claudeusage-sync --dry-run
+```
+
+---
+
+## Commands
+
+```sh
+claudeusage-sync              # (default) authenticate if needed, then sync new usage
+claudeusage-sync doctor       # show local Claude Code source coverage
+claudeusage-sync status       # show last sync time and masked token
+claudeusage-sync unlink       # remove local config so the next sync starts fresh
+claudeusage-sync logout       # alias of unlink
+```
+
+| Command  | Description |
+| -------- | ----------- |
+| *(none)* | Read new usage since the last sync, then upload aggregates. Authenticates first if needed. |
+| `doctor` | Run the same parser as `sync` and print source coverage: JSONL files scanned, usable record count, first/last detailed-usage dates, the local sync watermark, and whether Claude's legacy `stats-cache.json` exists. |
+| `status` | Print the last sync time, masked token, API base, and config path. |
+| `unlink` | Delete `~/.claudeusage/config.json` so the next run re-authenticates from scratch. |
+| `logout` | Alias of `unlink`. |
+
+### Flags
+
+These apply to the default sync command:
+
+| Flag                  | Description |
+| --------------------- | ----------- |
+| `--dry-run`           | Parse and build the payload, print a summary, but do **not** upload. |
+| `--since <YYYY-MM-DD>` | Only read records on or after this date (overrides the saved watermark). |
+| `--token <token>`     | Use this sync token instead of the browser device flow (headless / CI). |
+| `--version`           | Print the installed CLI version. |
+| `--help`              | Show usage. |
+
+### Environment variables
+
+Mostly for CI and local testing:
+
+| Variable                 | Effect |
+| ------------------------ | ------ |
+| `CLAUDEUSAGE_API`        | Override the API base URL (default `https://claudeusage.com`). |
+| `CLAUDE_CONFIG_DIR`      | Override the Claude config directory; the CLI reads `<dir>/projects`. Default `~/.claude`. |
+| `CLAUDEUSAGE_CONFIG_DIR` | Override where the CLI stores its own config (default `~`, i.e. `~/.claudeusage`). |
+| `CLAUDEUSAGE_ASSUME_YES` | Set to `1` to skip the interactive first-run consent prompt (use in CI). |
+
+---
+
+## Requirements
+
+- **Node.js 22 or newer** (Node 20 reaches end-of-life in April 2026).
+- Claude Code installed and used at least once, so that `~/.claude/projects/` exists.
+
+---
+
+## How device authentication works
+
+The first sign-in uses an [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)-style
+OAuth device authorization flow, so the CLI never handles your password:
+
+1. The CLI calls `POST /api/cli/auth/start` and receives a short user code plus a
+   verification URL.
+2. It opens that URL in your browser (and prints the code in case the browser does not
+   open). You sign in with Google or GitHub and approve the device.
+3. The CLI polls `POST /api/cli/auth/poll` until the request is approved, denied, or
+   expires, honoring `slow_down` back-off.
+4. On approval it receives a long-lived sync token (`cu_live_...`) and writes it to
+   `~/.claudeusage/config.json`.
+
+If a stored token is ever rejected (for example, you revoked it from the dashboard), the
+CLI automatically re-runs the device flow and retries the upload.
+
+---
+
+## Headless and CI usage
+
+Browsers are not available in CI. Create a sync token from your dashboard settings and
+pass it with `--token`:
+
+```sh
+CLAUDEUSAGE_ASSUME_YES=1 npx claudeusage-sync --token="cu_live_xxxxxxxx..."
+```
+
+`CLAUDEUSAGE_ASSUME_YES=1` skips the interactive consent prompt so the run is fully
+non-interactive. The token authenticates uploads exactly like a browser-approved session.
+
+---
+
+## Links
+
+- Website and leaderboard: [claudeusage.com](https://claudeusage.com)
+- Privacy policy: [claudeusage.com/privacy](https://claudeusage.com/privacy)
+- Source and issues: [github.com/bazarkua/claudeusage-sync](https://github.com/bazarkua/claudeusage-sync)
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. The project is small and dependency-light:
+
+```sh
+git clone https://github.com/bazarkua/claudeusage-sync.git
+cd claudeusage-sync
+npm install
+npm run build        # compile TypeScript to dist/
+node bin/cli.js --dry-run
+```
+
+To test against a local backend or fixture data:
+
+```sh
+CLAUDEUSAGE_API=http://localhost:3000 \
+CLAUDE_CONFIG_DIR=/tmp/fake-claude \
+node bin/cli.js --dry-run
+```
+
+If you find a privacy or security issue, please open an issue (or contact the maintainer
+privately for sensitive reports) rather than sending a PR with details.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Adilbek Bazarkulov
+
+*Not affiliated with Anthropic. "Claude" and "Claude Code" are used descriptively to
+refer to the tools whose local usage this CLI reads.*

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli.js").catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/aggregate/payload.js

@@ -0,0 +1,122 @@
+import { computeMachineId, detectOs } from "../auth/machine.js";
+import { recordWatermarkKey } from "../parse/dedupe.js";
+import { computeHoursActive, groupByLocalDay } from "../parse/hours.js";
+function emptyPayload(cliVersion) {
+    const now = new Date().toISOString();
+    return {
+        cliVersion,
+        dailyBuckets: [],
+        machineId: computeMachineId(),
+        os: detectOs(),
+        schema: 1,
+        sessionCount: 0,
+        windowEnd: now,
+        windowStart: now,
+    };
+}
+export function buildPayload(records, cliVersion) {
+    if (records.length === 0) {
+        return emptyPayload(cliVersion);
+    }
+    const byDay = groupByLocalDay(records);
+    const sessions = new Set();
+    let minTimestamp = Number.POSITIVE_INFINITY;
+    let maxTimestamp = Number.NEGATIVE_INFINITY;
+    const dailyBuckets = Array.from(byDay.entries())
+        .map(([date, dayRecords]) => {
+        const perModel = {};
+        const daySessions = new Set();
+        for (const record of dayRecords) {
+            const timestampMs = new Date(record.timestamp).getTime();
+            minTimestamp = Math.min(minTimestamp, timestampMs);
+            maxTimestamp = Math.max(maxTimestamp, timestampMs);
+            if (record.sessionId) {
+                sessions.add(record.sessionId);
+                daySessions.add(record.sessionId);
+            }
+            const model = perModel[record.model] ?? {
+                cacheCreateTokens: 0,
+                cacheReadTokens: 0,
+                firstMessageAt: record.timestamp,
+                hoursActive: 0,
+                inputTokens: 0,
+                lastMessageAt: record.timestamp,
+                messageCount: 0,
+                outputTokens: 0,
+                records: [],
+                sessionCount: 0,
+                sessions: new Set(),
+            };
+            model.cacheCreateTokens += record.cacheCreateTokens;
+            model.cacheReadTokens += record.cacheReadTokens;
+            model.inputTokens += record.inputTokens;
+            model.outputTokens += record.outputTokens;
+            model.messageCount += 1;
+            model.records.push(record);
+            if (record.sessionId) {
+                model.sessions.add(record.sessionId);
+            }
+            if (record.timestamp < model.firstMessageAt) {
+                model.firstMessageAt = record.timestamp;
+            }
+            if (record.timestamp > model.lastMessageAt) {
+                model.lastMessageAt = record.timestamp;
+            }
+            perModel[record.model] = model;
+        }
+        const finalPerModel = {};
+        for (const [modelId, model] of Object.entries(perModel)) {
+            finalPerModel[modelId] = {
+                cacheCreateTokens: model.cacheCreateTokens,
+                cacheReadTokens: model.cacheReadTokens,
+                firstMessageAt: model.firstMessageAt,
+                hoursActive: computeHoursActive(model.records),
+                inputTokens: model.inputTokens,
+                lastMessageAt: model.lastMessageAt,
+                messageCount: model.messageCount,
+                outputTokens: model.outputTokens,
+                sessionCount: model.sessions.size,
+            };
+        }
+        return {
+            date,
+            hoursActive: computeHoursActive(dayRecords),
+            perModel: finalPerModel,
+            sessionCount: daySessions.size,
+        };
+    })
+        .sort((a, b) => a.date.localeCompare(b.date));
+    return {
+        cliVersion,
+        dailyBuckets,
+        machineId: computeMachineId(),
+        os: detectOs(),
+        schema: 1,
+        sessionCount: sessions.size,
+        windowEnd: new Date(maxTimestamp).toISOString(),
+        windowStart: new Date(minTimestamp).toISOString(),
+    };
+}
+export function latestWatermark(records) {
+    let latest = null;
+    for (const record of records) {
+        if (!latest) {
+            latest = record;
+            continue;
+        }
+        if (record.timestamp > latest.timestamp) {
+            latest = record;
+            continue;
+        }
+        if (record.timestamp === latest.timestamp &&
+            recordWatermarkKey(record) > recordWatermarkKey(latest)) {
+            latest = record;
+        }
+    }
+    return latest
+        ? {
+            lastSyncAt: latest.timestamp,
+            lastSyncMessageId: recordWatermarkKey(latest),
+        }
+        : {};
+}

package/dist/api/ingest-client.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+const ingestResponseSchema = z.object({
+    accepted: z.boolean(),
+    batchId: z.string().optional(),
+    buckets: z.number().optional(),
+    duplicate: z.boolean().optional(),
+    messageCount: z.number(),
+    newRecords: z.number(),
+    updatedAt: z.string(),
+    userId: z.string(),
+});
+export class NeedsReauth extends Error {
+    constructor() {
+        super("needs_reauth");
+        this.name = "NeedsReauth";
+    }
+}
+export class RateLimited extends Error {
+    retryAfterSec;
+    constructor(retryAfterSec) {
+        super(`rate_limited:${retryAfterSec}s`);
+        this.retryAfterSec = retryAfterSec;
+        this.name = "RateLimited";
+    }
+}
+export class IngestConflict extends Error {
+    code;
+    retryAfterSec;
+    constructor(code, retryAfterSec) {
+        super(code);
+        this.code = code;
+        this.retryAfterSec = retryAfterSec;
+        this.name = "IngestConflict";
+    }
+}
+export async function postIngest(apiBase, token, payload) {
+    const response = await fetch(`${apiBase}/api/ingest`, {
+        body: JSON.stringify(payload),
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+        },
+        method: "POST",
+    });
+    if (response.status === 401) {
+        throw new NeedsReauth();
+    }
+    if (response.status === 429) {
+        const retryAfterSec = Number(response.headers.get("retry-after") ?? "60");
+        throw new RateLimited(Number.isFinite(retryAfterSec) ? retryAfterSec : 60);
+    }
+    if (response.status === 409) {
+        const retryAfterSec = Number(response.headers.get("retry-after") ?? "");
+        const body = await response.json().catch(() => null);
+        const code = body && typeof body.error === "string" ? body.error : "ingest_conflict";
+        throw new IngestConflict(code, Number.isFinite(retryAfterSec) ? retryAfterSec : undefined);
+    }
+    if (!response.ok) {
+        throw new Error(`ingest failed: ${response.status} ${await response.text().catch(() => "")}`);
+    }
+    return ingestResponseSchema.parse(await response.json());
+}

package/dist/auth/config.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { z } from "zod";
+const configSchema = z.object({
+    apiBase: z.string().url(),
+    consentAcceptedAt: z.string().optional(),
+    lastSyncAt: z.string().optional(),
+    lastSyncMessageId: z.string().optional(),
+    token: z.string().regex(/^cu_live_[a-f0-9]{48}$/),
+});
+export function configDir() {
+    return resolve(process.env.CLAUDEUSAGE_CONFIG_DIR ?? homedir(), ".claudeusage");
+}
+export function configFile() {
+    return resolve(configDir(), "config.json");
+}
+export async function readConfig() {
+    try {
+        const raw = await readFile(configFile(), "utf8");
+        return configSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeConfig(config) {
+    await mkdir(configDir(), { recursive: true, mode: 0o700 });
+    await writeFile(configFile(), `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600,
+    });
+}
+export async function deleteConfig() {
+    await rm(configFile(), { force: true });
+}

package/dist/auth/device-flow.js

@@ -0,0 +1,90 @@
+import chalk from "chalk";
+import open from "open";
+import ora from "ora";
+import { z } from "zod";
+import { readPackageInfo } from "../package.js";
+import { writeConfig } from "./config.js";
+import { computeHostnameHash, computeMachineId, detectOs, } from "./machine.js";
+const startResponseSchema = z.object({
+    deviceCode: z.string(),
+    expiresIn: z.number().int().positive(),
+    interval: z.number().positive(),
+    userCode: z.string(),
+    verificationUri: z.string().url(),
+    verificationUriComplete: z.string().url(),
+});
+const pollResponseSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("pending") }),
+    z.object({ status: z.literal("slow_down") }),
+    z.object({ status: z.literal("denied") }),
+    z.object({ status: z.literal("expired") }),
+    z.object({
+        status: z.literal("approved"),
+        token: z.string().regex(/^cu_live_[a-f0-9]{48}$/),
+        userId: z.string(),
+        username: z.string().nullable(),
+    }),
+]);
+const packageInfo = readPackageInfo(import.meta.url);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function runDeviceFlow(apiBase) {
+    const startResponse = await fetch(`${apiBase}/api/cli/auth/start`, {
+        body: JSON.stringify({
+            cliVersion: packageInfo.version,
+            hostnameHash: computeHostnameHash(),
+            machineId: computeMachineId(),
+            os: detectOs(),
+        }),
+        headers: { "content-type": "application/json" },
+        method: "POST",
+    });
+    if (!startResponse.ok) {
+        throw new Error(`device auth start failed: ${startResponse.status}`);
+    }
+    const start = startResponseSchema.parse(await startResponse.json());
+    console.log("");
+    console.log(chalk.bold("authorize this device:"));
+    console.log(`  ${chalk.hex("#d97757")(start.verificationUriComplete)}`);
+    console.log("");
+    console.log(`${chalk.gray("if the browser does not open, enter code")} ${chalk.bold(start.userCode)} ${chalk.gray("at")} ${start.verificationUri}`);
+    console.log("");
+    await open(start.verificationUriComplete).catch(() => undefined);
+    const spinner = ora("waiting for browser approval...").start();
+    let intervalMs = Math.max(1000, start.interval * 1000);
+    const expiresAt = Date.now() + start.expiresIn * 1000;
+    while (Date.now() < expiresAt) {
+        await sleep(intervalMs);
+        const pollResponse = await fetch(`${apiBase}/api/cli/auth/poll`, {
+            body: JSON.stringify({ deviceCode: start.deviceCode }),
+            headers: { "content-type": "application/json" },
+            method: "POST",
+        });
+        const parsed = pollResponseSchema.safeParse(await pollResponse.json().catch(() => ({})));
+        if (!parsed.success) {
+            spinner.fail("unexpected server response");
+            throw new Error("bad poll response");
+        }
+        if (parsed.data.status === "pending") {
+            continue;
+        }
+        if (parsed.data.status === "slow_down") {
+            intervalMs = Math.min(intervalMs * 2, 30_000);
+            continue;
+        }
+        if (parsed.data.status === "denied") {
+            spinner.fail("denied in the browser");
+            throw new Error("device authorization denied");
+        }
+        if (parsed.data.status === "expired") {
+            spinner.fail("approval code expired");
+            throw new Error("device authorization expired");
+        }
+        spinner.succeed(`authorized as ${chalk.hex("#d97757")(parsed.data.username ?? parsed.data.userId)}`);
+        await writeConfig({ apiBase, token: parsed.data.token });
+        return parsed.data.token;
+    }
+    spinner.fail("approval timed out");
+    throw new Error("device authorization timed out");
+}

package/dist/auth/machine.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+import { hostname, userInfo } from "node:os";
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function computeMachineId() {
+    const username = userInfo().username || "unknown";
+    return sha256(`${hostname()}:${username}`);
+}
+export function computeHostnameHash() {
+    return sha256(hostname());
+}
+export function detectOs() {
+    if (process.platform === "darwin" ||
+        process.platform === "linux" ||
+        process.platform === "win32") {
+        return process.platform;
+    }
+    return "linux";
+}

package/dist/cli.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { runDoctor } from "./commands/doctor.js";
+import { runStatus } from "./commands/status.js";
+import { runSync } from "./commands/sync.js";
+import { runUnlink } from "./commands/unlink.js";
+import { readPackageInfo } from "./package.js";
+const packageInfo = readPackageInfo(import.meta.url);
+function handleError(error) {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+}
+const program = new Command();
+program
+    .name("claudeusage-sync")
+    .description("sync your Claude Code usage stats to claudeusage.com")
+    .version(packageInfo.version)
+    .option("--token <token>", "use this sync token instead of the browser device flow (headless/CI)")
+    .option("--dry-run", "parse and build the payload but do not upload")
+    .option("--since <date>", "only read records newer than this YYYY-MM-DD")
+    .action((options) => {
+    runSync(options).catch(handleError);
+});
+program
+    .command("doctor")
+    .description("show local Claude Code source coverage")
+    .action(() => {
+    runDoctor().catch(handleError);
+});
+program
+    .command("status")
+    .description("show last sync time and masked token")
+    .action(() => {
+    runStatus().catch(handleError);
+});
+program
+    .command("unlink")
+    .description("remove local config so the next sync starts fresh")
+    .action(() => {
+    runUnlink().catch(handleError);
+});
+program
+    .command("logout")
+    .description("alias of unlink")
+    .action(() => {
+    runUnlink().catch(handleError);
+});
+program.parseAsync().catch(handleError);

package/dist/commands/doctor.js

@@ -0,0 +1,111 @@
+import chalk from "chalk";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { readConfig } from "../auth/config.js";
+import { dedupe } from "../parse/dedupe.js";
+import { streamAllRecords } from "../parse/jsonl.js";
+import { resolveClaudeDir } from "../parse/paths.js";
+function formatIso(value) {
+    if (!value) {
+        return "none";
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return value;
+    }
+    return `${date.toLocaleString()} (${date.toISOString()})`;
+}
+function stringField(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+async function countDirectJsonlFiles(rootDir) {
+    const projects = await readdir(rootDir).catch(() => []);
+    let count = 0;
+    for (const project of projects) {
+        const projectPath = join(rootDir, project);
+        const projectStat = await stat(projectPath).catch(() => null);
+        if (!projectStat?.isDirectory()) {
+            continue;
+        }
+        const files = await readdir(projectPath).catch(() => []);
+        count += files.filter((file) => file.endsWith(".jsonl")).length;
+    }
+    return count;
+}
+async function readRecords(rootDir) {
+    const records = [];
+    for await (const record of streamAllRecords(rootDir)) {
+        records.push(record);
+    }
+    return records;
+}
+async function readLegacyStatsCache(rootDir) {
+    const statsPath = resolve(dirname(rootDir), "stats-cache.json");
+    const raw = await readFile(statsPath, "utf8").catch(() => null);
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object"
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runDoctor() {
+    const rootDir = resolveClaudeDir();
+    const [fileCount, records, config, legacy] = await Promise.all([
+        countDirectJsonlFiles(rootDir),
+        readRecords(rootDir),
+        readConfig(),
+        readLegacyStatsCache(rootDir),
+    ]);
+    const deduped = dedupe(records);
+    const firstRecord = deduped.at(0);
+    const lastRecord = deduped.at(-1);
+    console.log(chalk.bold("claudeusage source doctor"));
+    console.log("");
+    console.log("Claude projects path:", chalk.gray(rootDir));
+    console.log("JSONL files scanned: ", fileCount);
+    console.log("usage records:       ", records.length);
+    console.log("after dedupe:        ", deduped.length);
+    console.log("first detailed usage:", formatIso(firstRecord?.timestamp));
+    console.log("last detailed usage: ", formatIso(lastRecord?.timestamp));
+    console.log("");
+    if (config) {
+        console.log(chalk.bold("local sync config"));
+        console.log("api base:            ", config.apiBase);
+        console.log("last synced at:      ", config.lastSyncAt ?? "never");
+        console.log("last message id:     ", config.lastSyncMessageId ?? "none");
+    }
+    else {
+        console.log(chalk.bold("local sync config"));
+        console.log(chalk.yellow("not linked yet"));
+    }
+    console.log("");
+    console.log(chalk.bold("legacy stats cache"));
+    if (!legacy) {
+        console.log("not found");
+        return;
+    }
+    const firstSessionDate = stringField(legacy.firstSessionDate);
+    const lastComputedDate = stringField(legacy.lastComputedDate);
+    const totalMessages = numberField(legacy.totalMessages);
+    const totalSessions = numberField(legacy.totalSessions);
+    console.log("first session:       ", formatIso(firstSessionDate ?? undefined));
+    console.log("last computed:       ", lastComputedDate ?? "unknown");
+    console.log("messages:            ", totalMessages ?? "unknown");
+    console.log("sessions:            ", totalSessions ?? "unknown");
+    if (firstSessionDate &&
+        firstRecord?.timestamp &&
+        firstSessionDate < firstRecord.timestamp) {
+        console.log("");
+        console.log(chalk.yellow("legacy cache starts earlier than detailed JSONL; sync keeps it separate because it is aggregate/incomplete."));
+    }
+}

package/dist/commands/status.js

@@ -0,0 +1,18 @@
+import chalk from "chalk";
+import { configFile, readConfig } from "../auth/config.js";
+function maskToken(token) {
+    return `${token.slice(0, 12)}...${token.slice(-4)}`;
+}
+export async function runStatus() {
+    const config = await readConfig();
+    if (!config) {
+        console.log(chalk.yellow("not authorized. run `claudeusage-sync` to link this device."));
+        console.log(chalk.gray(`config: ${configFile()}`));
+        return;
+    }
+    console.log("token:          ", maskToken(config.token));
+    console.log("apiBase:        ", config.apiBase);
+    console.log("last synced at: ", config.lastSyncAt ?? "never");
+    console.log("last message id:", config.lastSyncMessageId ?? "none");
+    console.log("config:         ", configFile());
+}

package/dist/commands/sync.js

@@ -0,0 +1,175 @@
+import chalk from "chalk";
+import ora from "ora";
+import { buildPayload, latestWatermark } from "../aggregate/payload.js";
+import { IngestConflict, NeedsReauth, postIngest, RateLimited, } from "../api/ingest-client.js";
+import { deleteConfig, readConfig, writeConfig, } from "../auth/config.js";
+import { runDeviceFlow } from "../auth/device-flow.js";
+import { readPackageInfo } from "../package.js";
+import { dedupe, detectOutputTokenUndercount, recordWatermarkKey, } from "../parse/dedupe.js";
+import { streamAllRecords } from "../parse/jsonl.js";
+import { resolveClaudeDir } from "../parse/paths.js";
+const DEFAULT_API = "https://claudeusage.com";
+const packageInfo = readPackageInfo(import.meta.url);
+function apiBase() {
+    return (process.env.CLAUDEUSAGE_API ?? DEFAULT_API).replace(/\/$/, "");
+}
+function parseSince(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new Error(`bad --since value: ${value}`);
+    }
+    const ms = Date.parse(`${value}T00:00:00`);
+    if (!Number.isFinite(ms)) {
+        throw new Error(`bad --since value: ${value}`);
+    }
+    return ms;
+}
+function afterWatermark(record, config) {
+    if (!config.lastSyncAt) {
+        return true;
+    }
+    if (record.timestamp > config.lastSyncAt) {
+        return true;
+    }
+    return (record.timestamp === config.lastSyncAt &&
+        Boolean(config.lastSyncMessageId) &&
+        recordWatermarkKey(record) > config.lastSyncMessageId);
+}
+async function readRecords() {
+    const rootDir = resolveClaudeDir();
+    const records = [];
+    for await (const record of streamAllRecords(rootDir)) {
+        records.push(record);
+    }
+    return records;
+}
+// Shown once, on the first sync — transparency, not a question. Authorization
+// already happened in the browser device-approval step, so there's nothing to
+// answer here; the CLI just states exactly what it uploads and proceeds.
+function printUploadNotice(dayCount, sessionCount) {
+    console.log("");
+    console.log(chalk.bold("uploading aggregate usage only:"));
+    console.log(`  ${dayCount} day-buckets across ${sessionCount} sessions`);
+    console.log("  numeric totals only: tokens, hours, and message counts");
+    console.log(chalk.gray("  never uploaded: prompts, responses, file paths, project names, or raw files"));
+    console.log(chalk.gray("  privacy: https://claudeusage.com/privacy"));
+    console.log("");
+}
+function printDryRun(payload, records) {
+    const totals = payload.dailyBuckets.reduce((acc, bucket) => {
+        for (const model of Object.values(bucket.perModel)) {
+            acc.input += model.inputTokens;
+            acc.output += model.outputTokens;
+            acc.cacheCreate += model.cacheCreateTokens;
+            acc.cacheRead += model.cacheReadTokens;
+            acc.messages += model.messageCount;
+        }
+        return acc;
+    }, { cacheCreate: 0, cacheRead: 0, input: 0, messages: 0, output: 0 });
+    console.log(chalk.bold("\ndry run - payload summary:"));
+    console.log("  records:     ", records);
+    console.log("  windowStart: ", payload.windowStart);
+    console.log("  windowEnd:   ", payload.windowEnd);
+    console.log("  sessions:    ", payload.sessionCount);
+    console.log("  dailyBuckets:", payload.dailyBuckets.length);
+    console.log("  messages:    ", totals.messages);
+    console.log("  inputTokens: ", totals.input);
+    console.log("  outputTokens:", totals.output);
+    console.log("  cacheCreate: ", totals.cacheCreate);
+    console.log("  cacheRead:   ", totals.cacheRead);
+}
+async function uploadWithReauth(base, token, payload) {
+    const upload = ora(`uploading ${payload.dailyBuckets.length} day-buckets...`).start();
+    try {
+        const result = await postIngest(base, token, payload);
+        upload.succeed(result.duplicate
+            ? "already synced; duplicate upload ignored"
+            : `synced ${result.newRecords} day-buckets (${result.messageCount} messages)`);
+        return token;
+    }
+    catch (error) {
+        if (error instanceof NeedsReauth) {
+            upload.warn("token rejected; re-running device authorization");
+            await deleteConfig();
+            const freshToken = await runDeviceFlow(base);
+            const result = await postIngest(base, freshToken, payload);
+            console.log(chalk.green(result.duplicate
+                ? "already synced after re-auth; duplicate upload ignored"
+                : `synced after re-auth (${result.newRecords} day-buckets, ${result.messageCount} messages)`));
+            return freshToken;
+        }
+        if (error instanceof RateLimited) {
+            upload.fail(`rate-limited. retry in ${error.retryAfterSec}s.`);
+            throw error;
+        }
+        if (error instanceof IngestConflict) {
+            if (error.code === "ingest_overlap") {
+                upload.fail("upload overlaps data already accepted for this machine; refusing to double-count");
+                throw new Error("overlapping sync rejected. Run `claudeusage-sync` normally, or contact support if you need a history reset/backfill.");
+            }
+            if (error.code === "ingest_in_progress") {
+                upload.fail(`another upload is still being applied. retry in ${error.retryAfterSec ?? 30}s.`);
+                throw error;
+            }
+        }
+        upload.fail(error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+}
+export async function runSync(options) {
+    const base = apiBase();
+    const existingConfig = await readConfig();
+    let token = options.token ?? existingConfig?.token;
+    const config = existingConfig
+        ? { ...existingConfig, apiBase: base }
+        : token
+            ? { apiBase: base, token }
+            : null;
+    const spinner = ora("reading Claude Code session files...").start();
+    const allRecords = await readRecords();
+    spinner.succeed(`read ${allRecords.length} records from ${resolveClaudeDir()}`);
+    let filtered = allRecords;
+    if (options.since) {
+        const cutoff = parseSince(options.since);
+        filtered = allRecords.filter((record) => new Date(record.timestamp).getTime() >= cutoff);
+    }
+    else if (config) {
+        filtered = allRecords.filter((record) => afterWatermark(record, config));
+    }
+    const deduped = dedupe(filtered);
+    if (detectOutputTokenUndercount(deduped)) {
+        console.log(chalk.yellow("warning: output token undercount suspected in this data; output totals may be low."));
+    }
+    console.log(chalk.gray(`  ${deduped.length} records after dedupe`));
+    const payload = buildPayload(deduped, packageInfo.version);
+    if (options.dryRun) {
+        printDryRun(payload, deduped.length);
+        return;
+    }
+    if (payload.dailyBuckets.length === 0) {
+        console.log(chalk.yellow("no new Claude Code usage records to sync."));
+        if (config) {
+            await writeConfig(config);
+        }
+        return;
+    }
+    if (!token) {
+        token = await runDeviceFlow(base);
+    }
+    const writableConfig = config ?? { apiBase: base, token };
+    writableConfig.apiBase = base;
+    writableConfig.token = token;
+    if (!writableConfig.consentAcceptedAt) {
+        printUploadNotice(payload.dailyBuckets.length, payload.sessionCount);
+        writableConfig.consentAcceptedAt = new Date().toISOString();
+    }
+    await writeConfig(writableConfig);
+    const finalToken = await uploadWithReauth(base, token, payload);
+    const watermark = latestWatermark(deduped);
+    await writeConfig({
+        ...writableConfig,
+        ...watermark,
+        apiBase: base,
+        token: finalToken,
+    });
+    console.log(chalk.bold("\nprofile:"), chalk.hex("#d97757")(`${base}/dashboard`));
+}

package/dist/commands/unlink.js

@@ -0,0 +1,6 @@
+import chalk from "chalk";
+import { deleteConfig } from "../auth/config.js";
+export async function runUnlink() {
+    await deleteConfig();
+    console.log(chalk.gray("removed local config. run `claudeusage-sync` to re-link."));
+}

package/dist/package.js

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function readPackageInfo(metaUrl) {
+    let dir = dirname(fileURLToPath(metaUrl));
+    let packagePath = resolve(dir, "package.json");
+    for (let depth = 0; depth < 6 && !existsSync(packagePath); depth += 1) {
+        dir = resolve(dir, "..");
+        packagePath = resolve(dir, "package.json");
+    }
+    const raw = readFileSync(packagePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        version: typeof parsed.version === "string" ? parsed.version : "0.0.0",
+    };
+}

package/dist/parse/dedupe.js

@@ -0,0 +1,26 @@
+export function recordWatermarkKey(record) {
+    return `${record.messageId}:${record.requestId}`;
+}
+export function dedupe(records) {
+    const best = new Map();
+    for (const record of records) {
+        const key = recordWatermarkKey(record);
+        const previous = best.get(key);
+        if (!previous || record.outputTokens > previous.outputTokens) {
+            best.set(key, record);
+        }
+    }
+    return Array.from(best.values()).sort((a, b) => {
+        const time = a.timestamp.localeCompare(b.timestamp);
+        return time === 0
+            ? recordWatermarkKey(a).localeCompare(recordWatermarkKey(b))
+            : time;
+    });
+}
+export function detectOutputTokenUndercount(records) {
+    if (records.length === 0) {
+        return false;
+    }
+    const suspicious = records.filter((record) => record.outputTokens === 1 && record.stopReason === null).length;
+    return suspicious / records.length > 0.5;
+}

package/dist/parse/hours.js

@@ -0,0 +1,42 @@
+const IDLE_CUTOFF_MS = 10 * 60 * 1000;
+export function toLocalDateKey(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+export function groupByLocalDay(records) {
+    const byDay = new Map();
+    for (const record of records) {
+        const date = new Date(record.timestamp);
+        if (Number.isNaN(date.getTime())) {
+            continue;
+        }
+        const dateKey = toLocalDateKey(date);
+        const dayRecords = byDay.get(dateKey) ?? [];
+        dayRecords.push(record);
+        byDay.set(dateKey, dayRecords);
+    }
+    for (const dayRecords of byDay.values()) {
+        dayRecords.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    return byDay;
+}
+export function computeHoursActive(records) {
+    if (records.length < 2) {
+        return 0;
+    }
+    const sorted = records
+        .slice()
+        .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    let totalMs = 0;
+    for (let index = 1; index < sorted.length; index += 1) {
+        const current = new Date(sorted[index]?.timestamp ?? "").getTime();
+        const previous = new Date(sorted[index - 1]?.timestamp ?? "").getTime();
+        const gap = current - previous;
+        if (gap > 0 && gap < IDLE_CUTOFF_MS) {
+            totalMs += gap;
+        }
+    }
+    return Math.round((totalMs / 3_600_000) * 100) / 100;
+}

package/dist/parse/jsonl.js

@@ -0,0 +1,95 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+function isObject(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function stringField(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim()) {
+            return value;
+        }
+    }
+    return null;
+}
+function nonNegativeInt(value) {
+    const n = Number(value ?? 0);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+function validIso(value) {
+    if (!value) {
+        return null;
+    }
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+function extract(parsed) {
+    if (!isObject(parsed)) {
+        return null;
+    }
+    const message = isObject(parsed.message) ? parsed.message : {};
+    const usage = isObject(message.usage)
+        ? message.usage
+        : isObject(parsed.usage)
+            ? parsed.usage
+            : null;
+    if (!usage) {
+        return null;
+    }
+    const timestamp = validIso(stringField(parsed.timestamp, message.timestamp, parsed.created_at));
+    const model = stringField(message.model, parsed.model);
+    const messageId = stringField(message.id, parsed.messageId, parsed.message_id);
+    const requestId = stringField(parsed.requestId, parsed.request_id, message.requestId, message.request_id) ?? "";
+    const sessionId = stringField(parsed.sessionId, parsed.session_id, message.sessionId) ?? "";
+    if (!timestamp || !model || !messageId) {
+        return null;
+    }
+    return {
+        cacheCreateTokens: nonNegativeInt(usage.cache_creation_input_tokens),
+        cacheReadTokens: nonNegativeInt(usage.cache_read_input_tokens),
+        inputTokens: nonNegativeInt(usage.input_tokens),
+        messageId,
+        model,
+        outputTokens: nonNegativeInt(usage.output_tokens),
+        requestId,
+        sessionId,
+        stopReason: stringField(message.stop_reason, parsed.stop_reason),
+        timestamp,
+    };
+}
+async function* streamFile(filePath) {
+    const stream = createReadStream(filePath, { encoding: "utf8" });
+    const rl = createInterface({ crlfDelay: Infinity, input: stream });
+    for await (const line of rl) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const record = extract(JSON.parse(line));
+            if (record) {
+                yield record;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+}
+export async function* streamAllRecords(rootDir) {
+    const projects = await readdir(rootDir).catch(() => []);
+    for (const project of projects) {
+        const projectPath = join(rootDir, project);
+        const projectStat = await stat(projectPath).catch(() => null);
+        if (!projectStat?.isDirectory()) {
+            continue;
+        }
+        const files = await readdir(projectPath).catch(() => []);
+        for (const file of files) {
+            if (!file.endsWith(".jsonl")) {
+                continue;
+            }
+            yield* streamFile(resolve(projectPath, file));
+        }
+    }
+}

package/dist/parse/paths.js

@@ -0,0 +1,9 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+export function resolveClaudeDir() {
+    const override = process.env.CLAUDE_CONFIG_DIR;
+    if (override) {
+        return resolve(override, "projects");
+    }
+    return resolve(homedir(), ".claude", "projects");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudeusage-sync",
-  "version": "0.0.1",
-  "description": "Placeholder — CLI for syncing Claude Code usage stats to claudeusage.com. Full release coming soon.",
+  "version": "0.2.0",
+  "description": "Sync your Claude Code usage stats to claudeusage.com",
   "keywords": [
     "claude",
     "claude-code",
@@ -10,7 +10,44 @@
     "cli"
   ],
   "homepage": "https://claudeusage.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bazarkua/claudeusage-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bazarkua/claudeusage-sync/issues"
+  },
   "license": "MIT",
   "author": "bazarkua",
-  "private": false
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/cli.js",
+  "bin": {
+    "claudeusage-sync": "bin/cli.js"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node bin/cli.js",
+    "prepack": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "chalk": "5.6.2",
+    "commander": "14.0.3",
+    "open": "11.0.0",
+    "ora": "9.3.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "22.0.0",
+    "typescript": "5.9.3"
+  }
 }