tokenjam 0.5.6 → 0.6.0

package/README.md

@@ -11,19 +11,15 @@
 
 </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.
+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: no pip environment, no manual config.
 
 ```bash
-npx tokenjam
+npx tokenjam onboard   # or: pipx install tokenjam && tj onboard
 ```
 
 ## What you get
 
-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.
-
-<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>
+`tj onboard` is guided setup: it writes a config, generates an ingest secret, and asks how you use AI agents (Claude Code, Codex, or your own SDK/API agents) to wire the right path. For Claude Code and Codex that means backfilling recent history and installing a statusline and hooks for live capture; restart and you're live. Onboarding unlocks all six analyzers, the Lens dashboard, and the zero-token statusline in one command.
 
 ## Commands
 
@@ -31,20 +27,14 @@ All arguments pass straight through to the Python CLI, so any `tj` subcommand an
 
 | 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 onboard` | Guided setup: writes a config, generates an ingest secret, and optionally installs the background daemon for live capture. |
 | `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. |
+| `npx tokenjam` | Bare run: still works, still zero-install, still a reference passthrough to the Python CLI. |
 
 ## Go deeper
 
-`npx tokenjam` is the no-setup front door. One command sets up live capture, the local Lens dashboard, and the zero-token statusline:
-
-```bash
-npx tokenjam onboard   # or: pipx install tokenjam && tj onboard
-```
-
-`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:
+`tj onboard` sets up live capture, the local Lens dashboard, and the zero-token statusline in one command. From there:
 
 ```bash
 tj optimize   # cost-saving candidates from your actual usage

package/bin/tj.js

@@ -7,8 +7,9 @@
  * `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.
+ * (no subcommand) prints the zero-install report: 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
@@ -112,13 +113,19 @@ function markRefreshed() {
 }
 
 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.
+  // Bare `npx tokenjam` IS the zero-install first run — 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; a bare invocation stays bare (no synthetic subcommand — there
+  // is no public/typeable command for this) and instead sets an env var that
+  // the Python CLI's own no-subcommand branch reads to pick the report over
+  // the home screen.
   const argv = process.argv.slice(2);
-  const passthrough = argv.length ? argv : ["quickstart"];
+  const passthrough = argv;
+  const childEnv = argv.length
+    ? process.env
+    : { ...process.env, TJ_NPX_ZERO_INSTALL_REPORT: "1" };
 
   for (const { bin, prefix } of runners()) {
     if (!has(bin)) continue;
@@ -127,6 +134,7 @@ function main() {
     const args = doRefresh ? ["--refresh", ...prefix] : prefix;
     const result = spawnSync(bin, [...args, ...passthrough], {
       stdio: "inherit",
+      env: childEnv,
     });
     if (result.error) continue; // try the next runner on spawn failure
     if (doRefresh && result.status === 0) markRefreshed();

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "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.",
+  "version": "0.6.0",
+  "description": "Zero-install launcher for TokenJam (tj): npx tokenjam runs the Python CLI via uvx/pipx and reports the recurring mistakes your AI agent keeps repeating, no setup required.",
   "keywords": [
     "claude-code",
     "ccusage",
     "tokens",
-    "cost",
+    "cost-optimization",
     "llm",
     "agents",
     "observability",
@@ -14,7 +14,7 @@
     "anthropic",
     "claude",
     "token-usage",
-    "cost-tracking",
+    "agent-behavior",
     "cli",
     "statusline",
     "opentelemetry",