savemytokens 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Offbeatport
+
+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,164 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/offbeatport/savemytokens/main/assets/logo.svg" alt="" width="64" height="64">
+
+# SaveMyTokens
+
+### Decide which project gets your Claude allowance.
+
+<a href="https://www.npmjs.com/package/savemytokens"><img src="https://img.shields.io/npm/v/savemytokens?style=flat-square&color=1a7f37&label=npm" alt="npm version"></a>
+<img src="https://img.shields.io/badge/dependencies-0-1a7f37?style=flat-square" alt="zero dependencies">
+<img src="https://img.shields.io/badge/node-%E2%89%A5%2018.17-2b7489?style=flat-square" alt="node 18.17+">
+<img src="https://img.shields.io/badge/local%20only-no%20network%20call-6e40c9?style=flat-square" alt="local only">
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-24292f?style=flat-square" alt="MIT"></a>
+
+<br><br>
+
+<img src="https://raw.githubusercontent.com/offbeatport/savemytokens/main/assets/screenshot.svg" alt="The SaveMyTokens control centre: three live projects sharing one 5-hour window, each row showing its allocation, how much of that allocation it has spent, its priority and its last prompt." width="880">
+
+<br>
+
+<img src="https://raw.githubusercontent.com/offbeatport/savemytokens/main/assets/statusline.svg" alt="A Claude Code status line: a braille bar, then 21%/50%, 5h 42%, in 3h52." width="520">
+
+</div>
+
+<br>
+
+## Get started
+
+```sh
+npx savemytokens
+```
+
+That is the whole install. It opens the control centre and, on the first run, offers to add four
+hooks and a status line to Claude Code's `settings.json`, backing the file up first. Prefer it
+installed once rather than fetched each time? `npm i -g savemytokens`, then the command is just
+`savemytokens`.
+
+**Say yes.** The status line is the only place Anthropic publishes your 5h and weekly usage, and it
+is what proves a session is still open, so nothing is live without it. Changed your mind?
+`npx savemytokens uninstall` takes every entry back out.
+
+<br>
+
+|  |  |
+| :-- | :-- |
+| **The real numbers** | Your 5-hour and weekly usage exactly as Anthropic publishes it. Never an invented *"% remaining"*. |
+| **Two lists you control** | **ACTIVE** is what shares your window; **RECENT** is everything else it has seen. A project joins ACTIVE on its own when you open Claude Code there and stays after you close it, so a target survives the session. `a` moves one up, `x` sends it back. |
+| **Claude working to it** | As a session eats into its slice it is told to narrow scope and finish, and to write down whatever it drops. That comes back the next time you work on the project. |
+| **Unused capacity returned** | A project with nothing running lends its share to the rest and takes it back when you return. Mark one done and what it did not spend goes to the others immediately. |
+| **In your status line** | `21%/50% · 5h 42% · in 3h52`. How much of your share you have spent, where the window is, when it comes back. Pick a shape, or arrange the pieces yourself. |
+
+<br>
+
+## Commands
+
+| | |
+| :-- | :-- |
+| `npx savemytokens` | the control centre |
+| `npx savemytokens status` | one plain-text snapshot · `--json` for a script |
+| `npx savemytokens share buydiff 40` | pin a project's allocation |
+| `npx savemytokens priority buydiff high` | who gets spare capacity first |
+| `npx savemytokens release buydiff` | hand its unused share back |
+| `npx savemytokens policy strict` | wind down earlier when it gets tight |
+| `npx savemytokens hud` | pick a status line, previewed on your numbers |
+| `npx savemytokens theme` | eighteen themes, or write your own |
+| `npx savemytokens defer` | work a session pushed to next time |
+| `npx savemytokens audit` | what your last 7 days wasted |
+| `npx savemytokens uninstall` | remove every trace · `--purge` drops the data too |
+
+Inside the control centre, `?` lists every key. The ones worth knowing: `←→` moves an allocation,
+`space` moves a project up a level and `x` moves it down, so a project you never want to see goes
+ACTIVE to RECENT to hidden. `p` cycles priority, `⏎` opens a project's sessions, `s` opens settings.
+
+## Where the numbers come from
+
+Three different kinds of number sit on that screen, and it matters which is which.
+
+| | |
+| :-- | :-- |
+| **5h and 7d** | Anthropic's own figures. Claude Code publishes them to the status line, so SaveMyTokens installs one, reads them, and stores each reading with its timestamp. Nothing is estimated. |
+| **share** | Measured from the transcripts already on your disk, token by token, including subagents. Exact, and independent of anything Anthropic reports. |
+| **used, allocation** | Anthropic's percentage, split by that measured share. The total is theirs. The division between projects is ours, and it is the only inferred number on the screen. |
+
+Usage from another machine, or from claude.ai, is invisible to a local tool. When the window moves
+while none of your projects had a turn, that is reported on its own line rather than folded silently
+into a project's figure.
+
+## How it works
+
+`install` writes three scripts to `~/.savemytokens/hooks`, adds four hook entries and a status line
+to Claude Code's `settings.json`, and backs that file up first. There is no daemon. The hooks meter
+their own session as it runs, the status line captures the published window every ten seconds, and
+the control centre reads what they leave behind. Transcripts are read incrementally, from a stored
+byte offset per file, so a prompt costs milliseconds however long the session has run.
+
+Nothing outside `~/.savemytokens` and Claude Code's own settings is touched. `uninstall` puts it
+back, and restores a status line of your own if it wrapped one.
+
+## Requirements
+
+Node 18.17 or newer, and Claude Code 2.1 or newer. The published 5h and 7d figures come with a Claude
+subscription. On an API key or through the Console, Anthropic reports no window; SaveMyTokens says so
+rather than guessing, and allocation and advice still work from measured usage alone.
+
+<details>
+<summary><b>Writing your own theme</b></summary>
+
+<br>
+
+```sh
+npx savemytokens theme new mine nord   # copy one to start from
+npx savemytokens theme check mine      # is it readable?
+npx savemytokens theme tui mine        # use it
+```
+
+`~/.savemytokens/themes/mine.json`. Everything you leave out is inherited:
+
+```json
+{
+  "colors": { "fg": "#eceff4", "dim": "#7b88a1", "accent": "#88c0d0",
+              "ok": "#a3be8c", "warn": "#ebcb8b", "danger": "#e0707c", "track": "#434c5e" },
+  "tui":    { "cursor": "❯", "pin": "★", "active": "●", "done": "✓",
+              "fill": "▰", "empty": "▱", "over": "▶", "meter": "▰", "track": "▱" },
+  "glyphs": { "sep": "·" }
+}
+```
+
+`theme check` measures every colour against the terminal and fails anything unreadable, against the same
+bar the built-in themes have to clear.
+
+</details>
+
+<details>
+<summary><b>What the hooks read and write</b></summary>
+
+<br>
+
+| | |
+| :-- | :-- |
+| **reads** | `~/.claude/projects/**/*.jsonl`, the transcripts Claude Code already writes, from a stored byte offset, and the status line payload Claude Code hands it on stdin. |
+| **writes** | `~/.savemytokens` only: meter offsets, per-project settings, quota readings, deferred notes. |
+| **injects** | A line of context on `SessionStart` and `UserPromptSubmit` when a project is over its share. Nothing else. |
+| **never** | Makes a network call, blocks a prompt, or exits non-zero. |
+
+</details>
+
+## What it will not do
+
+- **It advises; it does not enforce.** The hooks inject text, and a model does not hold a budget the
+  way a scheduler holds a lock. A session that ignores the advice keeps running. Hard caps are the
+  next step, and will ship only after a period of logging what *would* have been blocked.
+- **It does not predict a lockout.** Anthropic publishes a percentage and a reset time. Anything
+  beyond those two facts would be a guess dressed up as a number.
+- **It cannot see usage it did not measure.** Another machine, claude.ai, or work done before you
+  installed it shows up as unattributed window, labelled as such.
+- **It makes no network call.** No account, no telemetry, no daemon. `savemytokens privacy` prints
+  every file it reads and writes.
+
+<div align="center">
+<br>
+<sub>No daemon · no account · nothing leaves your machine · MIT</sub>
+<br>
+<sub>Built by <a href="https://offbeatport.com">Offbeatport</a> · questions and bugs: <a href="mailto:hello@offbeatport.com">hello@offbeatport.com</a></sub>
+</div>

