tokenwatch-sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # TokenWatch
 
+**[Website](https://jkhusanovpn.github.io/tokenwatch/)** · **[npm](https://www.npmjs.com/package/tokenwatch-sdk)**
+
 **Know where your LLM money goes.** Zero-config cost & quality monitor for indie AI builders: one-line SDK, local dashboard, per-feature/per-customer attribution, and a budget kill-switch so an agent loop can never surprise you with a 5-figure bill.
 
 - No proxy in your request path — your calls go straight to the provider, telemetry is sent async on the side
@@ -49,6 +51,18 @@ import { track } from 'tokenwatch';
 track({ model: 'claude-fable-5', inputTokens: 1200, outputTokens: 400, feature: 'batch-job', customerId: 'acme' });
 ```
 
+### Track your coding agents too
+
+Claude Code and Codex CLI make API calls you can't wrap — but they write session logs. `tokenwatch watch` tails them (read-only, no proxy, no agent config):
+
+```bash
+npx tokenwatch-sdk serve --watch --backfill   # server + agent-log watcher in one process
+# or separately:
+npx tokenwatch-sdk watch --backfill           # Claude Code (~/.claude) + Codex (~/.codex)
+```
+
+Spend appears per agent (`claude-code`, `codex`) and per project. Note: if you're on a subscription plan, the dollar figures are API-equivalent value, not your actual bill. Antigravity doesn't expose local session logs yet — open an issue if you know a way in.
+
 ### Budgets & alerts
 
 Set a monthly budget in the dashboard (or `POST /v1/settings`). At 80% and 100% TokenWatch fires your webhook; at 100% `enforceBudget: true` makes wrapped calls throw `BudgetExceededError` instead of burning money.

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './suppress-warnings.js';

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
+import './suppress-warnings.js';
 import { mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { startServer } from './server.js';
+import { startWatch } from './watch.js';
 const args = process.argv.slice(2);
 const wantsHelp = args.includes('--help') || args.includes('-h');
 const command = wantsHelp ? 'help' : args[0] && !args[0].startsWith('-') ? args[0] : 'serve';
@@ -10,18 +12,43 @@ function flag(name) {
     const i = args.indexOf(`--${name}`);
     return i >= 0 ? args[i + 1] : undefined;
 }
+const has = (name) => args.includes(`--${name}`);
 if (command === 'serve') {
     const port = Number(flag('port') ?? process.env.TOKENWATCH_PORT ?? process.env.PORT ?? 4318);
     const dbPath = flag('db') ?? process.env.TOKENWATCH_DB ?? join(homedir(), '.tokenwatch', 'tokenwatch.db');
     mkdirSync(dirname(dbPath), { recursive: true });
     startServer({ port, dbPath });
+    if (has('watch')) {
+        void startWatch({
+            endpoint: `http://localhost:${port}`,
+            apiKey: process.env.TOKENWATCH_API_KEY,
+            backfill: has('backfill'),
+            once: false,
+            intervalMs: Number(flag('interval') ?? 5000),
+        });
+    }
+}
+else if (command === 'watch') {
+    void startWatch({
+        endpoint: (flag('endpoint') ?? process.env.TOKENWATCH_URL ?? 'http://localhost:4318').replace(/\/$/, ''),
+        apiKey: process.env.TOKENWATCH_API_KEY,
+        backfill: has('backfill'),
+        once: has('once'),
+        intervalMs: Number(flag('interval') ?? 5000),
+    });
 }
 else {
     console.log(`tokenwatch — LLM cost & quality monitor
 
 Usage:
-  tokenwatch serve [--port 4318] [--db ~/.tokenwatch/tokenwatch.db]
+  tokenwatch serve [--port 4318] [--db ~/.tokenwatch/tokenwatch.db] [--watch] [--backfill]
+  tokenwatch watch [--endpoint http://localhost:4318] [--backfill] [--once] [--interval 5000]
+
+watch ingests usage from coding-agent session logs (read-only, no proxy):
+  Claude Code  ~/.claude/projects/**/*.jsonl
+  Codex CLI    ~/.codex/sessions/**/*.jsonl
+--backfill processes existing history; default tracks new usage only.
 
 Env:
-  TOKENWATCH_PORT, TOKENWATCH_DB, TOKENWATCH_API_KEY (require bearer auth for ingestion)`);
+  TOKENWATCH_PORT, TOKENWATCH_DB, TOKENWATCH_URL, TOKENWATCH_API_KEY`);
 }

package/dist/server.d.ts

@@ -1,8 +1,7 @@
 import { Hono } from 'hono';
-import { DatabaseSync } from 'node:sqlite';
 export declare function createApp(dbPath: string): {
     app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-    db: DatabaseSync;
+    db: import("node:sqlite").DatabaseSync;
 };
 export declare function startServer(opts: {
     port: number;

package/dist/server.js

@@ -1,8 +1,11 @@
 import { Hono } from 'hono';
 import { serve } from '@hono/node-server';
-import { DatabaseSync } from 'node:sqlite';
+import { createRequire } from 'node:module';
 import { computeCostUsd } from './pricing.js';
 import { dashboardHtml } from './dashboard.js';
+// Lazy-require node:sqlite so its ExperimentalWarning fires after our suppressor
+// (static `import 'node:sqlite'` emits the warning during module linking).
+const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS events (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -167,6 +170,15 @@ export function createApp(dbPath) {
 export function startServer(opts) {
     const { app } = createApp(opts.dbPath);
     const server = serve({ fetch: app.fetch, port: opts.port });
+    server.on?.('error', (err) => {
+        if (err?.code === 'EADDRINUSE') {
+            console.error(`\nTokenWatch: port ${opts.port} is already in use.\n` +
+                `Probably another TokenWatch is running — open http://localhost:${opts.port} to check,\n` +
+                `or start on a different port:  tokenwatch serve --port ${opts.port + 1}\n`);
+            process.exit(1);
+        }
+        throw err;
+    });
     console.log(`TokenWatch running → http://localhost:${opts.port}  (db: ${opts.dbPath})`);
     return server;
 }

