limitcast 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,11 +11,11 @@ Every Claude Code session starts at 102.7k tokens before your first message.
11
11
  - Hide 66 skills from the model (~5.3k): dataviz, block-kit, ...
12
12
  ```
13
13
 
14
- - **Trim advisor (Pro):** measures your latest session's starting context from its transcript (SessionStart hook output, MCP server instructions and tool names, skills, agents, instruction files) and names what you haven't used, with what each costs.
14
+ - **Trim advisor:** measures your latest session's starting context from its transcript (SessionStart hook output, MCP server instructions and tool names, skills, agents, instruction files). Free shows the total and how much of it you haven't used; Pro names each item and what it costs.
15
15
  - **Subagent guard (Pro)** for Claude Code and Codex: blocks a new subagent when that tool's own window is on pace to run out before it resets.
16
16
  - **Burn report (Pro):** Claude Code, Codex and Grok tokens by day, project, model and session.
17
17
  - **Runout forecast (free):** burn rate and the clock time each window runs out.
18
- - **Local only.** Reads the limit readings Claude Code passes to your status line and the logs Claude Code, Codex and Grok already write. No API calls, no logins, nothing leaves your machine.
18
+ - **Local only.** Reads the limit readings Claude Code passes to your status line and the logs Claude Code, Codex and Grok already write. No logins, and your usage data never leaves your machine. The free tier makes no network calls; a Pro license key talks to Polar only to activate, to re-check weekly, and to deactivate (it sends the key and your computer's name).
19
19
 
20
20
  | | Claude Code | Codex | Grok |
21
21
  |---|---|---|---|
@@ -50,11 +50,12 @@ limitcast doctor
50
50
  | `limitcast install [--guard] [--alerts]` / `uninstall` | Wire into Claude Code / restore your settings |
51
51
  | `limitcast doctor` | Check the setup, data freshness, license, and that Claude Code, Codex and Grok logs are still in a format limitcast reads |
52
52
  | `limitcast report [--days N] [--out FILE]` | **Pro.** Tokens by tool, day, project, model and session; subagent share |
53
- | `limitcast trim [--days N] [--share]` | **Pro.** Measured starting context of your latest session and what you haven't used in N days (default 7). `--share`: totals only, no names, safe to post |
53
+ | `limitcast trim [--days N] [--share]` | Measured starting context of your latest session and how much you haven't used in N days (default 7). **Pro** names each item. `--share`: totals only, no names, safe to post |
54
54
  | `limitcast saved` | **Pro.** How much the part of your starting context you control has dropped since limitcast first measured it, times your sessions since |
55
55
  | `install --alerts` | **Pro.** A SessionStart hook that tells you (never the model) when your starting context grew ~1k+ tokens, and what grew |
56
- | `limitcast activate <key>` | Unlock Pro: registers this computer with Polar once (3 computers per key), then works offline |
56
+ | `limitcast activate <key>` | Unlock Pro: registers this computer with Polar (3 computers per key). Polar re-checks it weekly in the background; it keeps working up to 30 days offline |
57
57
  | `limitcast deactivate` | Free this computer so the key can be used on another one |
58
+ | `limitcast license` | Show the license and re-check it with Polar now |
58
59
 
59
60
  ### Subagent guard (Pro)
60
61
 
@@ -66,7 +67,7 @@ Each limit reading is saved to `~/.local/state/limitcast/samples.jsonl` when it
66
67
 
67
68
  ## Pricing
68
69
 
69
- Free: runout forecast and status-line readout. Pro ($79/year, or $149 lifetime for the first 100 buyers): trim advisor, subagent guard, burn report. See https://limitcast.dev.
70
+ Free: runout forecast, status-line readout, and your starting-context total with how much you never use. Pro ($79/year, or $149 lifetime): names what to cut, subagent guard, burn report, starting-context alerts. 14-day refund: email support@limitcast.dev. See https://limitcast.dev.
70
71
 
71
72
  ## License
72
73
 
package/bin/limitcast.mjs CHANGED
@@ -1,21 +1,22 @@
1
1
  #!/usr/bin/env node
2
2
  // @ts-check
3
- import { spawnSync } from 'node:child_process';
3
+ import { spawn, spawnSync } from 'node:child_process';
4
4
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
5
5
  import { join } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
6
7
  import { forecastAll, oneClaudeSession } from '../src/forecast.mjs';
7
- import { claudeSamples, readCodex } from '../src/sources.mjs';
8
- import { KEEP_MS, load, record, stateDir } from '../src/store.mjs';
8
+ import { formatChecks } from '../src/formats.mjs';
9
9
  import { runGuard } from '../src/guard.mjs';
10
- import { claudeRoot, grokRoot, readUsage } from '../src/usage.mjs';
10
+ import { doctor, install, uninstall } from '../src/install.mjs';
11
+ import { activate, currentLicense, isPro, UPGRADE_URL } from '../src/license.mjs';
12
+ import { driftMessage, loadOverhead, recordOverhead, savedSummary, snapshot } from '../src/overhead.mjs';
13
+ import { activatePolar, deactivatePolar, refreshDue, refreshPolar } from '../src/polar.mjs';
11
14
  import { burnReport } from '../src/report.mjs';
12
- import { baseline, contributors, shareSummary, startupReport, trimReport } from '../src/trim.mjs';
15
+ import { claudeSamples, readCodex } from '../src/sources.mjs';
13
16
  import { countInteractiveSince, latestInteractiveTranscript } from '../src/startup.mjs';
14
- import { driftMessage, loadOverhead, recordOverhead, savedSummary, snapshot } from '../src/overhead.mjs';
15
- import { formatChecks } from '../src/formats.mjs';
16
- import { activate, currentLicense, isPro, UPGRADE_URL } from '../src/license.mjs';
17
- import { activatePolar, deactivatePolar, refreshPolar } from '../src/polar.mjs';
18
- import { doctor, install, uninstall } from '../src/install.mjs';
17
+ import { KEEP_MS, load, record, stateDir } from '../src/store.mjs';
18
+ import { baseline, contributors, shareSummary, startupReport, trimReport } from '../src/trim.mjs';
19
+ import { claudeRoot, grokRoot, readUsage } from '../src/usage.mjs';
19
20
 
20
21
  const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
21
22
  const HELP = `limitcast ${VERSION}: stretch your Claude Code and Codex plans