package/dist/adapters/claude-code/index.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mergeSidechain } from "./merge.js";
+import { parseClaudeSession } from "./parse.js";
+const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+const DATA_DIR = path.join(CLAUDE_HOME, "projects");
+const MAX_SUBAGENT_DEPTH = 4;
+export function encodeProject(dir) {
+    return dir.replace(/[^a-zA-Z0-9]/g, "-");
+}
+function collectNested(dir, depth, out) {
+    if (depth > MAX_SUBAGENT_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            collectNested(full, depth + 1, out);
+        else if (entry.name.endsWith(".jsonl"))
+            out.push(full);
+    }
+}
+function scanProject(projectDir, projectKey, options, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const directories = new Set(entries.filter((e) => e.isDirectory()).map((e) => e.name));
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+            continue;
+        const main = path.join(projectDir, entry.name);
+        let stat;
+        try {
+            stat = fs.statSync(main);
+        }
+        catch {
+            continue;
+        }
+        if (stat.size === 0)
+            continue;
+        const sessionId = entry.name.slice(0, -".jsonl".length);
+        const extras = [];
+        if (directories.has(sessionId))
+            collectNested(path.join(projectDir, sessionId), 1, extras);
+        let size = stat.size;
+        let mtimeMs = stat.mtimeMs;
+        for (const extra of extras) {
+            try {
+                const extraStat = fs.statSync(extra);
+                size += extraStat.size;
+                if (extraStat.mtimeMs > mtimeMs)
+                    mtimeMs = extraStat.mtimeMs;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (mtimeMs < options.since)
+            continue;
+        out.push({ adapter: "claude-code", file: main, size, mtimeMs, projectKey, extraFiles: extras });
+    }
+}
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    label: "Claude Code",
+    supported: true,
+    dataDir: DATA_DIR,
+    detect() {
+        try {
+            return fs.statSync(DATA_DIR).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    discover(options) {
+        const refs = [];
+        let projects;
+        try {
+            projects = fs.readdirSync(DATA_DIR, { withFileTypes: true });
+        }
+        catch {
+            return refs;
+        }
+        const wanted = options.project ? encodeProject(options.project) : null;
+        for (const project of projects) {
+            if (!project.isDirectory())
+                continue;
+            if (wanted && project.name !== wanted)
+                continue;
+            scanProject(path.join(DATA_DIR, project.name), project.name, options, refs);
+        }
+        return refs;
+    },
+    async parse(ref) {
+        let evidence = null;
+        try {
+            evidence = await parseClaudeSession(ref.file, fs.statSync(ref.file));
+        }
+        catch {
+            return null;
+        }
+        if (!evidence)
+            return null;
+        for (const extra of ref.extraFiles ?? []) {
+            try {
+                const sub = await parseClaudeSession(extra, fs.statSync(extra));
+                if (sub)
+                    mergeSidechain(evidence, sub);
+            }
+            catch {
+                continue;
+            }
+        }
+        evidence.sourceSize = ref.size;
+        evidence.sourceMtimeMs = ref.mtimeMs;
+        return evidence;
+    },
+};

package/dist/adapters/claude-code/merge.js

@@ -0,0 +1,90 @@
+import { WEIGHTS, addUsage, estimateTokens } from "../../core/tokens.js";
+const MAX_BUCKETS = 24;
+function mergeBuckets(base, extra, keyOf, combine, weightOf) {
+    const map = new Map();
+    for (const item of [...base, ...extra]) {
+        const key = keyOf(item);
+        const existing = map.get(key);
+        map.set(key, existing ? combine(existing, item) : item);
+    }
+    return [...map.values()].sort((a, b) => weightOf(b) - weightOf(a)).slice(0, MAX_BUCKETS);
+}
+export function mergeSidechain(base, extra) {
+    addUsage(base.usage, extra.usage);
+    base.weighted += extra.weighted;
+    base.turns += extra.turns;
+    base.toolCalls += extra.toolCalls;
+    base.toolErrors += extra.toolErrors;
+    base.apiErrors += extra.apiErrors;
+    base.interruptions += extra.interruptions;
+    base.searchChars += extra.searchChars;
+    base.bloatTurns += extra.bloatTurns;
+    base.bloatTokens += extra.bloatTokens;
+    base.bloatWeighted += extra.bloatWeighted;
+    base.compactions += extra.compactions;
+    base.sidechainTurns += extra.turns;
+    base.sidechainWeighted += extra.weighted;
+    base.sourceSize += extra.sourceSize;
+    if (extra.sourceMtimeMs > base.sourceMtimeMs)
+        base.sourceMtimeMs = extra.sourceMtimeMs;
+    if (extra.peakContext > base.peakContext)
+        base.peakContext = extra.peakContext;
+    if (extra.startedAt && (!base.startedAt || extra.startedAt < base.startedAt))
+        base.startedAt = extra.startedAt;
+    if (extra.endedAt > base.endedAt)
+        base.endedAt = extra.endedAt;
+    for (const model of extra.models) {
+        const existing = base.models.find((m) => m.model === model.model);
+        if (!existing) {
+            base.models.push(model);
+            continue;
+        }
+        existing.turns += model.turns;
+        addUsage(existing.usage, model.usage);
+        existing.weighted += model.weighted;
+        existing.trivialTurns += model.trivialTurns;
+        existing.trivialWeighted += model.trivialWeighted;
+    }
+    base.reads = mergeBuckets(base.reads, extra.reads, (r) => r.path, (a, b) => {
+        const sameContent = a.signature !== "" && a.signature === b.signature;
+        const firstCopyChars = b.chars - b.redundantChars;
+        return {
+            path: a.path,
+            signature: a.signature,
+            reads: a.reads + b.reads,
+            chars: a.chars + b.chars,
+            redundantReads: a.redundantReads + b.redundantReads + (sameContent ? b.reads - b.redundantReads : 0),
+            redundantChars: a.redundantChars + b.redundantChars + (sameContent ? firstCopyChars : 0),
+            redundantWeighted: a.redundantWeighted +
+                b.redundantWeighted +
+                (sameContent ? estimateTokens(firstCopyChars) * WEIGHTS.cacheWrite : 0),
+        };
+    }, (r) => r.redundantWeighted);
+    base.outputs = mergeBuckets(base.outputs, extra.outputs, (o) => o.label, (a, b) => ({
+        label: a.label,
+        tool: a.tool,
+        calls: a.calls + b.calls,
+        chars: a.chars + b.chars,
+        maxChars: Math.max(a.maxChars, b.maxChars),
+        excessChars: a.excessChars + b.excessChars,
+        excessWeighted: a.excessWeighted + b.excessWeighted,
+    }), (o) => o.excessWeighted);
+    base.hooks = mergeBuckets(base.hooks, extra.hooks, (h) => h.name, (a, b) => ({
+        name: a.name,
+        events: a.events + b.events,
+        chars: a.chars + b.chars,
+        weighted: a.weighted + b.weighted,
+        sample: a.sample || b.sample,
+        command: a.command || b.command,
+    }), (h) => h.weighted);
+    base.writes = mergeBuckets(base.writes, extra.writes, (w) => w.path, (a, b) => ({
+        path: a.path,
+        writes: a.writes + b.writes,
+        edits: a.edits + b.edits,
+        rewrittenChars: a.rewrittenChars + b.rewrittenChars,
+        rewrittenWeighted: a.rewrittenWeighted + b.rewrittenWeighted,
+    }), (w) => w.rewrittenWeighted);
+    base.failures = mergeBuckets(base.failures, extra.failures, (f) => f.label, (a, b) => ({ label: a.label, tool: a.tool, failures: a.failures + b.failures, chars: a.chars + b.chars, weighted: a.weighted + b.weighted }), (f) => f.weighted);
+    base.attachments = mergeBuckets(base.attachments, extra.attachments, (a) => a.type, (a, b) => ({ type: a.type, events: a.events + b.events, chars: a.chars + b.chars }), (a) => a.chars);
+    return base;
+}