tokenjam 0.5.3 → 0.5.6

package/README.md

@@ -1,40 +1,69 @@
-# `tokenjam` — zero-install TokenJam launcher (command: `tj`)
+# tokenjam
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Metabuilder-Labs/tokenjam/main/docs/brand/tokenjam-repo-header.png" alt="TokenJam: token efficiency for AI agents. Reads your agent's telemetry, finds the waste, runs 100% local." width="760">
+
+[![npm](https://img.shields.io/npm/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/tokenjam)
+[![npm downloads](https://img.shields.io/npm/dm/tokenjam?color=3d8eff&labelColor=0d1117&label=downloads)](https://www.npmjs.com/package/tokenjam)
+[![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](https://github.com/Metabuilder-Labs/tokenjam/blob/main/LICENSE)
+
+</div>
+
+TokenJam ingests telemetry data about your agents from a multitude of sources and provides you a quick and easy way to visualize and optimize cost so that you get the most out of the tokens you pay for. This package is the zero-install launcher: one command, no pip environment, no config.
 
 ```bash
 npx tokenjam
 ```
 
-That one command reads your `~/.claude/projects/*.jsonl` session logs
-and shows you **where your
-Claude Code quota actually goes** — quota composition (re-reading context vs.
-net-new work) plus a session timeline. No pip env, no daemon, no onboarding.
+## What you get
 
-This npm package is a **thin launcher** for the real CLI, which is the Python
-package [`tokenjam`](https://pypi.org/project/tokenjam/) (command: `tj`). `npx tokenjam`
-shells out to the first available Python runner:
+Bare `npx tokenjam` reads the session logs you already have (Claude Code today; more sources land in the full CLI) and prints a 15-second, read-only report: quota composition (what share of your tokens went to re-reading history and context vs. net-new work) plus a session timeline. Nothing is installed, nothing is kept.
 
-1. `uvx --from tokenjam tj …`
-2. `pipx run --spec tokenjam tj …`
-3. an already-installed `tj` on your `PATH`
+<div align="center">
+<img src="https://raw.githubusercontent.com/Metabuilder-Labs/tokenjam/main/docs/assets/tj-quickstart-hero.png" alt="Sample npx tokenjam output: quota composition (95.9% re-reading context, 4.1% net-new work) and a session timeline table" width="620">
+</div>
+
+## Commands
 
-All arguments pass straight through, so `npx tokenjam quickstart --since 7d`,
-`npx tokenjam context`, `npx tokenjam optimize`, etc. all work.
+All arguments pass straight through to the Python CLI, so any `tj` subcommand and flag works here too.
+
+| Command | What it does |
+|---|---|
+| `npx tokenjam` / `npx tokenjam quickstart` | Zero-install first run: quota composition and a session timeline from your existing session logs. |
+| `npx tokenjam context` | Where your quota goes: re-read vs. net-new share, recurring inclusions, `/compact` candidates. |
+| `npx tokenjam optimize` | Cost-saving candidates: model downsizing, cache opportunities, prompt trimming, workflow reuse, subagent right-sizing. |
+| `npx tokenjam onboard` | Guided setup: writes a config, generates an ingest secret, and optionally installs the background daemon for live capture. |
 
 ## Go deeper
 
-`npx tokenjam` is the no-setup front door. When you want live capture, the local
-dashboard, and the MCP server for Claude Code, install the full CLI and onboard:
+`npx tokenjam` is the no-setup front door. One command sets up live capture, the local Lens dashboard, and the zero-token statusline:
 
 ```bash
-pipx install tokenjam
-tj onboard
+npx tokenjam onboard   # or: pipx install tokenjam && tj onboard
 ```
 
-See the [TokenJam README](https://github.com/Metabuilder-Labs/tokenjam) for the
-full feature set.
+`tj onboard` asks how you use AI agents (Claude Code, Codex, or your own SDK/API agents) and wires the right path. For Claude Code and Codex that means backfilling recent history plus a statusline and hooks; restart and you're live. From there:
+
+```bash
+tj optimize   # cost-saving candidates from your actual usage
+tj serve      # open the Lens dashboard at http://127.0.0.1:7391/
+```
+
+- Full feature set, six analyzers, and Lens screenshots: [github.com/Metabuilder-Labs/tokenjam](https://github.com/Metabuilder-Labs/tokenjam)
+- Product site and docs: [tokenjam.dev](https://tokenjam.dev)
+
+## How the launcher works
+
+This npm package is a thin launcher, not the real CLI. `npx tokenjam` shells out to the first available Python runner:
+
+1. `uvx --from tokenjam tj …`
+2. `pipx run --spec tokenjam tj …`
+3. an already-installed `tj` on your `PATH`
+
+The real CLI is the Python package [`tokenjam`](https://pypi.org/project/tokenjam/) (command: `tj`).
 
 ## Requirements
 
-A Python runner — [`uv`](https://docs.astral.sh/uv/) (recommended) or
-[`pipx`](https://pipx.pypa.io/). If neither is present, `npx tokenjam` prints install
-guidance.
+A Python runner: [`uv`](https://docs.astral.sh/uv/) (recommended) or [`pipx`](https://pipx.pypa.io/). If neither is present, `npx tokenjam` prints install guidance instead of failing silently.

package/bin/tj.js

@@ -16,10 +16,27 @@
  *   3. `tj …`                      — an already-installed CLI on PATH
  *
  * If none are present we print actionable install guidance and exit non-zero.
+ *
+ * Note: tokenjam >=0.5.4 also ships a `tokenjam` console-script alias
+ * alongside `tj`, so bare `uvx tokenjam` / `pipx run tokenjam` work too. This
+ * wrapper keeps the explicit `--from tokenjam tj` / `--spec tokenjam tj` form
+ * below for back-compat with the 0.5.3 and earlier releases it also targets.
+ *
+ * Freshness (issue #111): `uv` reuses its cached tool environment and never
+ * re-resolves on its own, so a machine that first ran this wrapper on an old
+ * release keeps getting that release forever, even after newer ones hit
+ * PyPI. To avoid pinning stale versions indefinitely, the `uvx` branch passes
+ * `--refresh` at most once per 24h (tracked via a timestamp file — see
+ * `shouldRefresh`/`markRefreshed` below). `pipx run` isn't touched: its own
+ * cache already expires after ~14 days on its own. The installed-`tj` branch
+ * has no cache to go stale.
  */
 "use strict";
 
 const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 
 // PyPI package name vs. command name differ (`tokenjam` ships the `tj` script),
 // so ephemeral runners must be told the source package explicitly.
@@ -40,6 +57,60 @@ function runners() {
   ];
 }
 
+// --- uvx cache freshness (issue #111) -------------------------------------
+//
+// Only the `uvx` runner needs this: `uv` caches a resolved tool environment
+// and reuses it forever unless told to `--refresh`, so a returning user
+// silently keeps whatever version they first resolved. Tracked with a plain
+// timestamp file rather than anything fancier — this wrapper is intentionally
+// dependency-free (stdlib `fs`/`os`/`path` only).
+
+const REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+
+function refreshCacheDir() {
+  const xdgCacheHome = process.env.XDG_CACHE_HOME;
+  const base =
+    xdgCacheHome && xdgCacheHome.trim()
+      ? xdgCacheHome
+      : path.join(os.homedir(), ".cache");
+  return path.join(base, "tokenjam-npx");
+}
+
+function refreshTimestampPath() {
+  return path.join(refreshCacheDir(), "last-refresh");
+}
+
+// True if it's been >24h (or we've never refreshed / can't tell). Fails
+// open on any fs error — an unwritable/unreadable cache dir must never
+// break the wrapper, it just means we skip the freshness nudge this run.
+function shouldRefresh() {
+  try {
+    const stat = fs.statSync(refreshTimestampPath());
+    return Date.now() - stat.mtimeMs > REFRESH_INTERVAL_MS;
+  } catch {
+    return true; // no timestamp yet (or unreadable) => treat as stale
+  }
+}
+
+// Called only AFTER `uvx --refresh` has actually returned with a zero exit
+// status (not before we spawn it, and not on failure). If the refresh's
+// download is interrupted partway through (network drop, Ctrl-C, OOM kill),
+// spawnSync never returns normally, this never runs. If it returns but uv
+// exits non-zero (PyPI unreachable, partial download), the caller also
+// skips this call. Either way the *next* invocation still sees a
+// stale/missing timestamp and retries `--refresh`. Writing the timestamp up
+// front, or unconditionally on return, would mark the cache "fresh" even
+// though that refresh never completed, silently pinning a broken/partial
+// environment for a full 24h. Best-effort/fail-open: swallow fs errors.
+function markRefreshed() {
+  try {
+    fs.mkdirSync(refreshCacheDir(), { recursive: true });
+    fs.writeFileSync(refreshTimestampPath(), String(Date.now()));
+  } catch {
+    // fail open — worst case we just try to refresh again next run
+  }
+}
+
 function main() {
   // Bare `npx tokenjam` IS the zero-install first run — route it to
   // `tj quickstart` (the quota report the docs promise). The branded home
@@ -51,10 +122,14 @@ function main() {
 
   for (const { bin, prefix } of runners()) {
     if (!has(bin)) continue;
-    const result = spawnSync(bin, [...prefix, ...passthrough], {
+    const isUvx = bin === "uvx";
+    const doRefresh = isUvx && shouldRefresh();
+    const args = doRefresh ? ["--refresh", ...prefix] : prefix;
+    const result = spawnSync(bin, [...args, ...passthrough], {
       stdio: "inherit",
     });
     if (result.error) continue; // try the next runner on spawn failure
+    if (doRefresh && result.status === 0) markRefreshed();
     process.exit(result.status === null ? 1 : result.status);
   }
 

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "tokenjam",
-  "version": "0.5.3",
-  "description": "Zero-install launcher for TokenJam (tj) — `npx tokenjam` runs the Python CLI via uvx/pipx and prints where your Claude Code quota actually goes, no setup.",
-  "keywords": ["claude-code", "ccusage", "tokens", "cost", "llm", "agents", "observability", "tokenjam"],
+  "version": "0.5.6",
+  "description": "Zero-install launcher for TokenJam (tj): npx tokenjam runs the Python CLI via uvx/pipx and prints where your AI agent's token quota actually goes, no setup required.",
+  "keywords": [
+    "claude-code",
+    "ccusage",
+    "tokens",
+    "cost",
+    "llm",
+    "agents",
+    "observability",
+    "tokenjam",
+    "anthropic",
+    "claude",
+    "token-usage",
+    "cost-tracking",
+    "cli",
+    "statusline",
+    "opentelemetry",
+    "agent-observability"
+  ],
   "homepage": "https://tokenjam.dev",
   "bugs": "https://github.com/Metabuilder-Labs/tokenjam/issues",
   "license": "MIT",
@@ -12,7 +29,8 @@
     "directory": "npm-wrapper"
   },
   "bin": {
-    "tj": "bin/tj.js"
+    "tj": "bin/tj.js",
+    "tokenjam": "bin/tj.js"
   },
   "files": [
     "bin/tj.js",