savemytokens 0.2.0

package/dist/commands/hud.js

@@ -0,0 +1,71 @@
+import { HUD_LAYOUTS, builtinThemes, loadConfig, loadTheme, renderHud, saveConfig, userThemes, windowBounds, } from "../runtime/kernel.mjs";
+import { buildPlan } from "../scheduler/plan.js";
+import { bold, colorEnabled, dim, green, padEndVisible } from "../util/ansi.js";
+function sampleView(options) {
+    const control = buildPlan(Date.now(), true, options.window, options.adapter);
+    const now = control.schedule.now;
+    const bounds = windowBounds(control.schedule.quota, "five_hour", now);
+    const live = control.schedule.claimants.find((view) => view.state === "active") ?? control.schedule.claimants[0];
+    const quota = {};
+    for (const key of ["five_hour", "seven_day", "spend_limit"]) {
+        const window = control.schedule.quota?.windows?.[key];
+        if (window && (typeof window.resetsAt !== "number" || window.resetsAt * 1000 > now))
+            quota[key] = window;
+    }
+    const history = (control.schedule.quota?.history ?? [])
+        .filter((point) => typeof point.five_hour === "number" && point.at >= bounds.from)
+        .map((point) => point.five_hour);
+    return {
+        label: live?.claimant.label || "session",
+        target: live?.allocation.target ?? 1,
+        observed: live?.observed ?? 0,
+        used: live?.attributedPercent ?? null,
+        pressure: live?.pressure.value ?? 0,
+        priority: live?.claimant.priority ?? "normal",
+        quota,
+        history,
+        rate: null,
+        from: bounds.from,
+        to: bounds.to,
+        now,
+    };
+}
+export function runHud(options) {
+    const config = loadConfig();
+    const [first, second] = options.args;
+    if (first && HUD_LAYOUTS.includes(first)) {
+        config.layout.hud = first;
+        if (second)
+            config.theme.hud = second;
+        saveConfig(config);
+        process.stdout.write(`\n${green("Status line")} ${bold(first)}${second ? ` · theme ${bold(second)}` : ""}\n\n`);
+        return;
+    }
+    if (first) {
+        process.stdout.write(`\nNo layout called ${bold(first)}. Known: ${HUD_LAYOUTS.join(", ")}\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const view = sampleView(options);
+    const themeName = config.theme.hud;
+    const theme = loadTheme(themeName);
+    const out = ["", bold("Status line layouts"), dim("  what Claude Code shows you, on your own numbers"), ""];
+    for (const layout of HUD_LAYOUTS) {
+        const marker = layout === config.layout.hud ? green("→") : " ";
+        out.push(`  ${marker} ${dim(padEndVisible(layout, 11))} ${renderHud(layout, view, theme, colorEnabled)}`);
+    }
+    out.push("");
+    out.push(bold("The same layout in every theme"));
+    out.push("");
+    const themes = [...new Set([...builtinThemes(), ...userThemes()])];
+    for (const name of themes) {
+        const marker = name === themeName ? green("→") : " ";
+        out.push(`  ${marker} ${dim(padEndVisible(name, 11))} ${renderHud(config.layout.hud, view, loadTheme(name), colorEnabled)}`);
+    }
+    out.push("");
+    out.push(dim("  npx savemytokens hud blocks          set the layout"));
+    out.push(dim("  npx savemytokens hud blocks nord     layout and theme together"));
+    out.push(dim("  npx savemytokens theme hud dracula   theme only"));
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+}

package/dist/commands/install.js

@@ -0,0 +1,369 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RULES_BLOCK, RULES_END, RULES_START } from "../hooks/rules.js";
+import { HOME, HOOKS_DIR, loadConfig, saveConfig } from "../runtime/kernel.mjs";
+import { bold, dim, green, yellow } from "../util/ansi.js";
+const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+const SETTINGS = process.env.SAVEMYTOKENS_SETTINGS || path.join(CLAUDE_HOME, "settings.json");
+const MEMORY = process.env.SAVEMYTOKENS_MEMORY || path.join(CLAUDE_HOME, "CLAUDE.md");
+const RUNTIME_FILES = ["kernel.mjs", "hook.mjs", "statusline.mjs"];
+export const HOOK_EVENTS = [
+    ["SessionStart", "session-start"],
+    ["UserPromptSubmit", "prompt"],
+    ["Stop", "stop"],
+    ["SessionEnd", "session-end"],
+];
+function quoted(value) {
+    return /[\s"']/.test(value) ? `"${value}"` : value;
+}
+export function installPlan() {
+    const short = (full) => full.replace(os.homedir(), "~");
+    const rel = (name) => path.relative(os.homedir(), hookPath(name)).replace(/^\.savemytokens\//, "");
+    return [
+        {
+            file: short(SETTINGS),
+            lines: [
+                `+ statusLine        ${rel("statusline.mjs")}`,
+                ...HOOK_EVENTS.map(([event, action]) => `+ ${event.padEnd(17)} ${rel("hook.mjs")} ${action}`),
+                `copied first to ${short(path.join(HOME, "settings.backup.json"))}`,
+            ],
+        },
+        {
+            file: `${short(HOOKS_DIR)}`,
+            lines: ["+ kernel.mjs, hook.mjs, statusline.mjs"],
+        },
+    ];
+}
+export function hookPath(name) {
+    return path.join(HOOKS_DIR, name);
+}
+function hookCommand(event) {
+    return `${quoted(process.execPath)} ${quoted(hookPath("hook.mjs"))} ${event}`;
+}
+function statusLineCommand() {
+    return `${quoted(process.execPath)} ${quoted(hookPath("statusline.mjs"))}`;
+}
+function ourCommand(command) {
+    if (typeof command !== "string")
+        return false;
+    return command.includes(HOOKS_DIR) || command.includes("savemytokens") || command.includes("nudge.cjs");
+}
+function isOurs(entry) {
+    if (ourCommand(entry.command))
+        return true;
+    return Array.isArray(entry.hooks) && entry.hooks.some(isOurs);
+}
+function readSettings() {
+    let raw;
+    try {
+        raw = fs.readFileSync(SETTINGS, "utf8");
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim().length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function unreadableSettings() {
+    process.stdout.write(`\n${bold("SaveMyTokens")}\n\n${SETTINGS} is not valid JSON, so it could not be read.\nRefusing to touch it. Fix the file and try again. Nothing was changed.\n\n`);
+    process.exitCode = 1;
+}
+function writeSettings(settings) {
+    fs.mkdirSync(path.dirname(SETTINGS), { recursive: true });
+    fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + "\n");
+}
+function readMemory() {
+    try {
+        return fs.readFileSync(MEMORY, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function stripRules(text) {
+    const start = text.indexOf(RULES_START);
+    const end = text.indexOf(RULES_END);
+    if (start === -1 || end === -1)
+        return text;
+    return (text.slice(0, start) + text.slice(end + RULES_END.length)).replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+function writeRules() {
+    const body = stripRules(readMemory());
+    const next = body.length > 0 ? body + "\n\n" + RULES_BLOCK + "\n" : RULES_BLOCK + "\n";
+    fs.mkdirSync(path.dirname(MEMORY), { recursive: true });
+    fs.writeFileSync(MEMORY, next);
+}
+export function rulesInstalled() {
+    return readMemory().includes(RULES_START);
+}
+export function hookInstalled() {
+    return fs.existsSync(hookPath("hook.mjs"));
+}
+function copyRuntime() {
+    const from = fileURLToPath(new URL("../runtime/", import.meta.url));
+    fs.mkdirSync(HOOKS_DIR, { recursive: true });
+    for (const name of RUNTIME_FILES) {
+        fs.copyFileSync(path.join(from, name), path.join(HOOKS_DIR, name));
+    }
+    fs.chmodSync(path.join(HOOKS_DIR, "hook.mjs"), 0o755);
+    fs.chmodSync(path.join(HOOKS_DIR, "statusline.mjs"), 0o755);
+}
+function addHooks(settings) {
+    const hooks = (settings.hooks ??= {});
+    let added = 0;
+    for (const [event, action] of HOOK_EVENTS) {
+        const entries = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const kept = entries.filter((entry) => !isOurs(entry));
+        kept.push({ hooks: [{ type: "command", command: hookCommand(action), timeout: 10 }] });
+        hooks[event] = kept;
+        added++;
+    }
+    return added;
+}
+export function runInstall(options) {
+    const parsed = readSettings();
+    if (parsed === null) {
+        unreadableSettings();
+        return;
+    }
+    if (sandboxMismatch()) {
+        process.stdout.write(`\n${bold("SaveMyTokens")}\n\nHalf of this run is sandboxed and half is not: state is ${HOME}\nand settings are ${SETTINGS}. Refusing to touch either. Override\nSAVEMYTOKENS_HOME and SAVEMYTOKENS_SETTINGS together, or neither.\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const settings = parsed;
+    const existingStatusLine = settings.statusLine?.command;
+    const ours = ourCommand(existingStatusLine);
+    const conflict = typeof existingStatusLine === "string" && !ours;
+    const out = ["", bold("SaveMyTokens"), ""];
+    out.push("It gives every Claude Code session a target share of your Claude window, and tells");
+    out.push("Claude what share it is working within.");
+    out.push("");
+    out.push(bold("What it does to your machine"));
+    out.push("");
+    out.push(`  writes  ${HOOKS_DIR}/{kernel,hook,statusline}.mjs`);
+    out.push(`  adds    ${HOOK_EVENTS.map(([event]) => event).join(", ")} hooks to ${SETTINGS}`);
+    out.push(conflict && !options.force
+        ? `  keeps   your existing status line ${dim("(--force wraps it and appends the SMT segment)")}`
+        : conflict
+            ? `  wraps   your existing status line, then appends the SMT segment`
+            : `  sets    the status line, the only place Anthropic publishes your 5h and 7d usage`);
+    out.push(`  backs up the current settings to ${path.join(HOME, "settings.backup.json")}`);
+    if (options.rules)
+        out.push(`  adds    a fenced token-discipline block to ${MEMORY}`);
+    out.push("");
+    out.push(dim("  Hooks read your transcripts, write only to ~/.savemytokens, never block a prompt,"));
+    out.push(dim("  never make a network call, and exit 0 on every path. Remove with: npx savemytokens uninstall"));
+    out.push("");
+    if (conflict && !options.force) {
+        out.push(yellow("  Your status line is already set to something else:"));
+        out.push(dim(`    ${existingStatusLine}`));
+        out.push("  Without it SMT cannot read your published 5h/7d usage. Every other part still works.");
+        out.push(`  Run ${bold("npx savemytokens install --force")} to keep yours and append the SMT segment.`);
+        out.push("");
+    }
+    if (options.quiet && !options.dryRun) {
+        fs.mkdirSync(HOME, { recursive: true });
+        if (fs.existsSync(SETTINGS))
+            fs.copyFileSync(SETTINGS, path.join(HOME, "settings.backup.json"));
+        copyRuntime();
+        addHooks(settings);
+        const quietConfig = loadConfig();
+        if (!conflict || options.force) {
+            if (conflict && options.force)
+                quietConfig.wrappedStatusLine = existingStatusLine;
+            settings.statusLine = { type: "command", command: statusLineCommand(), padding: 0, refreshInterval: 10 };
+        }
+        if (!quietConfig.createdAt)
+            quietConfig.createdAt = Date.now();
+        saveConfig(quietConfig);
+        writeSettings(settings);
+        return;
+    }
+    if (options.dryRun) {
+        const preview = {
+            statusLine: { type: "command", command: statusLineCommand(), padding: 0, refreshInterval: 10 },
+            hooks: Object.fromEntries(HOOK_EVENTS.map(([event, action]) => [event, [{ hooks: [{ type: "command", command: hookCommand(action), timeout: 10 }] }]])),
+        };
+        out.push(bold("settings.json gains"));
+        out.push("");
+        for (const line of JSON.stringify(preview, null, 2).split("\n"))
+            out.push(`  ${line}`);
+        out.push("");
+        out.push(dim("--dry-run: nothing was written."));
+        out.push("");
+        process.stdout.write(out.join("\n") + "\n");
+        return;
+    }
+    fs.mkdirSync(HOME, { recursive: true });
+    if (fs.existsSync(SETTINGS))
+        fs.copyFileSync(SETTINGS, path.join(HOME, "settings.backup.json"));
+    copyRuntime();
+    if (options.rules)
+        writeRules();
+    addHooks(settings);
+    const config = loadConfig();
+    if (!conflict || options.force) {
+        if (conflict && options.force)
+            config.wrappedStatusLine = existingStatusLine;
+        settings.statusLine = { type: "command", command: statusLineCommand(), padding: 0, refreshInterval: 10 };
+    }
+    if (!config.createdAt)
+        config.createdAt = Date.now();
+    saveConfig(config);
+    writeSettings(settings);
+    out.push(`${green("Installed.")} It takes effect in sessions you start from now on.`);
+    out.push(dim("  Open the control centre with: npx savemytokens"));
+    out.push("");
+    if (!options.quiet)
+        process.stdout.write(out.join("\n") + "\n");
+}
+function sandboxMismatch() {
+    const homeOverridden = Boolean(process.env.SAVEMYTOKENS_HOME);
+    const settingsChosen = Boolean(process.env.SAVEMYTOKENS_SETTINGS || process.env.CLAUDE_CONFIG_DIR);
+    return homeOverridden !== settingsChosen;
+}
+function pointedAtTheRealHome() {
+    if (!process.env.SAVEMYTOKENS_HOME)
+        return false;
+    return path.resolve(HOME) === path.resolve(os.homedir(), ".savemytokens");
+}
+function refusePointingHere() {
+    process.stdout.write(`\n${bold("SaveMyTokens")}\n\nSAVEMYTOKENS_HOME is set to ${HOME}, which is the real one.\nRefusing to delete anything. Leave the variable unset to work on your own\nstate, or point it somewhere else.\n\n`);
+    process.exitCode = 1;
+}
+export function runUninstall(purge) {
+    const parsed = readSettings();
+    if (parsed === null) {
+        unreadableSettings();
+        return;
+    }
+    if (sandboxMismatch()) {
+        process.stdout.write(`\n${bold("SaveMyTokens")}\n\nHalf of this run is sandboxed and half is not: state is ${HOME}\nand settings are ${SETTINGS}. Refusing to touch either. Override\nSAVEMYTOKENS_HOME and SAVEMYTOKENS_SETTINGS together, or neither.\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (pointedAtTheRealHome()) {
+        refusePointingHere();
+        return;
+    }
+    const settings = parsed;
+    let removed = 0;
+    for (const [event] of HOOK_EVENTS) {
+        const entries = Array.isArray(settings.hooks?.[event]) ? settings.hooks[event] : [];
+        const kept = entries.filter((entry) => !isOurs(entry));
+        removed += entries.length - kept.length;
+        if (kept.length > 0)
+            settings.hooks[event] = kept;
+        else if (settings.hooks)
+            delete settings.hooks[event];
+    }
+    const config = loadConfig();
+    let statusLineRestored = false;
+    if (ourCommand(settings.statusLine?.command)) {
+        if (config.wrappedStatusLine) {
+            settings.statusLine = { type: "command", command: config.wrappedStatusLine, padding: 0 };
+            statusLineRestored = true;
+        }
+        else {
+            delete settings.statusLine;
+        }
+        removed++;
+    }
+    if (removed > 0)
+        writeSettings(settings);
+    try {
+        fs.rmSync(HOOKS_DIR, { recursive: true, force: true });
+    }
+    catch { }
+    const memory = readMemory();
+    const strippedRules = memory.includes(RULES_START);
+    if (strippedRules)
+        fs.writeFileSync(MEMORY, stripRules(memory) + "\n");
+    const defaultHome = path.resolve(HOME) === path.resolve(os.homedir(), ".savemytokens");
+    let purged = false;
+    if (purge && defaultHome && !process.stdin.isTTY) {
+        process.stdout.write(`\n${bold("SaveMyTokens")}\n\nRefusing to delete ${HOME} from a non-interactive run.\nRun it from a terminal, or delete the directory yourself.\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (purge) {
+        try {
+            fs.rmSync(HOME, { recursive: true, force: true });
+            purged = true;
+        }
+        catch { }
+    }
+    const out = ["", bold("SaveMyTokens"), ""];
+    out.push(removed > 0 || strippedRules
+        ? "Removed the hooks, the status line and the scripts. Nothing else was touched."
+        : "Nothing was installed.");
+    if (statusLineRestored)
+        out.push(dim("Your own status line is back in place."));
+    if (purged) {
+        out.push(dim(`Deleted ${HOME}.`));
+    }
+    else {
+        const kept = describeState();
+        out.push("");
+        out.push(`${dim("Kept")}  ${HOME}${kept ? dim(`  (${kept})`) : ""}`);
+        out.push(dim("      Your allocations, priorities and deferred notes live here. Measured"));
+        out.push(dim("      usage rebuilds itself from transcripts; those settings do not."));
+        out.push("");
+        out.push(`      ${dim("npx savemytokens uninstall --purge")}`);
+    }
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+}
+function describeState() {
+    try {
+        const parts = [];
+        let bytes = 0;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    walk(full);
+                else
+                    bytes += fs.statSync(full).size;
+            }
+        };
+        walk(HOME);
+        parts.push(bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`);
+        const root = path.join(HOME, "projects");
+        let projects = 0;
+        for (const adapter of fs.readdirSync(root)) {
+            projects += fs.readdirSync(path.join(root, adapter)).filter((name) => name.endsWith(".json")).length;
+        }
+        if (projects > 0)
+            parts.push(`${projects} ${projects === 1 ? "project" : "projects"}`);
+        return parts.join(" · ");
+    }
+    catch {
+        return "";
+    }
+}
+export function nudgeStats() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(HOME, "nudges.json"), "utf8"));
+        if (!Array.isArray(parsed.events) || parsed.events.length === 0)
+            return null;
+        return {
+            installedAt: parsed.installedAt ?? parsed.events[0]?.at ?? Date.now(),
+            fired: parsed.events.length,
+            usdAtStake: parsed.events.reduce((sum, event) => sum + (event.usd ?? 0), 0),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/policy.js

@@ -0,0 +1,93 @@
+import { POLICIES, deferredProjects, loadConfig, policyFor, policyNames } from "../runtime/kernel.mjs";
+import { forgetDeferred, savePreference, setPolicy } from "../scheduler/plan.js";
+import { bold, dim, green } from "../util/ansi.js";
+const PRESERVE_KINDS = ["implementation", "tests", "end-to-end checks", "documentation", "exploration"];
+function show(project) {
+    const config = loadConfig();
+    const active = policyFor(config, project);
+    const preserve = config.preserveFor[project] ?? config.preserveFor.default ?? [];
+    const out = ["", bold("When the window gets tight"), ""];
+    out.push(`  policy    ${bold(active.name)} ${dim(`· ${active.summary}`)}`);
+    out.push(`  preserve  ${preserve.length > 0 ? preserve.join(", ") : dim("testing and finalisation (default)")}`);
+    out.push("");
+    for (const name of policyNames()) {
+        const policy = POLICIES[name];
+        if (!policy)
+            continue;
+        const marker = name === active.name ? green("→") : " ";
+        const stages = policy.stages.length > 0
+            ? policy.stages.map((stage) => `${stage.at}% ${stage.actions.join("+")}`).join("   ")
+            : "nothing is ever injected";
+        out.push(`  ${marker} ${bold(name.padEnd(8))} ${dim(stages)}`);
+    }
+    out.push("");
+    out.push(dim("  focus  stay on completion, batch tool calls, stop wide reading"));
+    out.push(dim("  narrow cut scope to the smallest done version, start nothing new"));
+    out.push(dim("  defer  write what is dropped as SMT: DEFER, and get it back next session"));
+    out.push(dim("  verify finish what is open, run the tests, leave the tree clean"));
+    out.push(dim("  handoff say where it stopped, then DONE / NEEDS_MORE / BLOCKED"));
+    out.push("");
+    out.push(dim("  npx savemytokens policy strict          set it everywhere"));
+    out.push(dim("  npx savemytokens policy strict --here   set it for this project only"));
+    out.push(dim("  npx savemytokens policy preserve tests documentation"));
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+}
+export function runPolicy(options) {
+    const project = options.project ?? process.cwd();
+    const [first, ...rest] = options.args;
+    if (!first) {
+        show(project);
+        return;
+    }
+    if (first === "preserve") {
+        const kinds = rest
+            .flatMap((value) => value.split(","))
+            .map((value) => value.trim().toLowerCase())
+            .filter(Boolean)
+            .map((value) => PRESERVE_KINDS.find((kind) => kind.startsWith(value)) ?? value);
+        if (kinds.length === 0) {
+            process.stdout.write(`\nWhat should be preserved? ${dim(PRESERVE_KINDS.join(", "))}\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        savePreference(options.projectExplicit ? project : "default", kinds);
+        process.stdout.write(`\n${green("Will preserve")} ${bold(kinds.join(", "))}\n\n`);
+        return;
+    }
+    if (!setPolicy(first, options.projectExplicit ? project : null)) {
+        process.stdout.write(`\nNo policy called ${bold(first)}. Known: ${policyNames().join(", ")}\n\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const scope = options.projectExplicit ? `for ${project.split("/").pop()}` : "everywhere";
+    process.stdout.write(`\n${green("Policy")} ${bold(first)} ${dim(scope)}\n\n`);
+}
+export function runDefer(options) {
+    const project = options.project ?? process.cwd();
+    const [action] = options.args;
+    const adapter = options.adapter;
+    if (action === "clear") {
+        const groups = deferredProjects(adapter);
+        const targets = options.args[1] === "all" ? groups.map((group) => group.project) : [project];
+        for (const target of targets)
+            forgetDeferred(target, adapter);
+        process.stdout.write(`\n${green("Cleared")} deferred work for ${bold(targets.map((value) => value.split("/").pop()).join(", "))}\n\n`);
+        return;
+    }
+    const groups = deferredProjects(adapter);
+    const out = ["", bold("Deferred work"), ""];
+    if (groups.length === 0) {
+        out.push(dim("  Nothing yet. Sessions add to this when they report SMT: DEFER <one line>."));
+    }
+    for (const group of groups) {
+        out.push(`  ${bold(group.project.split("/").pop() ?? group.project)}`);
+        for (const item of group.items)
+            out.push(`    · ${item.text}`);
+        out.push("");
+    }
+    out.push(dim("  It is injected at the start of the next session in that project."));
+    out.push(dim("  npx savemytokens defer clear --here"));
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+}

package/dist/commands/privacy.js

@@ -0,0 +1,28 @@
+import { claudeCodeAdapter } from "../adapters/claude-code/index.js";
+import { displayHome } from "../storage/paths.js";
+import { bold, dim } from "../util/ansi.js";
+export function runPrivacy() {
+    const out = ["", bold("SaveMyTokens"), "", bold("What it reads"), ""];
+    out.push(`  ${claudeCodeAdapter.dataDir}${dim("  (Claude Code's own session logs, read-only)")}`);
+    out.push("");
+    out.push(bold("What it writes"));
+    out.push("");
+    out.push(`  ${displayHome()}/claimants/  ${dim("one file per session: label, target share, priority, state")}`);
+    out.push(`  ${displayHome()}/meter/      ${dim("token counts in five-minute buckets, and how far each transcript was read")}`);
+    out.push(`  ${displayHome()}/quota/      ${dim("the 5h and 7d percentages Anthropic publishes to the status line")}`);
+    out.push(`  ${displayHome()}/hooks/      ${dim("the three scripts install puts there")}`);
+    out.push(`  ${displayHome()}/cache/      ${dim("per-session audit measurements, so repeat runs are fast")}`);
+    out.push(dim("      · includes the first 120 characters of each prompt, so a finding or a row can"));
+    out.push(dim("        name the task it came from"));
+    out.push(`  ${displayHome()}/runs.json   ${dim("one line per audit run: score, waste ratios, token totals")}`);
+    out.push("");
+    out.push(dim("  Nothing outside that directory is created or modified, apart from the hook and"));
+    out.push(dim("  status line entries install adds to Claude Code's own settings.json. No project"));
+    out.push(dim("  file is touched unless you pass --rules."));
+    out.push("");
+    out.push(bold("What leaves this machine"));
+    out.push("");
+    out.push("  Nothing. There is no network call in this tool.");
+    out.push("");
+    process.stdout.write(out.join("\n") + "\n");
+}

package/dist/commands/set.js

@@ -0,0 +1,83 @@
+import { buildPlan, resolveClaimant, setParked, setPinned, setPriority, setShare, setState } from "../scheduler/plan.js";
+import { bold, dim, green, yellow } from "../util/ansi.js";
+const PRIORITIES = ["high", "normal", "low"];
+const STATES = {
+    done: "done",
+    blocked: "blocked",
+    active: "active",
+    "needs-more": "needs-more",
+};
+function fail(message) {
+    process.stdout.write(`\n${message}\n\n`);
+    process.exitCode = 1;
+}
+function percentOf(value) {
+    return `${Math.round(value * 100)}%`;
+}
+export function runSet(options) {
+    const [target, value] = options.args;
+    const command = options.command;
+    if (!target) {
+        fail(`Which project? ${dim(`try: npx savemytokens ${command} <project> ${command === "release" ? "" : "<value>"}`)}`);
+        return;
+    }
+    const control = buildPlan(Date.now(), true, options.window, options.adapter);
+    const found = resolveClaimant(control.schedule, target);
+    if (!found) {
+        const known = control.schedule.projects.map((view) => view.label).filter(Boolean);
+        fail(`No project matching ${bold(target)}. ${known.length > 0 ? dim(`Known: ${[...new Set(known)].join(", ")}`) : ""}`);
+        return;
+    }
+    const { view, matches } = found;
+    const note = matches > 1 ? dim(`  (${matches} matched, took the busiest)`) : "";
+    if (command === "share") {
+        if (!value) {
+            fail(`What share? ${dim("try: npx savemytokens share webinvoke 50, or `auto` to unpin it")}`);
+            return;
+        }
+        if (value === "auto" || value === "even") {
+            setShare(view.project, null, control.provider.id);
+            process.stdout.write(`\n${green("Unpinned")} ${bold(view.label)}, it takes an even split again${note}\n\n`);
+            return;
+        }
+        const percent = Number(String(value).replace("%", ""));
+        if (!Number.isFinite(percent) || percent < 0 || percent > 100) {
+            fail(`${bold(String(value))} is not a percentage between 0 and 100.`);
+            return;
+        }
+        setShare(view.project, percent / 100, control.provider.id);
+        const after = buildPlan(Date.now(), false, options.window, options.adapter);
+        const updated = after.schedule.projects.find((row) => row.project === view.project);
+        const actual = updated ? percentOf(updated.allocation.target) : `${Math.round(percent)}%`;
+        const clamped = updated && Math.abs(updated.allocation.target * 100 - percent) > 0.5;
+        process.stdout.write(`\n${green("Set")} ${bold(view.label)} target to ${bold(actual)}${note}\n${clamped ? yellow(`  asked for ${Math.round(percent)}%, but the window is already committed elsewhere\n`) : ""}\n`);
+        return;
+    }
+    if (command === "pin" || command === "park") {
+        const on = String(value ?? "on").toLowerCase() !== "off";
+        if (command === "pin")
+            setPinned(view.project, on, control.provider.id);
+        else
+            setParked(view.project, on, control.provider.id);
+        process.stdout.write(`\n${green(on ? (command === "pin" ? "Pinned" : "Parked") : "Cleared")} ${bold(view.label)}${note}\n${dim(command === "pin" ? "  it stays visible even when it goes quiet" : "  it drops out of the working set until you resume it")}\n\n`);
+        return;
+    }
+    if (command === "priority") {
+        const priority = String(value ?? "").toLowerCase();
+        if (!PRIORITIES.includes(priority)) {
+            fail(`Priority is one of ${PRIORITIES.join(", ")}.`);
+            return;
+        }
+        setPriority(view.project, priority, control.provider.id);
+        process.stdout.write(`\n${green("Set")} ${bold(view.label)} to ${bold(priority.toUpperCase())}${note}\n\n`);
+        return;
+    }
+    const state = STATES[String(value ?? "done").toLowerCase()];
+    if (!state) {
+        fail(`State is one of ${Object.keys(STATES).join(", ")}.`);
+        return;
+    }
+    setState(view.project, state, control.provider.id);
+    const released = state === "done" || state === "blocked";
+    process.stdout.write(`\n${green("Marked")} ${bold(view.label)} ${bold(state)}${note}\n${released ? dim("  its unused share goes back to the pool\n") : ""}\n`);
+}