@ycstudios/token-tab 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yiftach Cohen
+
+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,215 @@
+# Token Tab
+
+<p align="center">
+  <img src="app/Branding/gauge-appicon.png" alt="Token Tab" width="116" height="116"><br>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="app/Branding/gauge-wordmark-dark.png">
+    <img src="app/Branding/gauge-wordmark.png" alt="Token Tab" width="172">
+  </picture>
+</p>
+
+[![CI](https://github.com/YiftachCohen/token-tab/actions/workflows/ci.yml/badge.svg)](https://github.com/YiftachCohen/token-tab/actions/workflows/ci.yml)
+
+Token Tab shows your Claude Code token usage in the macOS menu bar. It reads the logs
+Claude Code already writes to `~/.claude` — no API keys, no keychain, no network calls.
+It reads token counts off disk and shows them; nothing leaves your machine.
+
+Click the menu bar item for your current 5-hour usage window (with an exact reset
+countdown) and a local cost estimate.
+
+## What it reads
+
+- `~/.claude/projects/**/*.jsonl` — the transcripts Claude Code already writes.
+- Tokens per model, per surface (subscription / Bedrock), per window (today / this week / last 5h).
+- A dollar **estimate** from a bundled per-model rate table — local arithmetic, not an invoice (see [Cost](#cost)).
+
+Works the same whether Claude Code talks to the Anthropic API, a Max/Pro subscription,
+or AWS Bedrock: the token counts are in the local logs either way, so no AWS
+credentials are needed to read them.
+
+## Trust model
+
+The point of Token Tab is that it has no way to leak anything. Each claim is verifiable:
+
+- **No network.** No network code, no dependencies.
+- **No content.** The parser decodes only the metadata it needs — `type`, `model`,
+  `message.id`, `requestId`, `usage`, `timestamp`, `isSidechain`. It never touches
+  `message.content` (your prompts, code, and responses).
+- **No state.** No cache, no telemetry, nothing written.
+
+What it can't claim is to be *blind* to your data. Any usage meter has to read the
+logs, and those logs contain your prompts. The narrower guarantee holds: it reads the
+numbers, sends nothing, stores nothing.
+
+### Audit it yourself
+
+It's one dependency-free script. These greps over `src/` all print nothing:
+
+```sh
+grep -RnE "fetch|http|https|net\.|URLSession|Socket|dns" src/   # no network
+grep -RnE "child_process|spawn|execFile" src/                   # no subprocess
+grep -RnE "\.content" src/ | grep -v "//"                       # never reads content
+cat package.json | grep -A1 dependencies                        # -> {}
+```
+
+The parser is `recordFromLine` in `src/core.mjs` — it returns `message.id`, `model`,
+`usage`, `timestamp`, `isSidechain`, never content. The one subprocess in the repo is
+the opt-in live reader, fenced outside `src/` in `adapters/` (see
+[Live server %](#live-server--opt-in)). The native app's own audit — sandbox
+entitlements, no-network greps over `app/Sources` — is in
+[`app/README.md`](app/README.md#the-two-minute-audit-native-build).
+
+## What runs where
+
+One job — read the logs, aggregate, show usage — as two engines (a JS core and a Swift
+port kept in parity) behind three front-ends. Only the opt-in live path touches the
+network:
+
+| Piece | What it is | Network? |
+|---|---|---|
+| `src/` JS engine | parse + dedup + aggregate | no |
+| **CLI** | `node src/token-tab.mjs` → a terminal report | no |
+| **SwiftBar** | shell wrappers run the JS engine on a timer | no¹ |
+| **Native app** | `app/Token Tab.app`, the menu-bar UI (App-Sandboxed, no network entitlement) | no — kernel-enforced |
+| **Live sidecar** | `adapters/write-live.mjs` runs `claude /usage`, writes a cache file | yes — via `claude` |
+
+¹ only the `…-live.2m.sh` variant calls `claude`; the default `…30s.sh` does not.
+
+## Quick start
+
+### CLI
+```sh
+node src/token-tab.mjs            # human report
+node src/token-tab.mjs --json     # machine-readable
+node src/token-tab.mjs --swiftbar # SwiftBar format
+```
+
+### Menu bar — SwiftBar
+One symlink and you have `◧ <tokens>` in the menu bar in about a minute. See
+[`swiftbar/README.md`](swiftbar/README.md). SwiftBar may need Full Disk Access to read
+`~/.claude` — broader than the native app's scoped grant; it's the fast on-ramp.
+
+### Menu bar — native app
+A SwiftUI `MenuBarExtra` app, App-Sandboxed with no network entitlement, reading
+`~/.claude` through a scoped read-only grant. Grab the notarized zip from the
+[Releases page](https://github.com/YiftachCohen/token-tab/releases) when one is up, or
+build it yourself in two minutes from [`app/README.md`](app/README.md) — the from-source
+path is the point of the trust model anyway. Release builds are signed + notarized
+locally, never in CI ([`RELEASING.md`](RELEASING.md)).
+
+## Accuracy
+
+Validated against [`ccusage`](https://github.com/ryoppippi/ccusage) on real logs:
+**99.997% match** on Claude token counts. Two notes:
+
+- `ccusage` now also counts Codex (`gpt-5.5`); Token Tab is Claude-only, so compare
+  Claude-only subtotals.
+- Streaming emits several usage lines per message that share one id, with
+  `output_tokens` growing across them; the parser keeps the last (final) line. It's the
+  one dedup rule that moves the total, and a test pins it.
+
+## Cost
+
+The report and dropdown show a dollar **estimate** next to the token counts — today,
+this week, all time, and per model. It's local arithmetic on a bundled rate table, on
+by default (no network, no key). Scope:
+
+- **An estimate, not your bill.** Bedrock region surcharges and cache-TTL nuances
+  aren't modeled.
+- **The rate table is [`src/pricing.mjs`](src/pricing.mjs)** — Anthropic's published
+  USD-per-million list rates, there to audit and edit. Cache classes derive from the
+  input rate by Anthropic's multipliers: cache **write** = 1.25× input (the 5-minute
+  rate; logs don't record the TTL), cache **read** = 0.10× input. All four token
+  classes are priced separately.
+- **`[1m]` and Bedrock ids normalize to the base model** — no long-context premium on
+  current models; `us.anthropic.<id>` reuses the same list rate.
+- **Unknown model ⇒ tokens counted, price not invented.** It still counts toward every
+  token total; it just lands in an `unpriced` line instead of getting a guessed dollar
+  figure.
+
+Token counts reconcile with `ccusage` (per-model within ~0.03%). The **dollar totals
+differ by design** — `ccusage` prices off LiteLLM's community table, Token Tab off
+Anthropic's list rates — so expect divergence on cache-heavy, Opus-tier usage. Token
+Tab's rates sit in one short, editable file.
+
+## Configuration
+
+Set these as env vars, or in a local `KEY=VALUE` file kept out of the repo —
+`~/.config/token-tab/env` (or `~/.token-tab.env`). Only `TOKENTAB_*` keys (plus
+`CLAUDE_CODE_USE_BEDROCK`) are read; real env vars take precedence.
+
+| Var | What it does |
+|---|---|
+| `TOKENTAB_LOG_DIR` | non-default log directory (default `~/.claude/projects`) |
+| `CLAUDE_CONFIG_DIR` | reads `$CLAUDE_CONFIG_DIR/projects` |
+| `TOKENTAB_WINDOW_CAP` | your plan's 5h token cap, to show a window `%` (see below) |
+| `CLAUDE_CODE_USE_BEDROCK` | Claude Code's Bedrock flag; switches the app to the pay-per-token panel² |
+| `TOKENTAB_LIVE` | opt in to the live server `%` via `claude -p "/usage"` (off by default) |
+| `TOKENTAB_LIVE_CACHE` | where the live sidecar writes its JSON (default `<logDir>/.token-tab-live.json`) |
+| `TOKENTAB_CLAUDE_BIN` | absolute path to `claude` when it isn't auto-resolved (SwiftBar's minimal PATH often needs this) |
+| `TOKENTAB_LIVE_DEBUG` | prints why live data was unavailable to stderr (diagnostic only) |
+
+² On Bedrock, Claude Code logs bare `claude-*` ids that are indistinguishable from a
+subscription, so the mode can't be inferred from the logs — this flag is the signal. A
+sandboxed app launched from Finder won't see your shell exports, so put it in the env
+file above too.
+
+## The 5-hour window
+
+The headline is your token count for today. On a subscription the dropdown also shows
+your current 5-hour rate-limit window, computed entirely from local logs (Anthropic
+resets usage in fixed 5-hour blocks anchored to your first message of the block).
+
+- **The reset countdown is exact** ("Resets in 3h36m"), verified against Claude's own
+  `/usage`: the window starts at your first message, not the top of the hour.
+- **A `%` shows only when you set `TOKENTAB_WINDOW_CAP`.** Anthropic doesn't publish the
+  per-plan cap, and Token Tab won't guess one. To get it: open Claude's `/usage`, note
+  "N% used", and set the cap to `current-window-tokens / (N/100)`. For example, 20M at
+  5% ⇒ `TOKENTAB_WINDOW_CAP=400000000`.
+
+## Live server % (opt-in)
+
+The live server `%` (what Claude's `/usage` shows) is available with `TOKENTAB_LIVE=1`.
+It does not make Token Tab phone home: it shells out to the official `claude` CLI
+(`claude -p "/usage"`), which does the keychain read and the network call, and Token
+Tab only parses the printed summary. The spawn lives in `adapters/claude-live.mjs`,
+outside the audited `src/` core, so the `src/` audit stays clean even with live on.
+
+- **Fails closed.** If `claude` can't be resolved, times out, or its output format
+  changes, it falls back to the local estimate and shows a gray `live unavailable` line
+  (set `TOKENTAB_LIVE_DEBUG=1` for the reason).
+- **Native app: via a sidecar.** The sandboxed app can't spawn `claude`, so the opt-in
+  writer `adapters/write-live.mjs` runs `/usage` in a separate, user-launched process and
+  writes the parsed `%` to `<logDir>/.token-tab-live.json`; the app reads that file as
+  plain data (inside the folder you already granted, ignored by both log walkers — hidden
+  and not `*.jsonl`). The "no network" guarantee stays enforced — the network lives in the
+  sidecar you scheduled.
+
+  ```sh
+  adapters/install-live.sh             # LaunchAgent, refreshes every 5 min
+  adapters/install-live.sh uninstall   # stop + remove it
+  node adapters/write-live.mjs         # one-off, no scheduler
+  ```
+
+  With a fresh reading the app headlines `91% left · live` and learns your cap from it
+  (cap ≈ window tokens ÷ session `%`), persisting it so a real `%` keeps showing once the
+  reading goes stale. On the menu bar, install `swiftbar/token-tab-live.2m.sh` (refreshes
+  every 2 minutes, sets `TOKENTAB_LIVE=1`); the default `token-tab.30s.sh` never spawns
+  anything.
+
+The local 5-hour window stays the default everywhere and needs no opt-in.
+
+## Develop
+
+```sh
+npm test     # node --test, golden-fixture suite for the parser core
+```
+
+`src/core.mjs` is a pure, I/O-free parser (so tests pin every edge case without a
+filesystem); `src/pricing.mjs` is the pure price table + cost math, injected into the
+parser so the rates stay testable; `src/token-tab.mjs` is the thin I/O shell. The Swift
+port in `app/Sources/TokenTabCore` is kept in deliberate parity — see
+[`AGENTS.md`](AGENTS.md).
+
+Branding assets and usage live in [`app/Branding/`](app/Branding/README.md).
+License: MIT.

package/adapters/claude-live.mjs

@@ -0,0 +1,90 @@
+// Token Tab — opt-in live usage adapter.
+//
+// This is the ONLY file in the repo that imports node:child_process. It is
+// deliberately fenced OUTSIDE src/ so the trust-critical core stays a clean
+// sweep: `grep -RnE "child_process|spawn|execFile" src/` prints nothing.
+//
+// It is loaded only via a dynamic import() in src/token-tab.mjs, and only when
+// TOKENTAB_LIVE is enabled. It spawns the official `claude` CLI in print mode
+// (`claude -p "/usage"`), which does the keychain read and the network call;
+// Token Tab only parses the printed stdout. The parser is pure and lives in
+// src/live-parse.mjs.
+//
+// Fail closed: ANY problem (binary not found, non-zero exit, timeout, parse
+// miss) resolves to null. Stores/transmits nothing. The only optional output is
+// a single stderr line when TOKENTAB_LIVE_DEBUG is set.
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { parseUsageOutput } from "../src/live-parse.mjs";
+
+// SwiftBar runs plugins with a minimal PATH (the wrapper already hardcodes the
+// `node` lookup for this reason), so `claude` is usually NOT on PATH there.
+// Resolve it explicitly, honoring an override, then known install locations,
+// then PATH as a last resort.
+function resolveClaude() {
+  if (process.env.TOKENTAB_CLAUDE_BIN) return process.env.TOKENTAB_CLAUDE_BIN;
+  const candidates = [
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+    join(homedir(), ".claude", "local", "claude"),
+    join(homedir(), ".local", "bin", "claude"),
+    join(homedir(), ".bun", "bin", "claude"),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return "claude"; // last resort: PATH
+}
+
+const isDebug = (v) => typeof v === "string" && /^(1|true|yes|on)$/i.test(v.trim());
+
+/**
+ * Spawn `claude -p "/usage" --output-format json`, parse it, and return the live
+ * window object — or null on any failure. Never throws.
+ *
+ * @param {{timeoutMs?:number}} opts
+ * @returns {Promise<null | object>}
+ */
+export async function readLiveUsage({ timeoutMs = 5000 } = {}) {
+  const bin = resolveClaude();
+  const debug = isDebug(process.env.TOKENTAB_LIVE_DEBUG);
+  return await new Promise((resolve) => {
+    let settled = false;
+    const done = (val, reason) => {
+      if (settled) return; // settle exactly once (timeout vs late callback)
+      settled = true;
+      if (val == null && debug && reason) console.error(`[token-tab live] ${reason}`);
+      resolve(val);
+    };
+    let child;
+    try {
+      child = execFile(
+        bin,
+        ["-p", "/usage", "--output-format", "json"],
+        // Run claude in a neutral temp dir, NOT the inherited cwd. `claude -p` still
+        // boots a session rooted at its working directory and indexes it; under the
+        // LaunchAgent that cwd is $HOME, so it walks into ~/Desktop / ~/Documents /
+        // ~/Downloads and trips macOS's TCC consent prompts (attributed to the parent
+        // "node"). /usage reads the server quota, never local files, so an empty
+        // tmpdir gives it nothing to scan and the prompts never fire.
+        { cwd: tmpdir(), timeout: timeoutMs, killSignal: "SIGTERM", maxBuffer: 256 * 1024, windowsHide: true },
+        (err, stdout) => {
+          if (err) return done(null, `spawn failed: ${err.code || err.message}`);
+          const parsed = parseUsageOutput(stdout);
+          return done(parsed, parsed ? null : "parse miss");
+        },
+      );
+    } catch (e) {
+      return done(null, `exec threw: ${e.message}`);
+    }
+    // Never let `claude -p` block waiting on stdin.
+    try {
+      child.stdin?.end();
+    } catch {
+      /* ignore */
+    }
+  });
+}

package/adapters/install-live.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Token Tab — install the live sidecar as a per-user LaunchAgent.
+#
+# This is the "blessed" way to keep the live server-% fresh: it runs
+# adapters/write-live.mjs on a timer so the menu-bar app always has a recent
+# reading to display. The app itself never runs this — it's sandboxed with no
+# network. Everything the network/keychain touches lives in this scheduled
+# helper, which YOU install here and can remove at any time.
+#
+# Usage:
+#   adapters/install-live.sh            # install + load (refresh every 5 min)
+#   adapters/install-live.sh uninstall  # stop + remove the LaunchAgent
+#   adapters/install-live.sh print      # print the plist it would write (no changes)
+#
+# Override the cadence:  TOKENTAB_LIVE_INTERVAL=120 adapters/install-live.sh
+set -euo pipefail
+
+LABEL="com.tokentab.live"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # adapters/
+SIDECAR="$HERE/write-live.mjs"
+LOG="$HOME/Library/Logs/token-tab-live.log"
+INTERVAL="${TOKENTAB_LIVE_INTERVAL:-300}"
+DOMAIN="gui/$(id -u)"
+
+# Resolve node (baked in absolutely — launchd has a minimal PATH) and claude
+# (passed as TOKENTAB_CLAUDE_BIN so the sidecar finds it without a login shell).
+NODE="$(command -v node || true)"
+CLAUDE="$(command -v claude || true)"
+for c in /opt/homebrew/bin/claude /usr/local/bin/claude "$HOME/.local/bin/claude" "$HOME/.claude/local/claude" "$HOME/.bun/bin/claude"; do
+  [ -z "$CLAUDE" ] && [ -x "$c" ] && CLAUDE="$c"
+done
+
+gen_plist() {
+  local claude_env=""
+  [ -n "$CLAUDE" ] && claude_env="
+    <key>TOKENTAB_CLAUDE_BIN</key><string>$CLAUDE</string>"
+  cat <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>$LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$NODE</string>
+    <string>$SIDECAR</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>$claude_env
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>StartInterval</key><integer>$INTERVAL</integer>
+  <key>StandardOutPath</key><string>$LOG</string>
+  <key>StandardErrorPath</key><string>$LOG</string>
+</dict>
+</plist>
+PLIST
+}
+
+case "${1:-install}" in
+  print)
+    gen_plist
+    ;;
+  uninstall)
+    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || launchctl unload "$PLIST" 2>/dev/null || true
+    rm -f "$PLIST"
+    echo "✓ live helper removed ($LABEL)"
+    ;;
+  install)
+    [ -n "$NODE" ] || { echo "✗ node not found on PATH — install Node, then re-run"; exit 1; }
+    [ -f "$SIDECAR" ] || { echo "✗ sidecar missing at $SIDECAR"; exit 1; }
+    [ -n "$CLAUDE" ] || echo "⚠ claude not found in the usual spots — set TOKENTAB_CLAUDE_BIN if live can't resolve it"
+    mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs"
+    gen_plist > "$PLIST"
+    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
+    launchctl bootstrap "$DOMAIN" "$PLIST" 2>/dev/null || launchctl load "$PLIST"
+    echo "✓ live helper installed — refreshing every ${INTERVAL}s"
+    echo "  reads:  $SIDECAR"
+    echo "  log:    $LOG"
+    echo "  remove: $0 uninstall"
+    ;;
+  *)
+    echo "usage: $0 [install|uninstall|print]"; exit 2
+    ;;
+esac

package/adapters/write-live.mjs

@@ -0,0 +1,85 @@
+// Token Tab — live-usage cache WRITER (opt-in, networked, fenced OUTSIDE src/).
+//
+// This is the bridge that lets the sandboxed menu-bar app show the real server-side %
+// WITHOUT the app itself ever touching the network. The app cannot run `claude` (no
+// network entitlement — enforced), so instead THIS process — separate, user-launched —
+// does the `claude -p "/usage"` call (via the existing adapter), parses it, and writes the
+// percentages to a small JSON file the app then reads as plain data.
+//
+// The network + keychain access lives entirely here, in something you opted into and
+// scheduled yourself. Run it on a timer to keep the app's live numbers fresh:
+//
+//   # one-off
+//   node adapters/write-live.mjs
+//   # every 2 minutes via launchd / cron / SwiftBar wrapper
+//
+// Writes to `<logDir>/.token-tab-live.json` (logDir = the same dir token-tab.mjs reads),
+// which is inside the folder the app is already granted — so no extra permission, and both
+// log walkers ignore it (hidden + not *.jsonl). Atomic write so the app never sees a
+// half-written file. Fails closed: if the live read returns null, nothing is written.
+
+import { writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { readLiveUsage } from "./claude-live.mjs";
+
+const SCHEMA = 1;
+
+/// Mirror resolveLogDir() in src/token-tab.mjs so the cache lands where the app reads.
+export function liveCachePath(env = process.env) {
+  const file = ".token-tab-live.json";
+  if (env.TOKENTAB_LIVE_CACHE) return env.TOKENTAB_LIVE_CACHE; // explicit override
+  if (env.TOKENTAB_LOG_DIR) return join(env.TOKENTAB_LOG_DIR, file);
+  if (env.CLAUDE_CONFIG_DIR) return join(env.CLAUDE_CONFIG_DIR, "projects", file);
+  return join(homedir(), ".claude", "projects", file);
+}
+
+/// PURE: shape a parsed live reading into the on-disk JSON (or null if there's nothing to
+/// write). Kept separate from I/O so it's unit-testable without spawning `claude`. Percent
+/// fields are normalized to `null` (not undefined) so the JSON is stable and explicit.
+export function serializeLive(reading, capturedAtIso) {
+  if (!reading || (reading.sessionPct == null && reading.weeklyPct == null)) return null;
+  return JSON.stringify(
+    {
+      schema: SCHEMA,
+      source: reading.source || "claude /usage",
+      capturedAt: capturedAtIso,
+      sessionPct: reading.sessionPct ?? null,
+      sessionResetText: reading.sessionResetText ?? null,
+      weeklyPct: reading.weeklyPct ?? null,
+      weeklyResetText: reading.weeklyResetText ?? null,
+      weeklyByModel: reading.weeklyByModel || {},
+    },
+    null,
+    2,
+  );
+}
+
+/// Read live usage and atomically write the cache. Never throws; returns a small status.
+export async function writeLiveCache({ path = liveCachePath(), now = new Date() } = {}) {
+  const reading = await readLiveUsage();
+  const json = serializeLive(reading, now.toISOString());
+  if (!json) return { ok: false, reason: "live unavailable — wrote nothing" };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, json, { mode: 0o600 });
+    renameSync(tmp, path); // atomic swap — the app never reads a torn file
+    return { ok: true, path };
+  } catch (e) {
+    return { ok: false, reason: `write failed: ${e.message}` };
+  }
+}
+
+// CLI entry: `node adapters/write-live.mjs`. Status goes to stderr (never stdout), so the
+// command is quiet on success and composes cleanly inside a SwiftBar/cron wrapper.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  writeLiveCache().then((r) => {
+    if (r.ok) {
+      console.error(`[token-tab] wrote ${r.path}`);
+    } else {
+      console.error(`[token-tab] ${r.reason}`);
+      process.exit(1);
+    }
+  });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ycstudios/token-tab",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "A provably-safe AI usage meter for the macOS menu bar. Reads local Claude Code logs, makes no network calls, keeps none of your content.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YiftachCohen/token-tab.git"
+  },
+  "homepage": "https://github.com/YiftachCohen/token-tab#readme",
+  "bugs": "https://github.com/YiftachCohen/token-tab/issues",
+  "bin": {
+    "token-tab": "src/token-tab.mjs"
+  },
+  "files": [
+    "src",
+    "adapters",
+    "swiftbar"
+  ],
+  "scripts": {
+    "start": "node src/token-tab.mjs",
+    "swiftbar": "node src/token-tab.mjs --swiftbar",
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "keywords": ["claude", "claude-code", "tokens", "usage", "menubar", "macos", "ccusage"]
+}