@@ -24,15 +25,17 @@ const HELP = `limitcast ${VERSION}: stretch your Claude Code and Codex plans
24
25
  limitcast uninstall remove it and restore your original status line
25
26
  limitcast doctor check the setup
26
27
  limitcast status [--json] used, burn rate, runout time and reset per limit window
28
+ limitcast trim [--share] tokens every session loads before you type, and how much you never use
29
+ limitcast license show the license and re-check it with Polar
27
30
 
28
31
  Pro (${UPGRADE_URL})
29
- limitcast trim [--days N] [--share] tokens every session loads before you type, and what to cut
32
+ limitcast trim [--days N] [--share] names what to cut and what each costs
30
33
  (--share: totals only, no names, safe to post)
31
34
  limitcast saved tokens saved since limitcast first measured you
32
35
  limitcast install --guard block new subagents when a window is on pace to run out
33
36
  limitcast install --alerts tell you when your starting context grows
34
37
  limitcast report [--days N] [--out FILE] tokens by tool, day, project, model and session
35
- limitcast activate <license-key> unlock Pro on this computer (once online, then works offline)
38
+ limitcast activate <license-key> unlock Pro on this computer (online once; then a weekly check, offline up to 30 days)
36
39
  limitcast deactivate free this computer's activation to use the key elsewhere
37
40
 
38
41
  Used by Claude Code and Codex (set up by install)
@@ -69,6 +72,8 @@ if (cmd === 'status') {
69
72
  sid = feed?.session_id;
70
73
  record(claudeSamples(feed, now));
71
74
  saveFeedShape(feed);
75
+ // Hook-only Pro users never run an interactive command, so the weekly Polar check starts here, detached.
76
+ if (refreshDue(now)) spawn(process.execPath, [fileURLToPath(import.meta.url), 'license'], { detached: true, stdio: 'ignore' }).unref();
72
77
  } catch {
73
78
  /* never break the status line */
74
79
  }
@@ -116,7 +121,8 @@ if (cmd === 'status') {
116
121
  for (const c of checks) console.log(`${c.ok ? '✓' : '✗'} ${c.line}`);
117
122
  process.exit(checks.every((c) => c.ok) ? 0 : 1);
118
123
  } else if (cmd === 'report' || cmd === 'trim') {
119
- if (!isPro()) {
124
+ const pro = isPro();
125
+ if (!pro && cmd === 'report') {
120
126
  console.log(`\`limitcast ${cmd}\` is part of limitcast Pro: ${UPGRADE_URL}\nAlready bought it? limitcast activate <license-key>`);
