tokentrax 0.1.0 → 0.1.1

package/README.md

@@ -13,9 +13,21 @@
 ### Via npm (recommended)
 
 ```bash
-npm install -g tokentrax
+npm install -g tokentrax --allow-scripts=better-sqlite3
 ```
 
+> **Why the flag?** npm 12 and newer block dependency install scripts by
+> default, and `better-sqlite3` is a native module — its install script is
+> what fetches or builds the binding. Without the flag you get an install
+> that *looks* fine and then fails the first time it opens a database.
+> Older npm versions ignore the flag, so the command works everywhere.
+>
+> If you'd rather set it once:
+>
+> ```bash
+> npm config set allow-scripts=better-sqlite3 --location=user
+> ```
+
 ### Via git clone
 
 ```bash
@@ -38,21 +50,6 @@ This installs TokenTrax globally and automatically:
 - Runs database migrations (schema updates are applied automatically)
 - Backfills pricing for any existing data without costs
 
-### Remote agent
-
-To report usage from a *second* machine — a laptop, a work box, anywhere
-with an AI harness — install the agent there:
-
-```bash
-npm install -g tokentrax-agent
-tokentrax-agent setup --server http://your-dashboard:7680 --key <sync-key>
-```
-
-That writes the configuration, installs a systemd user timer and starts it.
-The machine then reports its sessions, tokens and cost to the dashboard every
-five minutes. See [`agent/README.md`](agent/README.md) for the details, and
-[`docs/agent-configuration.md`](docs/agent-configuration.md) for every option.
-
 ### Requirements
 
 - Node.js >= 20
@@ -74,6 +71,37 @@ npm update -g tokentrax
 
 Updates are safe — the postinstall script automatically migrates your existing database schema and backfills any missing pricing data.
 
+### Remote agent
+
+To report usage from a *second* machine — a laptop, a work box, anywhere
+with an AI harness — install the agent there. It ships as its own npm
+package:
+
+```bash
+npm install -g tokentrax-agent --allow-scripts=better-sqlite3
+tokentrax-agent setup --server http://your-dashboard:7680 --key <sync-key>
+```
+
+The `--allow-scripts` flag is for npm 12+, which blocks dependency install
+scripts by default — `better-sqlite3` needs its install script to build a
+native module. Older npm ignores the flag. See the note in the
+[Installation](#installation) section above.
+
+`setup` writes the configuration, installs a systemd user timer, and starts it.
+The machine then reports its sessions, tokens and cost to the dashboard every
+five minutes.
+
+No npm? Bootstrap straight from the repository:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jeshuwah/TokenTrax/main/agent/install.sh \
+  | bash -s -- --server http://your-dashboard:7680 --key <sync-key>
+```
+
+Full details in [`agent/README.md`](agent/README.md) and
+[`docs/agent-configuration.md`](docs/agent-configuration.md). See
+[Remote agents](#remote-agents) for how it fits together.
+
 ---
 
 ## Features
@@ -85,6 +113,7 @@ Updates are safe — the postinstall script automatically migrates your existing
 - **Bundled + live pricing** — 2200+ model prices cached locally, auto-refreshed
 - **Normalization engine** — maps 100+ model aliases to canonical names
 - **Privacy-first** — all data stays in `~/.tokentrax/`, no telemetry
+- **Optional remote agents** — one dashboard, many machines, via `tokentrax-agent`
 
 ---
 
@@ -118,6 +147,12 @@ Theme toggle (dark/light), pricing freshness indicator, normalization rule edito
 
 <img src="docs/screenshots/settings.png" alt="Settings" width="100%">
 
+### Agents
+
+Every machine reporting into this dashboard — sessions, tokens, cost and
+context-reduction percentage — with a per-machine breakdown by model and
+per-session detail. See [Remote agents](#remote-agents).
+
 ---
 
 ## Supported AI Tools
@@ -140,6 +175,78 @@ Theme toggle (dark/light), pricing freshness indicator, normalization rule edito
 
 ---
 
+## Remote agents
+
+TokenTrax is local-first: one machine, one SQLite file, no server. The
+optional `tokentrax-agent` package adds the other half — reporting from
+*other* machines into the same dashboard.
+
+```
+  laptop (omarchy)                server (olympus)
+  ┌──────────────────────┐         ┌────────────────────────┐
+  │ pi / Claude / Codex  │  POST   │  tokentrax serve :7680 │
+  │      tokentrax-agent │────────▶│  agent_sessions table  │
+  │   systemd timer 5min │         │  "Agents" dashboard tab │
+  └──────────────────────┘         └────────────────────────┘
+```
+
+Each remote machine runs the agent on a timer. It reads that machine's
+harness session data, condenses it, and POSTs it to the dashboard. The
+dashboard shows every machine in one list with sessions, tokens, cost and
+context-reduction percentage.
+
+### Install on the remote machine
+
+```bash
+npm install -g tokentrax-agent --allow-scripts=better-sqlite3
+tokentrax-agent setup --server http://your-dashboard:7680 --key <sync-key>
+```
+
+`setup` writes the configuration, verifies the native SQLite binding loads,
+installs a systemd user service and timer, and enables it. It is safe to
+re-run.
+
+### Prepare the dashboard
+
+The server needs a shared key before it will accept anything:
+
+```bash
+export TOKENTRAX_SYNC_KEY=$(openssl rand -base64 48)
+npm start serve
+```
+
+The same value goes on every remote machine. With a key set, the server
+refuses writes from anything that is not loopback, so it is safe to expose
+on a LAN or over a VPN.
+
+### What crosses the wire
+
+Session metadata and usage numbers only — never prompts, file contents or
+tool arguments. Project paths are hashed by default
+(`TOKENTRAX_TRACK_PROJECT=hash`), so the dashboard never learns your
+directory names. Set it to `full` only if you want the real paths.
+
+### A note on hooks
+
+The agent installs post-session hooks for harnesses that support them. The
+harness with the most data — pi — has no hook mechanism at all, so a hook
+would silently never fire there. The systemd timer is what actually keeps
+the data flowing, and it works for every harness.
+
+### Agent commands
+
+| Command | Description |
+| --------- | ------------- |
+| `tokentrax-agent setup --server <url> --key <key>` | Configure the machine and start the timer |
+| `tokentrax-agent sync [--auto]` | Send new sessions to the server |
+| `tokentrax-agent status` | Show configuration, machine id and cursor |
+| `tokentrax-agent init` | Install post-session hooks where supported |
+| `tokentrax-agent uninstall` | Remove post-session hooks |
+
+See [`agent/README.md`](agent/README.md) for the full package documentation.
+
+---
+
 ## Commands
 
 ### Core Commands
@@ -203,6 +310,19 @@ All data stored in `~/.tokentrax/`:
 - **Auditable** — open source, read the parser code in `src/lib/parsers/`
 - **No telemetry** — no analytics, no crash reporting, no phone-home
 
+### …unless you install the remote agent
+
+`tokentrax-agent` is the one exception, and it is entirely opt-in: you
+install it, on a machine you choose, and point it at a dashboard you
+control. It sends session metadata and usage numbers to that one URL —
+never prompts, file contents or tool arguments — and it sends nothing at
+all until you run `tokentrax-agent setup`.
+
+TokenTrax itself never phones home. The agent is a separate package, so
+installing TokenTrax does not install it.
+
+See [Remote agents](#remote-agents).
+
 ---
 
 ## Development
@@ -227,6 +347,10 @@ tokentrax/
 │       ├── sqlite.js      # DB schema + upsert logic
 │       ├── pricing.js     # Cost computation
 │       └── parsers/       # One parser per AI tool (13 total)
+├── agent/                 # tokentrax-agent — separate npm package
+│   ├── bin/agent.js       # Remote agent entry point
+│   ├── install.sh         # Bootstrap script
+│   └── src/               # setup, sync, session parsing, hooks
 ├── dashboard/
 │   └── index.html         # Single-file SPA dashboard
 ├── docs/

package/bin/tracker.js

@@ -1,10 +1,58 @@
 #!/usr/bin/env node
-const { run } = require("../src/cli.js");
+// Entry point for the TokenTrax CLI.
+//
+// One failure deserves a friendly explanation: a missing better-sqlite3
+// native binding. npm 12+ blocks dependency install scripts by default, and
+// better-sqlite3's binding is built by its install script. `require()` of
+// the module succeeds without it, so the failure only surfaces when a
+// database is opened — which for `tokentrax sync` is a runtime error deep
+// inside a parser.
+//
+// Left alone, the user gets a wall of "Could not locate the bindings file.
+// Tried: ..." listing eight paths, which tells them nothing about what to
+// do about it.
+
+/**
+ * Is this the missing-native-binding failure?
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isMissingBinding(err) {
+  const message = String((err && err.message) || "");
+  return /bindings|Could not locate the bindings file/i.test(message);
+}
+
+function explainMissingBinding() {
+  console.error(
+    "\n✗ better-sqlite3's native binding is missing.\n\n" +
+      "  This normally means the package's install script was blocked.\n" +
+      "  Fix it with:\n\n" +
+      "    npm install-scripts approve better-sqlite3\n" +
+      "    npm rebuild better-sqlite3\n\n" +
+      "  Or reinstall with:\n\n" +
+      "    npm install -g tokentrax --allow-scripts=better-sqlite3\n",
+  );
+}
+
+let run;
+try {
+  ({ run } = require("../src/cli.js"));
+} catch (err) {
+  if (isMissingBinding(err)) {
+    explainMissingBinding();
+    process.exit(1);
+  }
+  throw err;
+}
 
 (async () => {
   try {
     await run(process.argv.slice(2));
   } catch (err) {
+    if (isMissingBinding(err)) {
+      explainMissingBinding();
+      process.exit(1);
+    }
     console.error("tokentrax:", err.message);
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrax",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lean, local-first AI token usage tracker — zero bloat",
   "main": "src/cli.js",
   "bin": {