agent-spend-guard 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhaskar Pandey
+
+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,97 @@
+# agent-spend-guard
+
+**Token budgets + a kill-switch for AI coding agents. Know what you're burning; stop it before the invoice does.**
+
+```bash
+npx agent-spend-guard            # spend vs budgets, right now
+npx agent-spend-guard init      # drop a .spend-guard.json to set limits
+npx agent-spend-guard check     # exit 1 when over budget — wire into hooks/CI
+```
+
+Read-only. Zero dependencies. Nothing leaves your machine.
+
+---
+
+## Why
+
+2026 is the year the token bill came due: teams blowing entire annual AI budgets
+by April, "3x over budget" panic, licenses getting revoked. Dashboards tell you
+what you spent *after the fact* — nothing indie-sized actually **enforces** a
+limit. This does:
+
+- **Meter**: parses real usage — Claude Code transcripts (`~/.claude/projects`)
+  and generic JSON event files from any agent/proxy — and prices it with a
+  built-in (overridable) price table.
+- **Budget**: daily / monthly / per-project USD ceilings in `.spend-guard.json`,
+  with a warn threshold (default 80%).
+- **Kill-switch**: `check` exits 1 the moment a ceiling is crossed, so a hook or
+  CI gate can stop the agent instead of emailing you next month.
+
+## Wiring the kill-switch
+
+**Claude Code** — stop tool calls when over budget (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "npx agent-spend-guard check --cwd ." }] }
+    ]
+  }
+}
+```
+
+**CI** — fail the pipeline before it gets expensive:
+
+```bash
+npx agent-spend-guard check --strict   # exit 1 on warn too
+```
+
+## Config
+
+`.spend-guard.json` in your project (create with `init`):
+
+```json
+{
+  "budgets": {
+    "dailyUsd": 25,
+    "monthlyUsd": 300,
+    "perProjectUsd": { "my-app": 100 },
+    "warnAtPct": 0.8
+  },
+  "prices": {
+    "claude-sonnet": { "input": 3, "output": 15 }
+  }
+}
+```
+
+Prices are USD per **million** tokens, matched by longest model-id prefix;
+built-ins cover Claude / GPT / Gemini families with a conservative fallback.
+They aim to be budget-accurate, not invoice-accurate — override freely.
+
+## Commands & options
+
+| | |
+|---|---|
+| `status` (default) | spend summary + budget lines |
+| `check` | same, but exit 1 on STOP (with `--strict`, on WARN too) |
+| `init` | write a sample `.spend-guard.json` |
+| `--usage <file>` | add a `.jsonl` transcript or JSON event array (repeatable) |
+| `--no-user` | skip `~/.claude/projects` scan (hermetic/CI) |
+| `--json` | machine-readable report |
+| `--verbose` | per-project breakdown |
+
+## Sibling tools (AI dev hygiene suite)
+
+[`ai-instruct-sync`](https://www.npmjs.com/package/ai-instruct-sync) · [`ai-setup-doctor`](https://www.npmjs.com/package/ai-setup-doctor) · [`mcp-config-sync`](https://www.npmjs.com/package/mcp-config-sync) · `agent-skill-scan`
+
+## Honest limits
+
+Estimates use list prices and parsed transcripts — subscription plans, provider
+discounts, and non-transcript usage aren't visible to it. The kill-switch stops
+what's wired through it (hooks/CI); it cannot reach into a provider account.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_FILENAME, buildReport, loadConfig, sampleConfig } from "./guard.js";
+import { collectClaudeCodeUsage, parseClaudeCodeJsonl, parseGenericEvents } from "./usage.js";
+const useColor = process.stdout.isTTY && !("NO_COLOR" in process.env);
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const green = paint(32);
+const yellow = paint(33);
+const red = paint(31);
+const cyan = paint(36);
+const dim = paint(2);
+const bold = paint(1);
+function verdictLabel(v) {
+    if (v === "stop")
+        return red(bold("STOP"));
+    if (v === "warn")
+        return yellow("WARN");
+    return green("OK");
+}
+function usd(n) {
+    return `$${n.toFixed(2)}`;
+}
+function printReport(report, verbose) {
+    console.log(bold("agent-spend-guard") + dim(` — ${report.cwd}`));
+    console.log(dim(`Node ${report.node} · ${report.platform} · ${report.checkedAt} · ${report.summary.events} usage events`));
+    console.log();
+    const s = report.summary;
+    console.log(`  ${bold("Spend")} ${usd(s.totalUsd)}  ${dim(`· ${s.totalTokens.toLocaleString()} tokens across ${s.events} calls`)}`);
+    const models = Object.entries(s.byModel).sort((a, b) => b[1].usd - a[1].usd).slice(0, 5);
+    for (const [model, m] of models) {
+        console.log(dim(`    ${model}  ${usd(m.usd)} · ${m.tokens.toLocaleString()} tok · ${m.calls} calls`));
+    }
+    if (verbose) {
+        const projects = Object.entries(s.byProject).sort((a, b) => b[1].usd - a[1].usd).slice(0, 8);
+        for (const [project, p] of projects) {
+            console.log(dim(`    ${project}  ${usd(p.usd)} · ${p.calls} calls`));
+        }
+    }
+    console.log();
+    if (report.lines.length === 0) {
+        console.log(dim(`  No budgets configured — create ${CONFIG_FILENAME} (try: agent-spend-guard init)`));
+    }
+    for (const l of report.lines) {
+        const bar = l.pct >= 1 ? red : l.pct >= 0.8 ? yellow : green;
+        console.log(`  ${verdictLabel(l.verdict)} ${bold(l.scope)}  ${bar(usd(l.spentUsd))} / ${usd(l.limitUsd)} ${dim(`(${Math.round(l.pct * 100)}%)`)}`);
+    }
+    console.log();
+    if (report.verdict === "stop") {
+        console.log(red(bold("Budget exceeded — kill-switch active (exit 1). Agents should stop.")));
+    }
+    else if (report.verdict === "warn") {
+        console.log(yellow("Approaching budget — consider smaller models or a pause."));
+    }
+    else {
+        console.log(green("Within budget."));
+    }
+}
+function printHelp() {
+    console.log(`${bold("agent-spend-guard")} — token budgets + kill-switch for AI coding agents
+
+Reads real usage (Claude Code transcripts, generic event files), prices it,
+and enforces daily / monthly / per-project USD budgets. Read-only; nothing
+leaves your machine.
+
+Usage
+  agent-spend-guard [command] [options]
+
+Commands
+  status         Show spend vs budgets (default)
+  check          Same as status but built for hooks/CI: exit 1 on STOP
+  init           Write a sample ${CONFIG_FILENAME} to --cwd
+  help           Show this help
+
+Options
+  --cwd <dir>        Project directory holding ${CONFIG_FILENAME} (default: .)
+  --usage <file>     Add a usage file (repeatable): .jsonl transcript or JSON event array
+  --no-user          Skip scanning ~/.claude/projects transcripts
+  --json             Machine-readable report
+  --strict           check: exit 1 on WARN as well as STOP
+  --verbose, -v      Per-project breakdown
+
+Kill-switch wiring
+  Claude Code hook (settings.json → hooks.PreToolUse):
+    { "type": "command", "command": "npx agent-spend-guard check --cwd ." }
+  CI gate:
+    npx agent-spend-guard check --strict
+
+Config (${CONFIG_FILENAME})
+  { "budgets": { "dailyUsd": 25, "monthlyUsd": 300,
+                 "perProjectUsd": { "my-app": 100 }, "warnAtPct": 0.8 },
+    "prices": { "claude-sonnet": { "input": 3, "output": 15 } } }
+
+Exit codes
+  0 ok/warn (status) · 1 stop (check; warn too with --strict) · 2 usage error
+`);
+}
+function loadUsageFile(path) {
+    const text = readFileSync(path, "utf8");
+    if (path.endsWith(".jsonl"))
+        return parseClaudeCodeJsonl(text);
+    const generic = parseGenericEvents(text);
+    if (generic.length > 0)
+        return generic;
+    return parseClaudeCodeJsonl(text);
+}
+function main() {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            cwd: { type: "string" },
+            usage: { type: "string", multiple: true },
+            json: { type: "boolean", default: false },
+            strict: { type: "boolean", default: false },
+            verbose: { type: "boolean", default: false, short: "v" },
+            "no-user": { type: "boolean", default: false },
+            help: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    const cmd = positionals[0] ?? "status";
+    if (values.help || cmd === "help") {
+        printHelp();
+        process.exit(0);
+    }
+    const cwd = resolve(typeof values.cwd === "string" ? values.cwd : process.cwd());
+    if (cmd === "init") {
+        const path = join(cwd, CONFIG_FILENAME);
+        if (existsSync(path)) {
+            console.error(yellow(`${CONFIG_FILENAME} already exists at ${cwd} — not overwriting.`));
+            process.exit(2);
+        }
+        writeFileSync(path, JSON.stringify(sampleConfig(), null, 2) + "\n");
+        console.log(green(`Wrote ${path}`));
+        console.log(dim("Edit the budgets, then run: agent-spend-guard status"));
+        process.exit(0);
+    }
+    if (cmd !== "status" && cmd !== "check") {
+        console.error(red(`Unknown command: ${cmd}`));
+        printHelp();
+        process.exit(2);
+    }
+    const config = loadConfig(cwd);
+    const events = [];
+    const usageFiles = Array.isArray(values.usage) ? values.usage : [];
+    for (const f of usageFiles) {
+        if (typeof f !== "string")
+            continue;
+        try {
+            events.push(...loadUsageFile(resolve(f)));
+        }
+        catch {
+            console.error(red(`Cannot read usage file: ${f}`));
+            process.exit(2);
+        }
+    }
+    if (values["no-user"] !== true) {
+        events.push(...collectClaudeCodeUsage());
+    }
+    const report = buildReport(cwd, events, config);
+    if (values.json === true) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report, values.verbose === true);
+    }
+    let exit = 0;
+    if (cmd === "check") {
+        if (report.verdict === "stop")
+            exit = 1;
+        if (values.strict === true && report.verdict === "warn")
+            exit = 1;
+    }
+    process.exit(exit);
+}
+main();

package/dist/guard.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/guard.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { costOf } from "./pricing.js";
+export const CONFIG_FILENAME = ".spend-guard.json";
+export function loadConfig(cwd) {
+    const path = join(cwd, CONFIG_FILENAME);
+    if (!existsSync(path))
+        return { budgets: {} };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { budgets: raw.budgets ?? {}, prices: raw.prices };
+    }
+    catch {
+        return { budgets: {} };
+    }
+}
+export function sampleConfig() {
+    return {
+        budgets: {
+            dailyUsd: 25,
+            monthlyUsd: 300,
+            perProjectUsd: { "my-app": 100 },
+            warnAtPct: 0.8,
+        },
+    };
+}
+function dayOf(ts) {
+    return ts.slice(0, 10) || "unknown";
+}
+function monthOf(ts) {
+    return ts.slice(0, 7) || "unknown";
+}
+export function summarize(events, config) {
+    const byDay = {};
+    const byModel = {};
+    const byProject = {};
+    let totalTokens = 0;
+    let totalUsd = 0;
+    for (const e of events) {
+        const usd = costOf(e, config?.prices);
+        const tokens = e.inputTokens + e.outputTokens + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0);
+        totalTokens += tokens;
+        totalUsd += usd;
+        const day = dayOf(e.ts);
+        byDay[day] = (byDay[day] ?? 0) + usd;
+        const model = e.model || "unknown";
+        byModel[model] ??= { tokens: 0, usd: 0, calls: 0 };
+        byModel[model].tokens += tokens;
+        byModel[model].usd += usd;
+        byModel[model].calls += 1;
+        const project = e.project ?? "(unattributed)";
+        byProject[project] ??= { tokens: 0, usd: 0, calls: 0 };
+        byProject[project].tokens += tokens;
+        byProject[project].usd += usd;
+        byProject[project].calls += 1;
+    }
+    return { events: events.length, totalTokens, totalUsd, byDay, byModel, byProject };
+}
+function verdictFor(spent, limit, warnAt) {
+    if (limit <= 0)
+        return "ok";
+    if (spent >= limit)
+        return "stop";
+    if (spent >= limit * warnAt)
+        return "warn";
+    return "ok";
+}
+const VERDICT_RANK = { ok: 0, warn: 1, stop: 2 };
+/**
+ * Evaluate budgets against usage. `now` is injectable for tests.
+ * Missing budgets simply produce no lines — the guard never invents limits.
+ */
+export function evaluateBudgets(events, budgets, config, now = new Date()) {
+    const warnAt = budgets.warnAtPct ?? 0.8;
+    const lines = [];
+    const today = now.toISOString().slice(0, 10);
+    const thisMonth = now.toISOString().slice(0, 7);
+    if (budgets.dailyUsd !== undefined) {
+        const spent = events
+            .filter((e) => dayOf(e.ts) === today)
+            .reduce((s, e) => s + costOf(e, config?.prices), 0);
+        lines.push({
+            scope: `today (${today})`,
+            spentUsd: spent,
+            limitUsd: budgets.dailyUsd,
+            pct: budgets.dailyUsd > 0 ? spent / budgets.dailyUsd : 0,
+            verdict: verdictFor(spent, budgets.dailyUsd, warnAt),
+        });
+    }
+    if (budgets.monthlyUsd !== undefined) {
+        const spent = events
+            .filter((e) => monthOf(e.ts) === thisMonth)
+            .reduce((s, e) => s + costOf(e, config?.prices), 0);
+        lines.push({
+            scope: `month (${thisMonth})`,
+            spentUsd: spent,
+            limitUsd: budgets.monthlyUsd,
+            pct: budgets.monthlyUsd > 0 ? spent / budgets.monthlyUsd : 0,
+            verdict: verdictFor(spent, budgets.monthlyUsd, warnAt),
+        });
+    }
+    for (const [project, limit] of Object.entries(budgets.perProjectUsd ?? {})) {
+        const spent = events
+            .filter((e) => (e.project ?? "") === project && monthOf(e.ts) === thisMonth)
+            .reduce((s, e) => s + costOf(e, config?.prices), 0);
+        lines.push({
+            scope: `project ${project} (${thisMonth})`,
+            spentUsd: spent,
+            limitUsd: limit,
+            pct: limit > 0 ? spent / limit : 0,
+            verdict: verdictFor(spent, limit, warnAt),
+        });
+    }
+    const verdict = lines.reduce((worst, l) => (VERDICT_RANK[l.verdict] > VERDICT_RANK[worst] ? l.verdict : worst), "ok");
+    return { lines, verdict };
+}
+export function buildReport(cwd, events, config, now = new Date()) {
+    const summary = summarize(events, config);
+    const { lines, verdict } = evaluateBudgets(events, config.budgets, config, now);
+    return {
+        cwd,
+        checkedAt: now.toISOString(),
+        node: process.version,
+        platform: process.platform,
+        summary,
+        lines,
+        verdict,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+export type Verdict = "ok" | "warn" | "stop";
+export interface UsageEvent {
+  ts: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  project?: string;
+  source?: string;
+}
+export interface ModelPrice { input: number; output: number; cacheRead?: number; cacheWrite?: number; }
+export interface Budgets {
+  dailyUsd?: number;
+  monthlyUsd?: number;
+  perProjectUsd?: Record<string, number>;
+  warnAtPct?: number;
+}
+export interface GuardConfig { budgets: Budgets; prices?: Record<string, ModelPrice>; }
+export interface SpendLine { scope: string; spentUsd: number; limitUsd: number; pct: number; verdict: Verdict; }
+export interface SpendSummary {
+  events: number;
+  totalTokens: number;
+  totalUsd: number;
+  byDay: Record<string, number>;
+  byModel: Record<string, { tokens: number; usd: number; calls: number }>;
+  byProject: Record<string, { tokens: number; usd: number; calls: number }>;
+}
+export interface GuardReport {
+  cwd: string;
+  checkedAt: string;
+  node: string;
+  platform: string;
+  summary: SpendSummary;
+  lines: SpendLine[];
+  verdict: Verdict;
+}
+export declare const CONFIG_FILENAME: string;
+export declare const DEFAULT_PRICES: Record<string, ModelPrice>;
+export declare function priceFor(model: string, overrides?: Record<string, ModelPrice>): ModelPrice;
+export declare function costOf(e: UsageEvent, overrides?: Record<string, ModelPrice>): number;
+export declare function parseClaudeCodeJsonl(text: string, project?: string): UsageEvent[];
+export declare function parseGenericEvents(text: string): UsageEvent[];
+export declare function collectClaudeCodeUsage(maxFilesPerProject?: number): UsageEvent[];
+export declare function loadConfig(cwd: string): GuardConfig;
+export declare function sampleConfig(): GuardConfig;
+export declare function summarize(events: UsageEvent[], config?: GuardConfig): SpendSummary;
+export declare function evaluateBudgets(events: UsageEvent[], budgets: Budgets, config?: GuardConfig, now?: Date): { lines: SpendLine[]; verdict: Verdict };
+export declare function buildReport(cwd: string, events: UsageEvent[], config: GuardConfig, now?: Date): GuardReport;

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CONFIG_FILENAME, buildReport, evaluateBudgets, loadConfig, sampleConfig, summarize, } from "./guard.js";
+export { DEFAULT_PRICES, costOf, priceFor } from "./pricing.js";
+export { collectClaudeCodeUsage, parseClaudeCodeJsonl, parseGenericEvents, } from "./usage.js";

package/dist/pricing.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/pricing.js

@@ -0,0 +1,45 @@
+/**
+ * Approximate list prices per MILLION tokens (USD), mid-2026. Matched by
+ * longest model-id prefix; override any entry via .spend-guard.json `prices`.
+ * Budget math needs to be roughly right, not invoice-exact.
+ */
+export const DEFAULT_PRICES = {
+    "claude-opus": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    "claude-fable": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    "claude-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    "claude-haiku": { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
+    "claude-3-5": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    "gpt-4o-mini": { input: 0.15, output: 0.6 },
+    "gpt-4o": { input: 2.5, output: 10 },
+    "gpt-4.1": { input: 2, output: 8 },
+    o3: { input: 2, output: 8 },
+    "gemini-1.5-pro": { input: 1.25, output: 5 },
+    "gemini-2": { input: 1.25, output: 5 },
+    // Conservative fallback for unknown models
+    default: { input: 5, output: 25 },
+};
+export function priceFor(model, overrides) {
+    const table = { ...DEFAULT_PRICES, ...(overrides ?? {}) };
+    const m = model.toLowerCase();
+    let best = null;
+    for (const prefix of Object.keys(table)) {
+        if (prefix === "default")
+            continue;
+        if (m.startsWith(prefix.toLowerCase()) && (!best || prefix.length > best.length)) {
+            best = prefix;
+        }
+    }
+    return table[best ?? "default"] ?? table.default;
+}
+/** Cost of one usage event in USD. */
+export function costOf(e, overrides) {
+    const p = priceFor(e.model, overrides);
+    const perTokenIn = p.input / 1_000_000;
+    const perTokenOut = p.output / 1_000_000;
+    const perTokenCacheRead = (p.cacheRead ?? p.input * 0.1) / 1_000_000;
+    const perTokenCacheWrite = (p.cacheWrite ?? p.input * 1.25) / 1_000_000;
+    return (e.inputTokens * perTokenIn +
+        e.outputTokens * perTokenOut +
+        (e.cacheReadTokens ?? 0) * perTokenCacheRead +
+        (e.cacheWriteTokens ?? 0) * perTokenCacheWrite);
+}

package/dist/types.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/usage.js

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+/**
+ * Parse Claude Code transcript JSONL text into usage events. Each assistant
+ * line carries message.usage {input_tokens, output_tokens, cache_*} and
+ * message.model. Unknown/malformed lines are skipped — never throws.
+ */
+export function parseClaudeCodeJsonl(text, project) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        if (typeof obj !== "object" || obj === null)
+            continue;
+        const rec = obj;
+        const msg = rec.message;
+        if (!msg || typeof msg !== "object")
+            continue;
+        const usage = msg.usage;
+        if (!usage || typeof usage !== "object")
+            continue;
+        const inputTokens = Number(usage.input_tokens ?? 0);
+        const outputTokens = Number(usage.output_tokens ?? 0);
+        if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens))
+            continue;
+        if (inputTokens === 0 && outputTokens === 0)
+            continue;
+        out.push({
+            ts: typeof rec.timestamp === "string" ? rec.timestamp : new Date(0).toISOString(),
+            model: typeof msg.model === "string" ? msg.model : "unknown",
+            inputTokens,
+            outputTokens,
+            cacheReadTokens: Number(usage.cache_read_input_tokens ?? 0) || 0,
+            cacheWriteTokens: Number(usage.cache_creation_input_tokens ?? 0) || 0,
+            project,
+            source: "claude-code",
+        });
+    }
+    return out;
+}
+/**
+ * Parse a generic usage-events JSON file: an array of
+ * { ts, model, inputTokens, outputTokens, project?, source? }.
+ * Lets any agent/proxy feed the guard.
+ */
+export function parseGenericEvents(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(data))
+        return [];
+    const out = [];
+    for (const item of data) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const r = item;
+        const inputTokens = Number(r.inputTokens ?? r.input_tokens ?? 0);
+        const outputTokens = Number(r.outputTokens ?? r.output_tokens ?? 0);
+        if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens))
+            continue;
+        out.push({
+            ts: typeof r.ts === "string" ? r.ts : new Date(0).toISOString(),
+            model: typeof r.model === "string" ? r.model : "unknown",
+            inputTokens,
+            outputTokens,
+            cacheReadTokens: Number(r.cacheReadTokens ?? 0) || 0,
+            cacheWriteTokens: Number(r.cacheWriteTokens ?? 0) || 0,
+            project: typeof r.project === "string" ? r.project : undefined,
+            source: typeof r.source === "string" ? r.source : "generic",
+        });
+    }
+    return out;
+}
+/** Decode Claude Code's project-dir naming (-Users-x-repo → /Users/x/repo). */
+function projectNameFromDir(dir) {
+    const b = basename(dir);
+    return b.startsWith("-") ? b.slice(1).replace(/-/g, "/") : b;
+}
+/**
+ * Collect usage events from Claude Code transcripts under
+ * ~/.claude/projects/<project>/<session>.jsonl. Read-only; caps files per
+ * project to stay fast.
+ */
+export function collectClaudeCodeUsage(maxFilesPerProject = 20) {
+    const root = join(homedir(), ".claude", "projects");
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    let projects;
+    try {
+        projects = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    for (const proj of projects) {
+        const dir = join(root, proj);
+        let files;
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+            files = readdirSync(dir).filter((f) => f.endsWith(".jsonl")).slice(0, maxFilesPerProject);
+        }
+        catch {
+            continue;
+        }
+        const project = projectNameFromDir(dir);
+        for (const f of files) {
+            try {
+                const text = readFileSync(join(dir, f), "utf8");
+                out.push(...parseClaudeCodeJsonl(text, project));
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "agent-spend-guard",
+  "version": "0.1.0-alpha.1",
+  "private": false,
+  "description": "Token budgets and a kill-switch for AI coding agents — reads Claude Code/Cursor usage, prices it, and enforces daily/monthly/per-project USD limits. Read-only, zero dependencies.",
+  "type": "module",
+  "bin": {
+    "agent-spend-guard": "dist/cli.js",
+    "spend-guard": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node --test tests/litmus.test.mjs",
+    "litmus": "node --test tests/litmus.test.mjs",
+    "test:quick": "node --test tests/litmus.test.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "demo": "node dist/cli.js status --no-user"
+  },
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "finops",
+    "tokens",
+    "budget",
+    "cost",
+    "kill-switch",
+    "claude",
+    "cursor",
+    "cli"
+  ],
+  "author": "Bhaskar Pandey <bhaskarauthor@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}