121
127
  process.exit(2);
122
128
  }
@@ -130,12 +136,19 @@ if (cmd === 'status') {
130
136
  // Prefer the measured starting context of the latest interactive session; older Claude Code logs fall back to estimates.
131
137
  const latest = await latestInteractiveTranscript(claudeRoot());
132
138
  if (latest) recordOverhead(snapshot(latest));
133
- if (latest && args.includes('--share')) text = shareSummary(baseline(usage), latest, used, days());
139
+ // Free: the measured totals without names (the --share view); Pro names what to cut.
140
+ if (!pro && !latest) {
141
+ console.log(`\`limitcast trim\` needs one Claude Code session first. Naming what to cut is Pro: ${UPGRADE_URL}`);
142
+ process.exit(2);
143
+ }
144
+ if (latest && (args.includes('--share') || !pro)) text = shareSummary(baseline(usage), latest, used, days());
134
145
  else text = latest ? startupReport(baseline(usage), latest, used, days()) : trimReport(baseline(usage), contributors(), used, days());
146
+ if (!pro)
147
+ text += `\n\nPro names each item and what it costs, so you can cut it: ${UPGRADE_URL}\nAlready bought it? limitcast activate <license-key>`;
135
148
  }
136
149
  const out = flag('--out');
137
150
  if (out) {
138
- writeFileSync(out, text + '\n');
151
+ writeFileSync(out, `${text}\n`);
139
152
  console.log(`Wrote ${out}`);
140
153
  } else console.log(text);
141
154
  } else if (cmd === 'drift') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "limitcast",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Stretch your Claude Code plan: measure what every session loads before you type, cut what you never use, and stop runaway subagents before they burn your window.",
5
5
  "type": "module",
6
6
  "bin": { "limitcast": "bin/limitcast.mjs" },
package/src/formats.mjs CHANGED
@@ -1,9 +1,9 @@
1
1
  // @ts-check
2
2
  import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
- import { createInterface } from 'node:readline';
4
3
  import { join } from 'node:path';
5
- import { claudeRoot, codexRoot, grokRoot } from './usage.mjs';
4
+ import { createInterface } from 'node:readline';
6
5
  import { stateDir } from './store.mjs';
6
+ import { claudeRoot, codexRoot, grokRoot } from './usage.mjs';
7
7
 
8
8
  /**
9
9
  * limitcast reads Claude Code's, Codex's and Grok's own log formats, which can change in any release.
package/src/install.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // @ts-check
2
2
  import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
3
- import { join } from 'node:path';
4
3
  import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
 
7
7
  export const settingsPath = () => join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'settings.json');
@@ -152,7 +152,7 @@ export function readSettings(path) {
152
152
  /** @param {string} path @param {any} cfg */
153
153
  function writeSettings(path, cfg) {
154
154
  mkdirSync(join(path, '..'), { recursive: true });
155
- writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n');
155
+ writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
156
156
  }
157
157
 
158
158
  /** @param {string} path */
@@ -208,7 +208,7 @@ export function doctor({ path = settingsPath(), codexPath = codexHooksPath(), sa
208
208
  });
209
209
  const exe = sl.match(/^'([^']+)'|^(\S+)/);
210
210
  const exePath = exe?.[1] ?? exe?.[2];
