tokenjam 0.5.3

package/README.md

@@ -0,0 +1,40 @@
+# `tokenjam` — zero-install TokenJam launcher (command: `tj`)
+
+```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.
+
+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:
+
+1. `uvx --from tokenjam tj …`
+2. `pipx run --spec tokenjam tj …`
+3. an already-installed `tj` on your `PATH`
+
+All arguments pass straight through, so `npx tokenjam quickstart --since 7d`,
+`npx tokenjam context`, `npx tokenjam optimize`, etc. all work.
+
+## 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:
+
+```bash
+pipx install tokenjam
+tj onboard
+```
+
+See the [TokenJam README](https://github.com/Metabuilder-Labs/tokenjam) for the
+full feature set.
+
+## 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.

package/bin/tj.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/*
+ * Zero-install launcher for TokenJam (`npx tokenjam`), issue #6.
+ *
+ * TokenJam's CLI is a Python package (`tokenjam`, command `tj`). This thin npm
+ * wrapper exists for one reason: the Claude Code / ccusage crowd reaches for
+ * `npx <tool>` first. `npx tokenjam` here resolves a Python launcher with NO pip env,
+ * NO daemon, NO onboarding — it shells out to the Python CLI via the first
+ * available runner and hands every argument straight through. Bare `npx tokenjam`
+ * (no subcommand) routes to `tj quickstart`: where your Claude Code quota goes,
+ * from the same ~/.claude/projects/*.jsonl files ccusage reads, in one command.
+ *
+ * Runner preference (first that exists wins):
+ *   1. `uvx --from tokenjam tj …`  — fully ephemeral, downloads nothing global
+ *   2. `pipx run --spec tokenjam tj …`
+ *   3. `tj …`                      — an already-installed CLI on PATH
+ *
+ * If none are present we print actionable install guidance and exit non-zero.
+ */
+"use strict";
+
+const { spawnSync } = require("child_process");
+
+// PyPI package name vs. command name differ (`tokenjam` ships the `tj` script),
+// so ephemeral runners must be told the source package explicitly.
+const PACKAGE = "tokenjam";
+const COMMAND = "tj";
+
+function has(bin) {
+  // `<bin> --version` is a cheap, side-effect-free presence probe.
+  const probe = spawnSync(bin, ["--version"], { stdio: "ignore" });
+  return probe.status === 0 || probe.status === 1; // 1 = exists but no --version
+}
+
+function runners() {
+  return [
+    { bin: "uvx", prefix: ["--from", PACKAGE, COMMAND] },
+    { bin: "pipx", prefix: ["run", "--spec", PACKAGE, COMMAND] },
+    { bin: COMMAND, prefix: [] }, // already installed on PATH
+  ];
+}
+
+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
+  // screen that bare LOCAL `tj` prints assumes an installed CLI and would
+  // dead-end an npx user ("You're set up", suggesting commands they don't
+  // have). Any explicit args pass through untouched.
+  const argv = process.argv.slice(2);
+  const passthrough = argv.length ? argv : ["quickstart"];
+
+  for (const { bin, prefix } of runners()) {
+    if (!has(bin)) continue;
+    const result = spawnSync(bin, [...prefix, ...passthrough], {
+      stdio: "inherit",
+    });
+    if (result.error) continue; // try the next runner on spawn failure
+    process.exit(result.status === null ? 1 : result.status);
+  }
+
+  process.stderr.write(
+    "\n" +
+      "tj (TokenJam) needs a Python runner to launch its CLI.\n" +
+      "Install one of these, then re-run `npx tokenjam`:\n" +
+      "  • uv     →  https://docs.astral.sh/uv/  (then `uvx --from tokenjam tj`)\n" +
+      "  • pipx   →  `brew install pipx` / `apt install pipx`\n" +
+      "Or install TokenJam directly:  pipx install tokenjam\n\n"
+  );
+  process.exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "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"],
+  "homepage": "https://tokenjam.dev",
+  "bugs": "https://github.com/Metabuilder-Labs/tokenjam/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Metabuilder-Labs/tokenjam.git",
+    "directory": "npm-wrapper"
+  },
+  "bin": {
+    "tj": "bin/tj.js"
+  },
+  "files": [
+    "bin/tj.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}