package/dist/suppress-warnings.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/suppress-warnings.js

@@ -0,0 +1,10 @@
+// Must be imported before any module that loads node:sqlite.
+// node:sqlite is stable for our use; hide the scary first-run ExperimentalWarning.
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+    const text = typeof warning === 'string' ? warning : warning?.message ?? '';
+    if (text.includes('SQLite is an experimental feature'))
+        return;
+    originalEmitWarning(warning, ...rest);
+});
+export {};

package/dist/watch.d.ts

@@ -0,0 +1,9 @@
+export interface WatchOptions {
+    endpoint: string;
+    apiKey?: string;
+    backfill: boolean;
+    once: boolean;
+    intervalMs: number;
+    statePath?: string;
+}
+export declare function startWatch(opts: WatchOptions): Promise<void>;

package/dist/watch.js

@@ -0,0 +1,222 @@
+/**
+ * `tokenwatch watch` — ingest usage from coding-agent session logs (read-only).
+ * Supported: Claude Code (~/.claude/projects), OpenAI Codex CLI (~/.codex/sessions).
+ * No proxy, no config inside the agents: we tail their JSONL transcripts.
+ */
+import { readdirSync, statSync, openSync, readSync, closeSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname, relative, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { findPrice } from './pricing.js';
+const seen = new Set();
+function parseClaudeLine(line, ctx) {
+    if (!line.includes('"assistant"') || !line.includes('"usage"'))
+        return null;
+    let o;
+    try {
+        o = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (o?.type !== 'assistant')
+        return null;
+    const m = o.message;
+    const u = m?.usage;
+    if (!u)
+        return null;
+    const id = m.id ?? o.uuid;
+    if (id) {
+        if (seen.has(id))
+            return null;
+        seen.add(id);
+    }
+    const model = m.model ?? 'unknown';
+    if (model.includes('synthetic'))
+        return null;
+    const p = findPrice(model);
+    const inT = u.input_tokens || 0;
+    const outT = u.output_tokens || 0;
+    const cacheRead = u.cache_read_input_tokens || 0;
+    const cc5 = u.cache_creation ? (u.cache_creation.ephemeral_5m_input_tokens || 0) : (u.cache_creation_input_tokens || 0);
+    const cc1 = u.cache_creation ? (u.cache_creation.ephemeral_1h_input_tokens || 0) : 0;
+    // Anthropic cache pricing: read 0.1x, 5m write 1.25x, 1h write 2x of input price.
+    const costUsd = p ? (inT * p.input + outT * p.output + cacheRead * p.input * 0.1 + cc5 * p.input * 1.25 + cc1 * p.input * 2) / 1e6 : 0;
+    return {
+        ts: o.timestamp ? Date.parse(o.timestamp) : Date.now(),
+        model,
+        provider: 'anthropic',
+        inputTokens: inT + cacheRead + cc5 + cc1,
+        outputTokens: outT,
+        costUsd,
+        feature: 'claude-code',
+        customerId: ctx.project,
+    };
+}
+function parseCodexLine(line, ctx) {
+    if (!line.includes('"model"') && !line.includes('token_count') && !line.includes('"cwd"'))
+        return null;
+    let o;
+    try {
+        o = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const pl = o?.payload;
+    if (!pl)
+        return null;
+    if (typeof pl.model === 'string' && pl.model)
+        ctx.model = pl.model;
+    if (typeof pl.cwd === 'string' && pl.cwd)
+        ctx.cwd = basename(pl.cwd);
+    if (pl.type !== 'token_count')
+        return null;
+    const u = pl.info?.last_token_usage;
+    if (!u)
+        return null;
+    const inT = u.input_tokens || 0;
+    const cached = u.cached_input_tokens || 0;
+    const outT = u.output_tokens || 0;
+    if (!inT && !outT)
+        return null;
+    const model = ctx.model ?? 'gpt-5.5';
+    const p = findPrice(model);
+    // OpenAI cached input is ~0.1x of input price; cached is a subset of input_tokens.
+    const costUsd = p ? Math.max(0, ((inT - cached) * p.input + cached * p.input * 0.1 + outT * p.output) / 1e6) : 0;
+    return {
+        ts: o.timestamp ? Date.parse(o.timestamp) : Date.now(),
+        model,
+        provider: 'openai',
+        inputTokens: inT,
+        outputTokens: outT,
+        costUsd,
+        feature: 'codex',
+        customerId: ctx.cwd,
+    };
+}
+const SOURCES = [
+    { name: 'claude-code', root: join(homedir(), '.claude', 'projects'), parse: parseClaudeLine, projectFromPath: true },
+    { name: 'codex', root: join(homedir(), '.codex', 'sessions'), parse: parseCodexLine, projectFromPath: false },
+];
+function* findJsonl(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            yield* findJsonl(p);
+        else if (e.name.endsWith('.jsonl'))
+            yield p;
+    }
+}
+export async function startWatch(opts) {
+    const statePath = opts.statePath ?? join(homedir(), '.tokenwatch', 'watch-state.json');
+    mkdirSync(dirname(statePath), { recursive: true });
+    let state = { offsets: {}, seen: [] };
+    if (existsSync(statePath)) {
+        try {
+            state = JSON.parse(readFileSync(statePath, 'utf8'));
+        }
+        catch { /* fresh start */ }
+    }
+    for (const id of state.seen)
+        seen.add(id);
+    const ctxByFile = new Map();
+    const active = SOURCES.filter((s) => existsSync(s.root));
+    if (active.length === 0) {
+        console.error('tokenwatch watch: no supported agent logs found (~/.claude/projects, ~/.codex/sessions)');
+        return;
+    }
+    console.log(`watching: ${active.map((s) => s.name).join(', ')}  →  ${opts.endpoint}${opts.backfill ? '  (backfill)' : ''}`);
+    const scan = async () => {
+        const events = [];
+        for (const src of active) {
+            for (const file of findJsonl(src.root)) {
+                let size;
+                try {
+                    size = statSync(file).size;
+                }
+                catch {
+                    continue;
+                }
+                let offset = state.offsets[file];
+                if (offset === undefined) {
+                    offset = opts.backfill ? 0 : size;
+                    state.offsets[file] = offset;
+                    if (offset === size)
+                        continue;
+                }
+                if (size <= offset)
+                    continue;
+                let ctx = ctxByFile.get(file);
+                if (!ctx) {
+                    ctx = { project: src.projectFromPath ? relative(src.root, file).split(sep)[0] : undefined };
+                    ctxByFile.set(file, ctx);
+                    // When starting mid-file, recover per-file context (model/cwd) from the head.
+                    if (offset > 0 && src.name === 'codex') {
+                        try {
+                            const headFd = openSync(file, 'r');
+                            const head = Buffer.alloc(Math.min(65536, size));
+                            readSync(headFd, head, 0, head.length, 0);
+                            closeSync(headFd);
+                            for (const l of head.toString('utf8').split('\n').slice(0, 80))
+                                src.parse(l, ctx);
+                        }
+                        catch { /* best effort */ }
+                    }
+                }
+                let text;
+                try {
+                    const fd = openSync(file, 'r');
+                    const buf = Buffer.alloc(size - offset);
+                    readSync(fd, buf, 0, buf.length, offset);
+                    closeSync(fd);
+                    text = buf.toString('utf8');
+                }
+                catch {
+                    continue;
+                }
+                const lastNl = text.lastIndexOf('\n');
+                if (lastNl === -1)
+                    continue;
+                for (const line of text.slice(0, lastNl).split('\n')) {
+                    const ev = src.parse(line, ctx);
+                    if (ev)
+                        events.push(ev);
+                }
+                state.offsets[file] = offset + Buffer.byteLength(text.slice(0, lastNl + 1), 'utf8');
+            }
+        }
+        if (events.length > 0) {
+            const headers = { 'content-type': 'application/json' };
+            if (opts.apiKey)
+                headers.authorization = `Bearer ${opts.apiKey}`;
+            for (let i = 0; i < events.length; i += 500) {
+                const res = await fetch(`${opts.endpoint}/v1/events`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({ events: events.slice(i, i + 500) }),
+                });
+                if (!res.ok)
+                    throw new Error(`ingest failed: HTTP ${res.status}`);
+            }
+            const total = events.reduce((s, e) => s + e.costUsd, 0);
+            console.log(`+${events.length} events ($${total.toFixed(2)} API-value) ingested`);
+        }
+        state.seen = [...seen].slice(-20000);
+        writeFileSync(statePath, JSON.stringify(state));
+    };
+    await scan();
+    if (!opts.once) {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            await new Promise((r) => setTimeout(r, opts.intervalMs));
+            await scan().catch((err) => console.error('tokenwatch watch:', err?.message ?? err));
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenwatch-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Zero-config LLM cost & quality monitor for indie AI builders. One-line SDK, local dashboard, budget kill-switch.",
   "type": "module",
   "license": "MIT",