211
- if (sl.includes(MARK) && exePath && exePath.startsWith('/')) {
211
+ if (sl.includes(MARK) && exePath?.startsWith('/')) {
212
212
  out.push({
213
213
  ok: existsSync(exePath),
214
214
  line: existsSync(exePath) ? 'Node path in settings exists' : `Node path in settings is gone (${exePath}): run \`limitcast install\` again`,
@@ -227,12 +227,15 @@ export function doctor({ path = settingsPath(), codexPath = codexHooksPath(), sa
227
227
  );
228
228
  out.push({
229
229
  ok: license?.ok !== false,
230
- line:
231
- license === null
232
- ? 'Free tier'
233
- : license.ok
234
- ? `Pro: ${license.claims.e}${license.claims.x ? `, renews ${new Date(license.claims.x * 1000).toISOString().slice(0, 10)}` : ', lifetime'}`
235
- : `License problem: ${license.reason}`,
230
+ line: license === null ? 'Free tier' : license.ok ? `Pro: ${license.claims.e}${proTerm(license.claims)}` : `License problem: ${license.reason}`,
236
231
  });
237
232
  return out;
238
233
  }
234
+
235
+ /** @param {{p:string, i:number, x:number}} c */
236
+ function proTerm(c) {
237
+ const day = (/** @type {number} */ s) => new Date(s * 1000).toISOString().slice(0, 10);
238
+ if (c.x) return `, ${c.p === 'polar' ? 'valid until' : 'renews'} ${day(c.x)}`;
239
+ // A Polar key has no end date for Lifetime or an active subscription; the weekly check is what keeps it honest.
240
+ return c.p === 'polar' ? `, last checked with Polar ${day(c.i)}` : ', lifetime';
241
+ }
package/src/license.mjs CHANGED
@@ -1,9 +1,9 @@
1
1
  // @ts-check
2
- import { createPublicKey, createPrivateKey, sign, verify } from 'node:crypto';
2
+ import { createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
3
3
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
4
  import { join } from 'node:path';
5
- import { stateDir } from './store.mjs';
6
5
  import { loadPolar, polarStatus } from './polar.mjs';
6
+ import { stateDir } from './store.mjs';
7
7
 
8
8
  export const UPGRADE_URL = 'https://limitcast.dev/#pricing';
9
9
  const PUBLIC_KEY = 'MCowBQYDK2VwAyEAG+4c5uaNB7IAZiAxtcyyXBEmmRkmZfWvlEFyvhmDQvA=';
@@ -63,7 +63,7 @@ export function activate(key) {
63
63
  const res = checkLicense(key, Date.now());
64
64
  if (res.ok) {
65
65
  mkdirSync(stateDir(), { recursive: true });
66
- writeFileSync(licenseFile(), key.trim() + '\n', { mode: 0o600 });
66
+ writeFileSync(licenseFile(), `${key.trim()}\n`, { mode: 0o600 });
67
67
  }
68
68
  return res;
69
69
  }
package/src/polar.mjs CHANGED
@@ -41,7 +41,28 @@ export function polarStatus(l, now) {
41
41
  if (exp && exp < now) return { ok: false, reason: `expired ${new Date(exp).toISOString().slice(0, 10)}` };
42
42
  if (now - l.checkedAt > GRACE_MS)
43
43
  return { ok: false, reason: 'not checked with Polar for 30 days: connect to the internet and run `limitcast license`' };
44
- return { ok: true, claims: { e: l.email, p: 'pro', i: Math.floor(l.checkedAt / 1000), x: exp ? Math.floor(exp / 1000) : 0 } };
44
+ // p 'polar': i is the last successful check, and x is 0 for both Lifetime and an active subscription.
45
+ return { ok: true, claims: { e: l.email, p: 'polar', i: Math.floor(l.checkedAt / 1000), x: exp ? Math.floor(exp / 1000) : 0 } };
46
+ }
47
+
48
+ /**
49
+ * Hooks never touch the network, so the status line asks this before starting a detached re-check.
50
+ * True when the weekly re-check is due and no attempt was made in the last hour (offline or rate-limited).
51
+ * @param {number} now
52
+ */
53
+ export function refreshDue(now) {
54
+ const l = loadPolar();
55
+ if (!l || now - l.checkedAt < RECHECK_MS) return false;
56
+ const mark = join(stateDir(), 'polar-refresh.at');
57
+ let last = 0;
58
+ try {
59
+ last = Number(readFileSync(mark, 'utf8')) || 0;
60
+ } catch {
61
+ /* never attempted */
62
+ }
63
+ if (Math.abs(now - last) < 3600_000) return false;
64
+ writeFileSync(mark, String(now));
65
+ return true;
45
66
  }
46
67
 
47
68
  /**
@@ -66,6 +87,7 @@ async function post(path, body, fetchImpl) {
66
87
 
67
88
  /** @param {any} data */
68
89
  const detail = (data) => (typeof data?.detail === 'string' ? data.detail : '');
90
+ const BUSY = 'Polar is rate-limiting requests: wait a minute and try again';
69
91
 
70
92
  /**
71
93
  * Register this machine with Polar and store the result for offline use.
@@ -81,6 +103,7 @@ export async function activatePolar(key, { fetchImpl = fetch, now = Date.now(),
81
103
  return { ok: false, reason: `could not reach Polar (${e instanceof Error ? e.message : e}); activation needs the internet once` };
82
104
  }
83
105
  if (r.status === 404) return { ok: false, reason: 'Polar does not know this license key' };
106
+ if (r.status === 429) return { ok: false, reason: BUSY };
84
107
  if (r.status === 403)
85
108
  return {
86
109
  ok: false,
@@ -138,6 +161,7 @@ export async function deactivatePolar({ fetchImpl = fetch } = {}) {
138
161
  } catch (e) {
139
162
  return { ok: false, reason: `could not reach Polar (${e instanceof Error ? e.message : e})` };
140
163
  }
164
+ if (r.status === 429) return { ok: false, reason: BUSY };
141
165
  if (r.status !== 204 && r.status !== 200 && r.status !== 404)
142
166
  return { ok: false, reason: `Polar returned ${r.status}${detail(r.data) ? `: ${detail(r.data)}` : ''}` };
143
167
  if (existsSync(file())) rmSync(file());
package/src/sources.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  // @ts-check
2
2
  import { createReadStream, existsSync, readdirSync, statSync } from 'node:fs';
3
- import { createInterface } from 'node:readline';
4
- import { join } from 'node:path';
5
3
  import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ import { createInterface } from 'node:readline';
6
6
  import { windowName } from './forecast.mjs';
7
7
 
8
8
  /** @typedef {import('./forecast.mjs').Sample} Sample */
package/src/startup.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // @ts-check
2
2
  import { createReadStream, readdirSync, statSync } from 'node:fs';
3
- import { createInterface } from 'node:readline';
4
3
  import { join } from 'node:path';
4
+ import { createInterface } from 'node:readline';
5
5
 
6
6
  /**
7
7
  * One piece of the context Claude Code loads before your first message, measured from the transcript.
package/src/store.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // @ts-check
2
2
  import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
3
- import { join } from 'node:path';
4
3
  import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
5
 
6
6
  /** @typedef {import('./forecast.mjs').Sample} Sample */
7
7
 
@@ -36,14 +36,14 @@ export function record(samples) {
36
36
  });
37
37
  if (!fresh.length) return;
38
38
  const file = join(dir, 'samples.jsonl');
39
- appendFileSync(file, fresh.map((s) => JSON.stringify(s)).join('\n') + '\n');
39
+ appendFileSync(file, `${fresh.map((s) => JSON.stringify(s)).join('\n')}\n`);
40
40
  for (const s of fresh) last[key(s)] = { pct: s.pct, reset: s.reset };
41
41
  writeFileSync(lastPath, JSON.stringify(last));
42
42
  if (statSync(file).size > PRUNE_BYTES)
43
43
  writeFileSync(
44
44
  file,
45
45
  load(Date.now() - KEEP_MS)
46
- .map((s) => JSON.stringify(s) + '\n')
46
+ .map((s) => `${JSON.stringify(s)}\n`)
47
47
  .join(''),
48
48
  );
49
49
  }
package/src/trim.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // @ts-check
2
2
  import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
- import { join } from 'node:path';
4
3
  import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
5
  import { fmt } from './report.mjs';
6
6
 
7
7
  /** @typedef {import('./usage.mjs').Usage} Usage */
package/src/usage.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  // @ts-check
2
2
  import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
- import { createInterface } from 'node:readline';
4
- import { basename, join } from 'node:path';
5
3
  import { homedir } from 'node:os';
4
+ import { basename, join } from 'node:path';
5
+ import { createInterface } from 'node:readline';
6
6
 
7
7
  /**
8
8
  * One model response's token usage.