savemytokens 0.2.0

package/dist/commands/theme.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+import { HUD_LAYOUTS, THEME_DIR, builtinThemes, loadConfig, loadTheme, saveConfig, userThemes, writeJson, } from "../runtime/kernel.mjs";
+import { bold, dim, green, red } from "../util/ansi.js";
+const LAYOUTS = HUD_LAYOUTS;
+function scaffold(name, from) {
+    if (!name) {
+        process.stdout.write(`\nName it: ${bold("npx savemytokens theme new midnight")}\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const file = path.join(THEME_DIR, `${name}.json`);
+    if (fs.existsSync(file)) {
+        process.stdout.write(`\n${file} already exists.\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const base = loadTheme(from);
+    writeJson(file, { ...base, name });
+    fs.writeFileSync(file, JSON.stringify({ ...base, name }, null, 2) + "\n");
+    process.stdout.write(`\n${green("Wrote")} ${file}\n${dim(`  edit it, then: npx savemytokens theme check ${name} && npx savemytokens theme tui ${name}`)}\n\n`);
+}
+const TEXT_ROLES = ["fg", "accent", "ok", "warn", "danger"];
+const REQUIRED_TUI = ["cursor", "pin", "active", "done", "blocked", "idle", "fill", "empty", "over", "meter", "track"];
+function channel(value) {
+    const v = value / 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+function luminance(hex) {
+    if (!/^#[0-9a-f]{6}$/i.test(hex))
+        return null;
+    const n = Number.parseInt(hex.slice(1), 16);
+    return 0.2126 * channel((n >> 16) & 255) + 0.7152 * channel((n >> 8) & 255) + 0.0722 * channel(n & 255);
+}
+function contrast(hex, background) {
+    const first = luminance(hex);
+    const second = luminance(background);
+    if (first === null || second === null)
+        return null;
+    return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+}
+function check(name, background) {
+    const known = new Set([...builtinThemes(), ...userThemes()]);
+    if (!known.has(name)) {
+        process.stdout.write(`\nNo theme called ${bold(name)}. Known: ${[...known].join(", ")}\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const theme = loadTheme(name);
+    const out = ["", bold(`theme ${name}`), dim(`  measured against ${background}`), ""];
+    let problems = 0;
+    for (const [role, value] of Object.entries(theme.colors)) {
+        const ratio = contrast(String(value), background);
+        if (ratio === null) {
+            out.push(`  ${red("✗")} ${role.padEnd(8)} ${value} ${dim("is not a #rrggbb colour")}`);
+            problems++;
+            continue;
+        }
+        const floor = TEXT_ROLES.includes(role) ? 4.5 : role === "dim" ? 2.5 : 1.15;
+        const ceiling = role === "track" ? 4 : Infinity;
+        const ok = ratio >= floor && ratio <= ceiling;
+        if (!ok)
+            problems++;
+        out.push(`  ${ok ? green("✓") : red("✗")} ${role.padEnd(8)} ${String(value).padEnd(9)} ${ratio.toFixed(1)}:1 ${dim(ok ? "" : ratio < floor ? `wants at least ${floor}:1` : `wants at most ${ceiling}:1`)}`);
+    }
+    const missing = REQUIRED_TUI.filter((key) => !(theme.tui ?? {})[key]);
+    if (missing.length > 0) {
+        out.push("");
+        out.push(`  ${dim(`inherits ${missing.join(", ")} from the default theme`)}`);
+    }
+    out.push("");
+    out.push(problems === 0 ? green("  Readable everywhere.") : red(`  ${problems} ${problems === 1 ? "problem" : "problems"} to fix.`));
+    out.push(dim("  --light checks against a white terminal instead"));
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+    if (problems > 0)
+        process.exitCode = 1;
+}
+export function runTheme(args) {
+    const config = loadConfig();
+    const surface = args[0];
+    const value = args[1];
+    if (surface === "new") {
+        scaffold(String(value ?? ""), String(args[2] ?? config.theme.tui));
+        return;
+    }
+    if (surface === "check") {
+        const light = args.includes("--light");
+        check(String(value ?? config.theme.tui), light ? "#ffffff" : "#1e1e1e");
+        return;
+    }
+    const target = surface === "tui" || surface === "hud" ? surface : null;
+    if (surface && !target) {
+        process.stderr.write(`\nNo theme surface called ${surface}. Use: theme tui <name>, theme hud <name>, theme check, theme new\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!surface) {
+        const out = ["", bold("SaveMyTokens themes"), ""];
+        out.push(`  tui   ${config.theme.tui}`);
+        out.push(`  hud   ${config.theme.hud} ${dim(`· layout ${config.layout.hud}`)}`);
+        out.push("");
+        out.push(dim(`  built in: ${builtinThemes().join(", ")}`));
+        const custom = userThemes().filter((name) => !builtinThemes().includes(name));
+        if (custom.length > 0)
+            out.push(dim(`  yours: ${custom.join(", ")}`));
+        out.push(dim(`  hud layouts: ${LAYOUTS.join(", ")}`));
+        out.push("");
+        out.push(dim("  npx savemytokens theme tui nord           use it in the control centre"));
+        out.push(dim("  npx savemytokens theme new mine nord      copy one to start from"));
+        out.push(dim("  npx savemytokens theme check mine         is it readable?"));
+        out.push(dim("  they live in ~/.savemytokens/themes/<name>.json"));
+        out.push("");
+        process.stdout.write(out.join("\n") + "\n");
+        return;
+    }
+    if (!value) {
+        process.stdout.write(`\n  ${target} theme is ${config.theme[target ?? "tui"]}\n\n`);
+        return;
+    }
+    if (target === "hud" && LAYOUTS.includes(value)) {
+        config.layout.hud = value;
+        saveConfig(config);
+        process.stdout.write(`\n${green("Set")} hud layout to ${bold(value)}\n\n`);
+        return;
+    }
+    const known = new Set([...builtinThemes(), ...userThemes()]);
+    if (!known.has(value)) {
+        process.stdout.write(`\nNo theme called ${bold(value)}. Known: ${[...known].join(", ")}\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    config.theme[target ?? "tui"] = value;
+    saveConfig(config);
+    process.stdout.write(`\n${green("Set")} ${target} theme to ${bold(value)}\n\n`);
+}

package/dist/commands/watch.js

@@ -0,0 +1,135 @@
+import { activeAdapters } from "../adapters/index.js";
+import { analyze } from "../analyze/index.js";
+import { collect } from "../collect.js";
+import { buildPlan } from "../scheduler/plan.js";
+import { saveRun } from "../storage/store.js";
+import { bold, dim, green, red, yellow } from "../util/ansi.js";
+import { percent, plural } from "../util/fmt.js";
+import { defaultProject } from "./audit.js";
+const SCORE_STEP = 2;
+const QUOTA_STEP = 5;
+function stageOf(pressure) {
+    if (pressure >= 1)
+        return 100;
+    if (pressure >= 0.9)
+        return 90;
+    if (pressure >= 0.8)
+        return 80;
+    return 0;
+}
+function scheduleSnapshot(options) {
+    const control = buildPlan(Date.now(), true, options.window, options.adapter);
+    const snapshot = {
+        states: new Map(),
+        stages: new Map(),
+        labels: new Map(),
+        used: control.schedule.live ? control.schedule.live.usedPercent : null,
+    };
+    for (const view of control.schedule.claimants) {
+        snapshot.states.set(view.claimant.id, view.state);
+        snapshot.stages.set(view.claimant.id, stageOf(view.pressure.value));
+        snapshot.labels.set(view.claimant.id, view.claimant.label || view.claimant.id.slice(0, 8));
+    }
+    return { snapshot };
+}
+function driftEvents(previous, next) {
+    const events = [];
+    for (const [id, state] of next.states) {
+        const label = next.labels.get(id) ?? id.slice(0, 8);
+        const before = previous.states.get(id);
+        if (before === undefined) {
+            events.push(`${bold(label)} joined the window`);
+            continue;
+        }
+        if (before !== state && (state === "done" || state === "blocked")) {
+            events.push(`${bold(label)} ${state} ${dim("· its unused share is back in the pool")}`);
+        }
+        const stage = next.stages.get(id) ?? 0;
+        if (stage > (previous.stages.get(id) ?? 0)) {
+            const text = stage >= 100 ? "is over its target share" : `passed ${stage}% of its target share`;
+            events.push(`${stage >= 100 ? red(label) : yellow(label)} ${text}`);
+        }
+    }
+    if (previous.used !== null && next.used !== null && next.used - previous.used >= QUOTA_STEP) {
+        events.push(dim(`window ${Math.round(previous.used)}% → ${Math.round(next.used)}% used`));
+    }
+    return events;
+}
+function clock() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+function line(text) {
+    process.stdout.write(`${dim(clock())} ${text}\n`);
+}
+export async function runWatch(options) {
+    if (activeAdapters().length === 0) {
+        process.stdout.write(`\nSaveMyTokens\n\nNo Claude Code data found at ~/.claude/projects.\n\n`);
+        return;
+    }
+    process.stdout.write(`\n${bold("SaveMyTokens")} ${dim("watch")}\n\n`);
+    process.stdout.write(dim("Observing only. Nothing is modified, redirected, or uploaded.\n"));
+    process.stdout.write(dim("Reports allocation drift as well as new waste.\n"));
+    process.stdout.write(dim(`Window: last ${options.days} days${options.project ? " · this project" : ""} · checking every ${options.interval}s · Ctrl-C to stop\n\n`));
+    let baseline = null;
+    let stopping = false;
+    let schedule = null;
+    const tick = async () => {
+        const { snapshot } = scheduleSnapshot(options);
+        if (schedule)
+            for (const event of driftEvents(schedule, snapshot))
+                line(event);
+        schedule = snapshot;
+        const corpus = await collect({ days: options.days, project: defaultProject(options) });
+        const audit = analyze(corpus);
+        if (!baseline) {
+            baseline = audit;
+            const top = audit.findings[0];
+            line(`baseline ${bold(`${audit.score}/100`)} ${dim(`· ${audit.totals.sessions} ${plural(audit.totals.sessions, "session")} · ${audit.totals.turns} turns`)}${top ? dim(` · top: ${top.title.toLowerCase()}`) : ""}`);
+            if (options.save)
+                saveRun(audit);
+            return;
+        }
+        const previous = baseline;
+        const delta = audit.score - previous.score;
+        const newTurns = audit.totals.turns - previous.totals.turns;
+        const knownIds = new Set(previous.findings.map((f) => f.id));
+        const fresh = audit.findings.filter((f) => !knownIds.has(f.id) && f.wasteRatio >= 0.02);
+        for (const finding of fresh) {
+            line(`${yellow("new waste")} ${finding.title.toLowerCase()} ${dim(`· ${percent(finding.wasteRatio, 1)} of spend`)}`);
+            line(dim(`          fix: ${finding.fix}`));
+        }
+        if (Math.abs(delta) >= SCORE_STEP) {
+            const marker = delta > 0 ? green(`+${delta}`) : red(String(delta));
+            line(`efficiency ${bold(`${audit.score}/100`)} ${marker} ${dim(`· ${newTurns} new turns`)}`);
+        }
+        if (fresh.length > 0 || Math.abs(delta) >= SCORE_STEP) {
+            baseline = audit;
+            if (options.save)
+                saveRun(audit);
+        }
+    };
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        const audit = baseline;
+        process.stdout.write(`\n${dim("stopped")} ${audit ? `· efficiency ${audit.score}/100 · run ${bold("npx savemytokens")} for the full audit` : ""}\n\n`);
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await tick();
+    for (;;) {
+        await new Promise((resolve) => setTimeout(resolve, options.interval * 1000));
+        if (stopping)
+            return;
+        try {
+            await tick();
+        }
+        catch (error) {
+            line(red(`scan failed: ${error.message}`));
+        }
+    }
+}

package/dist/core/cost.js

@@ -0,0 +1,24 @@
+import { WEIGHTS } from "./tokens.js";
+export class LifetimeCost {
+    tokens = 0;
+    segments = new Map();
+    add(segment, turn, tokens) {
+        this.tokens += tokens;
+        let s = this.segments.get(segment);
+        if (!s) {
+            s = { tokens: 0, tokenTurns: 0 };
+            this.segments.set(segment, s);
+        }
+        s.tokens += tokens;
+        s.tokenTurns += tokens * turn;
+    }
+    resolve(segmentEnds) {
+        let total = 0;
+        for (const [segment, s] of this.segments) {
+            const end = segmentEnds[segment] ?? 0;
+            const residentTurns = Math.max(0, end * s.tokens - s.tokenTurns);
+            total += WEIGHTS.cacheWrite * s.tokens + WEIGHTS.cacheRead * residentTurns;
+        }
+        return total;
+    }
+}

package/dist/core/pricing.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const PRICE_SOURCES = [
+    { label: "Anthropic", asOf: "2026-06-24", url: "https://docs.claude.com/en/docs/about-claude/pricing" },
+    { label: "OpenAI", asOf: "2026-08-31", url: "https://developers.openai.com/api/docs/pricing" },
+];
+const TABLE = [
+    [/fable|mythos/i, { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 }],
+    [/opus/i, { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 }],
+    [/sonnet-4-6/i, { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 }],
+    [/sonnet/i, { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 }],
+    [/haiku/i, { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 }],
+    [/gpt-5\.5-pro/i, { input: 30, output: 180, cacheRead: 3, cacheWrite: 30 }],
+    [/gpt-5\.6-luna/i, { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.2 }],
+    [/gpt-5\.6-terra/i, { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2 }],
+    [/gpt-5\.6/i, { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 5 }],
+    [/gpt-5\.5/i, { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 5 }],
+    [/gpt-5\.4/i, { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 2.5 }],
+    [/gpt-5/i, { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 5 }],
+];
+const FALLBACK = { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 };
+let overrides = null;
+function loadOverrides() {
+    if (overrides)
+        return overrides;
+    overrides = {};
+    const home = process.env.SAVEMYTOKENS_HOME || path.join(os.homedir(), ".savemytokens");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(home, "pricing.json"), "utf8"));
+        if (parsed && typeof parsed === "object")
+            overrides = parsed;
+    }
+    catch {
+        overrides = {};
+    }
+    return overrides;
+}
+export function rateFor(model) {
+    const override = loadOverrides()[model];
+    if (override)
+        return override;
+    for (const [pattern, rate] of TABLE)
+        if (pattern.test(model))
+            return rate;
+    return FALLBACK;
+}
+export function isKnownModel(model) {
+    if (loadOverrides()[model])
+        return true;
+    return TABLE.some(([pattern]) => pattern.test(model));
+}
+export function usd(model, usage) {
+    const rate = rateFor(model);
+    return ((usage.input * rate.input +
+        usage.cacheWrite * rate.cacheWrite +
+        usage.cacheRead * rate.cacheRead +
+        usage.output * rate.output) /
+        1_000_000);
+}
+export function pricingNote() {
+    return `Prices: ${PRICE_SOURCES.map((s) => `${s.label} list ${s.asOf}`).join(", ")}. Override in ~/.savemytokens/pricing.json`;
+}

package/dist/core/resource.js

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

package/dist/core/tokens.js

@@ -0,0 +1,32 @@
+export const WEIGHTS = {
+    input: 1,
+    cacheWrite: 1.25,
+    cacheRead: 0.1,
+    output: 5,
+};
+export const CHARS_PER_TOKEN = 4;
+export function emptyUsage() {
+    return { input: 0, output: 0, cacheWrite: 0, cacheRead: 0 };
+}
+export function addUsage(target, add) {
+    target.input += add.input;
+    target.output += add.output;
+    target.cacheWrite += add.cacheWrite;
+    target.cacheRead += add.cacheRead;
+    return target;
+}
+export function rawTokens(u) {
+    return u.input + u.output + u.cacheWrite + u.cacheRead;
+}
+export function weigh(u) {
+    return (u.input * WEIGHTS.input +
+        u.cacheWrite * WEIGHTS.cacheWrite +
+        u.cacheRead * WEIGHTS.cacheRead +
+        u.output * WEIGHTS.output);
+}
+export function estimateTokens(chars) {
+    return Math.round(chars / CHARS_PER_TOKEN);
+}
+export function contextLifetimeCost(tokens, turnsAfter) {
+    return tokens * (WEIGHTS.cacheWrite + WEIGHTS.cacheRead * Math.max(0, turnsAfter));
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export const EVIDENCE_SCHEMA = 4;

package/dist/hooks/nudge.js

@@ -0,0 +1,111 @@
+export const HOOK_FILENAME = "nudge.cjs";
+export const NUDGE_CONTEXT_TOKENS = 150_000;
+export const NUDGE_COOLDOWN_MS = 30 * 60 * 1000;
+export const NUDGE_HORIZON_TURNS = 10;
+export const HOOK_SCRIPT = String.raw `#!/usr/bin/env node
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const HOME = process.env.SAVEMYTOKENS_HOME || path.join(os.homedir(), ".savemytokens");
+const STATE = path.join(HOME, "nudges.json");
+const THRESHOLD = 150000;
+const COOLDOWN_MS = 30 * 60 * 1000;
+const TAIL_BYTES = 262144;
+const RATE_PER_TOKEN = 5 / 1000000;
+const CACHE_READ = 0.1;
+const HORIZON_TURNS = 10;
+const ANAPHORIC =
+  /^\s*(ok|okay|now|also|and|then|next|again|yes|no|nope|yep|same|do the same|the other|these|those|them|it|that|this|continue|carry on|keep going|go on|more|another|fix (it|that|this)|try again|redo|revert|undo|hmm|wait|great|nice|thanks|perfect|good)\b/i;
+
+function selfContained(prompt) {
+  const text = String(prompt || "").trim();
+  return text.length >= 40 && !ANAPHORIC.test(text);
+}
+
+function tailLines(file) {
+  const fd = fs.openSync(file, "r");
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    fs.readSync(fd, buffer, 0, buffer.length, start);
+    return buffer.toString("utf8").split("\n");
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function currentContext(file) {
+  const lines = tailLines(file);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || line.indexOf('"usage"') === -1) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const usage = record && record.message && record.message.usage;
+    if (!usage) continue;
+    const total =
+      (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+    if (total > 0) return total;
+  }
+  return 0;
+}
+
+function readState() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(STATE, "utf8"));
+    if (parsed && Array.isArray(parsed.events)) return parsed;
+  } catch {}
+  return { installedAt: Date.now(), events: [] };
+}
+
+function writeState(state) {
+  try {
+    fs.mkdirSync(HOME, { recursive: true });
+    state.events = state.events.slice(-500);
+    fs.writeFileSync(STATE, JSON.stringify(state));
+  } catch {}
+}
+
+function run() {
+  const raw = fs.readFileSync(0, "utf8");
+  if (!raw) return;
+  const input = JSON.parse(raw);
+  if (!input || !input.transcript_path || !selfContained(input.prompt)) return;
+  if (!fs.existsSync(input.transcript_path)) return;
+
+  const context = currentContext(input.transcript_path);
+  if (context < THRESHOLD) return;
+
+  const state = readState();
+  const now = Date.now();
+  const recent = state.events.filter((event) => event.session === input.session_id).pop();
+  if (recent && now - recent.at < COOLDOWN_MS) return;
+
+  const horizon = context * CACHE_READ * RATE_PER_TOKEN * HORIZON_TURNS;
+  const thousands = Math.round(context / 1000);
+
+  state.events.push({ at: now, session: input.session_id, context: context, usd: horizon });
+  writeState(state);
+
+  process.stdout.write(
+    "[savemytokens] This reads as a new task and " +
+      thousands +
+      "k tokens of earlier work are still in context, about $" +
+      horizon.toFixed(2) +
+      " per " +
+      HORIZON_TURNS +
+      " turns from here. Open your reply with one short line saying so, and that /clear or a fresh session drops it. Then do what was asked.\n",
+  );
+}
+
+try {
+  run();
+} catch {}
+process.exit(0);
+`;

package/dist/hooks/rules.js

@@ -0,0 +1,14 @@
+export const RULES_START = "<!-- savemytokens:start -->";
+export const RULES_END = "<!-- savemytokens:end -->";
+export const RULES_BLOCK = `${RULES_START}
+## Token discipline
+
+- Batch shell work. Chain related commands into one call instead of one call per step; every extra
+  round trip re-reads the whole conversation.
+- Never dump a large result into context. Pipe long output through \`tail\`/\`grep\`, or write it to a
+  file and read back only the part that matters.
+- Delegate multi-step searching, log reading and file discovery to a subagent, and ask it for its
+  conclusion rather than its transcript.
+- Once a file exists, edit it. Do not rewrite a whole file to change part of it.
+- Do not re-read a file you have already read in this session unless it changed.
+${RULES_END}`;

package/dist/privacy/payload.js

@@ -0,0 +1,22 @@
+export function buildPayload(audit, version, outcomes) {
+    const round = (value) => Math.round(value * 1000) / 1000;
+    return {
+        schema: 1,
+        tool: `savemytokens@${version}`,
+        agent: audit.scope.adapters.join(","),
+        window_days: audit.scope.days,
+        sessions: audit.totals.sessions,
+        tasks: audit.totals.tasks,
+        turns: audit.totals.turns,
+        tokens: {
+            input: audit.totals.usage.input,
+            output: audit.totals.usage.output,
+            cache_write: audit.totals.usage.cacheWrite,
+            cache_read: audit.totals.usage.cacheRead,
+        },
+        efficiency_score: audit.score,
+        waste_ratio: round(audit.wasteRatio),
+        findings: audit.findings.map((f) => ({ id: f.id, waste_ratio: round(f.wasteRatio), confidence: f.confidence })),
+        outcomes,
+    };
+}