how-much-claude 1.0.0

package/README.md

@@ -0,0 +1,22 @@
+# how-much-claude
+
+The device-pairing helper for **[How Much Claude](https://howmuchclaude.com)** — a live dashboard for your Claude usage limits across multiple accounts.
+
+## Usage
+
+In the app, click **Connect account** to get a pairing code, then run:
+
+```bash
+npx how-much-claude connect ABCD-EFGH-JKLM
+```
+
+## What it does (and doesn't)
+
+- Reads the Claude Code login token **already stored on this machine** (macOS Keychain, or `~/.claude/.credentials.json`).
+- Asks for your confirmation, then sends the token **only** to `https://howmuchclaude.com` over HTTPS to pair the device showing your code. Stored encrypted.
+- Never prints, logs, or sends the token anywhere else. No dependencies — Node built-ins only.
+- Self-hosting? Point it at your own deployment: `HMC_URL=https://your-deploy npx how-much-claude connect <code>`
+
+Source lives in the [main repo](https://github.com/SeraphKc/how-much-claude) (`bin/connect.mjs` + `lib/credential-source.mjs`); this package is synced from it at publish time.
+
+Unofficial tool — not affiliated with Anthropic.

package/connect.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// @ts-check
+// "How Much Claude" device-pairing helper (Feature B).
+//
+// Reads the Claude Code OAuth token already stored on THIS machine and sends it to the app to pair a
+// device shown a code in the browser. Uses ONLY Node built-ins (+ the dependency-free credential
+// reader shared with the web app) so `npx` starts instantly with no install.
+//
+// Usage:  node bin/connect.mjs connect <code>
+//         npx github:SeraphKc/how-much-claude connect ABCD-EFGH-JKLM
+//         HMC_URL=https://your-deploy.example connect ABCD-EFGH-JKLM   (self-hosted target)
+//
+// Flags:  -y / --yes   skip the confirmation prompt (for scripting)
+
+import process from "node:process";
+import readline from "node:readline";
+import { readLocalCredentialRaw, extractTokens, LocalCredentialError } from "./credential-source.mjs";
+
+const BASE_URL = (process.env.HMC_URL || "https://howmuchclaude.com").replace(/\/$/, "");
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(String(answer).trim());
+    });
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const yes = args.includes("-y") || args.includes("--yes");
+  const positional = args.filter((a) => a !== "-y" && a !== "--yes");
+  // Accept "connect <code>" or a bare "<code>".
+  const code = positional[0] === "connect" ? positional[1] : positional[0];
+
+  if (!code) {
+    console.error("Usage: connect <code>\n  Get the code from the \"Connect account\" dialog at " + BASE_URL + ".");
+    process.exitCode = 1;
+    return;
+  }
+
+  // Plain-English notice + consent, so nothing happens silently.
+  console.log(
+    [
+      "",
+      "How Much Claude — connect this device",
+      "",
+      "This reads the Claude Code login token already on THIS machine and sends it ONLY to",
+      `  ${BASE_URL}`,
+      "to pair this device with the code you were shown. The token is sent over HTTPS, stored",
+      "encrypted, and this helper is open source.",
+      "",
+    ].join("\n"),
+  );
+
+  if (!yes) {
+    const answer = await ask("Continue? [y/N] ");
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log("Aborted — nothing was sent.");
+      return;
+    }
+  }
+
+  // Read the local credential (macOS Keychain via execFile, else ~/.claude/.credentials.json).
+  let tokens;
+  try {
+    const raw = await readLocalCredentialRaw();
+    tokens = extractTokens(raw);
+  } catch (err) {
+    if (err instanceof LocalCredentialError) {
+      console.error(`\n✗ ${err.message}\n  ${err.recommendation}`);
+    } else {
+      console.error(`\n✗ Couldn't read the local Claude Code credential: ${err instanceof Error ? err.message : err}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // Send it. Never print the token.
+  let res;
+  try {
+    res = await fetch(`${BASE_URL}/api/connect/pair/complete`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code, token: tokens }),
+    });
+  } catch (err) {
+    console.error(`\n✗ Couldn't reach ${BASE_URL}: ${err instanceof Error ? err.message : err}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const data = await res.json().catch(() => ({}));
+  if (res.ok && data && data.ok) {
+    console.log(`\n✓ Connected ${data.email || "your account"}. You can close this window — the dashboard will update.`);
+  } else {
+    console.error(`\n✗ ${(data && data.error) || `Pairing failed (HTTP ${res.status}).`}`);
+    process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/credential-source.mjs

@@ -0,0 +1,140 @@
+// @ts-check
+// Shared, DEPENDENCY-FREE reader for the Claude Code credential stored on THIS machine.
+//
+// Deliberately plain ESM using only Node built-ins so BOTH consumers can use it with zero install:
+//   - the self-hosted local-connect route (lib/local-credentials.ts wraps this), and
+//   - the `bin/connect.mjs` CLI helper run via `npx` (which must start instantly, no `npm install`).
+//
+// It NEVER interpolates a shell string: the macOS keychain is read with execFile + a fixed argv, so
+// there is no shell-injection surface. It returns the RAW credential JSON for the caller to parse.
+
+import { execFile as _execFile } from "node:child_process";
+import { readFile as _readFile } from "node:fs/promises";
+import { homedir as _homedir } from "node:os";
+import path from "node:path";
+
+// The macOS Keychain generic-password entry Claude Code stores its OAuth credential under.
+export const KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+/** An error the UI/CLI can present, carrying an actionable next step in `recommendation`. */
+export class LocalCredentialError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} recommendation - what the user should do next (shown in the UI / printed by the CLI).
+   */
+  constructor(message, recommendation) {
+    super(message);
+    this.name = "LocalCredentialError";
+    this.recommendation = recommendation;
+  }
+}
+
+/** @typedef {{ accessToken: string, refreshToken: string | null, expiresAt: number }} ExtractedTokens */
+
+/**
+ * @typedef {object} CredentialDeps
+ * @property {NodeJS.Platform | string} [platform] - defaults to process.platform.
+ * @property {(cmd: string, args: string[]) => Promise<string>} [execFile] - returns stdout.
+ * @property {(file: string) => Promise<string>} [readFile] - returns file contents (utf8).
+ * @property {() => string} [homedir]
+ */
+
+/**
+ * Run a command with a fixed argv and NO shell. Returns stdout.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {Promise<string>}
+ */
+function defaultExecFile(cmd, args) {
+  return new Promise((resolve, reject) => {
+    // No `encoding` option → stdout is a utf8 string; no shell → args are passed literally.
+    _execFile(cmd, args, { timeout: 10_000, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+}
+
+/**
+ * Read THIS machine's Claude Code credential and return the raw JSON string.
+ *
+ * Strategy: on macOS try the Keychain first (where recent Claude Code stores it), then fall back to
+ * ~/.claude/.credentials.json (older macOS installs, and the canonical location on Linux/Windows).
+ * If nothing is found, throw a LocalCredentialError with a recommendation.
+ *
+ * @param {CredentialDeps} [deps]
+ * @returns {Promise<string>}
+ */
+export async function readLocalCredentialRaw(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const execFile = deps.execFile ?? defaultExecFile;
+  const readFile = deps.readFile ?? ((/** @type {string} */ file) => _readFile(file, "utf8"));
+  const homedir = deps.homedir ?? _homedir;
+
+  // 1) macOS Keychain (fixed argv — no shell, no interpolation).
+  if (platform === "darwin") {
+    try {
+      const out = await execFile("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"]);
+      const trimmed = out.trim();
+      if (trimmed) return trimmed;
+    } catch {
+      // No keychain entry (or `security` unavailable) — fall through to the file.
+    }
+  }
+
+  // 2) ~/.claude/.credentials.json — canonical on Linux/Windows, and the older macOS location.
+  const file = path.join(homedir(), ".claude", ".credentials.json");
+  try {
+    const content = await readFile(file);
+    const trimmed = content.trim();
+    if (trimmed) return trimmed;
+  } catch {
+    // Fall through to the appropriate error below.
+  }
+
+  // 3) Nothing found — give a clear, OS-aware reason + recommendation.
+  const supported = platform === "darwin" || platform === "linux" || platform === "win32";
+  if (!supported) {
+    throw new LocalCredentialError(
+      `Unsupported OS "${String(platform)}" — can't auto-read the Claude Code credential here.`,
+      "Add the account by pasting its token instead (the manual option below).",
+    );
+  }
+  throw new LocalCredentialError(
+    "Couldn't find a Claude Code credential on this machine.",
+    "Make sure Claude Code is installed and signed in on this machine (run `claude` and log in), then try again — or add the account by pasting its token.",
+  );
+}
+
+/**
+ * Extract just the OAuth tokens from a raw credential blob. Accepts the full
+ * `{ claudeAiOauth: {...} }` wrapper or a bare `{ accessToken, ... }` object. Missing
+ * refreshToken/expiresAt default to null/0 rather than being invented.
+ *
+ * @param {string} raw
+ * @returns {ExtractedTokens}
+ */
+export function extractTokens(raw) {
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    throw new LocalCredentialError(
+      "The Claude Code credential wasn't valid JSON.",
+      "Re-run the login for this account in Claude Code, then try again.",
+    );
+  }
+  const oauth = obj && typeof obj === "object" && obj.claudeAiOauth ? obj.claudeAiOauth : obj;
+  const accessToken = oauth && typeof oauth === "object" ? oauth.accessToken : undefined;
+  if (typeof accessToken !== "string" || !accessToken) {
+    throw new LocalCredentialError(
+      "The Claude Code credential didn't contain an access token.",
+      "Sign in to Claude Code again for this account, then try again.",
+    );
+  }
+  return {
+    accessToken,
+    refreshToken: typeof oauth.refreshToken === "string" ? oauth.refreshToken : null,
+    expiresAt: typeof oauth.expiresAt === "number" ? oauth.expiresAt : 0,
+  };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "how-much-claude",
+  "version": "1.0.0",
+  "description": "Connect this machine's Claude Code account to How Much Claude (howmuchclaude.com) — a live usage monitor for your Claude limits across multiple accounts.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "how-much-claude": "./connect.mjs"
+  },
+  "files": [
+    "connect.mjs",
+    "credential-source.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "sync": "node sync.mjs",
+    "prepublishOnly": "node sync.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SeraphKc/how-much-claude.git",
+    "directory": "cli"
+  },
+  "homepage": "https://howmuchclaude.com",
+  "bugs": "https://github.com/SeraphKc/how-much-claude/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "usage",
+    "rate-limit",
+    "monitor",
+    "anthropic"
+  ]
+}