limitcast 0.17.3 → 0.18.1

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/src/trim.mjs CHANGED
@@ -140,12 +140,21 @@ export function savings(c, used) {
140
140
  * @param {ReturnType<typeof contributors>} c
141
141
  * @param {Activity} used
142
142
  * @param {number} days
143
+ * @param {boolean} [share] totals only, including when no startup transcript is available
143
144
  */
144
- export function trimReport(base, c, used, days) {
145
+ export function trimReport(base, c, used, days, share = false) {
145
146
  const s = savings(c, used);
146
147
  const fileTokens = c.files.reduce((a, f) => a + f.tokens, 0);
147
148
  const visible = c.skills.filter((k) => !k.hidden);
148
149
  const listing = visible.reduce((a, k) => a + k.tokens, 0);
150
+ if (share)
151
+ return [
152
+ base ? `Claude starting context: ${fmt(base.median)} tokens across ${base.sessions} sessions.` : 'Claude starting context: unavailable.',
153
+ `Estimated removable skill listings: ~${fmt(s.skillTokens)} tokens per session.`,
154
+ `Unused in ${days} days: ${s.unusedSkills.length} skills, ${s.unusedMcp.length} MCP servers (server sizes unavailable).`,
155
+ `Instruction files: ${c.files.length}, ~${fmt(fileTokens)} tokens. Visible skill listings: ~${fmt(listing)} tokens.`,
156
+ 'Totals only; no configuration names or paths. https://limitcast.dev',
157
+ ].join('\n');
149
158
  const lines = ['# limitcast trim', ''];
150
159
  if (base) {
151
160
  lines.push(
@@ -198,9 +207,11 @@ const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
198
207
  * @param {import('./startup.mjs').Piece[]} pieces
199
208
  * @param {Activity} used
200
209
  * @param {string[]} [keep] the `trim keep` list: unused, but never counted as a cut; named in `kept`
210
+ * @param {Activity|null} [usedMonth] servers used in 30 days. When set, only servers missing here are removable.
201
211
  */
202
- export function measuredSavings(pieces, used, keep = []) {
212
+ export function measuredSavings(pieces, used, keep = [], usedMonth = null) {
203
213
  const usedMcp = new Set([...used.mcp].map(norm));
214
+ const month = usedMonth ? new Set([...usedMonth.mcp].map(norm)) : null;
204
215
  // Instructions and tool names spell a server differently ("claude.ai Postman" / "claude_ai_Postman"): merge by normalized name.
205
216
  /** @type {Map<string, {name:string, chars:number}>} */
206
217
  const mcp = new Map();
@@ -217,9 +228,11 @@ export function measuredSavings(pieces, used, keep = []) {
217
228
  const kept = [...mcp.values(), ...skills].filter((x) => keep.some((k) => norm(k) === norm(x.name))).map((x) => x.name);
218
229
  const isKept = (/** @type {{name:string}} */ x) => kept.includes(x.name);
219
230
  const unusedMcp = [...mcp.values()].filter((m) => !isKept(m)).sort((a, b) => b.chars - a.chars);
231
+ const standingMcp = month ? unusedMcp.filter((m) => month.has(norm(m.name))) : [];
232
+ const staleMcp = month ? unusedMcp.filter((m) => !month.has(norm(m.name))) : unusedMcp;
220
233
  const unusedSkills = skills.filter((s) => !isKept(s));
221
- const chars = unusedMcp.reduce((a, m) => a + m.chars, 0) + unusedSkills.reduce((a, s) => a + s.chars, 0);
222
- return { unusedMcp, unusedSkills, tokens: tok(chars), kept };
234
+ const chars = staleMcp.reduce((a, m) => a + m.chars, 0) + unusedSkills.reduce((a, s) => a + s.chars, 0);
235
+ return { unusedMcp, standingMcp, staleMcp, unusedSkills, tokens: tok(chars), kept };
223
236
  }
224
237
 
225
238
  /**
@@ -229,9 +242,10 @@ export function measuredSavings(pieces, used, keep = []) {
229
242
  * @param {Activity} used
230
243
  * @param {number} days
231
244
  * @param {string[]} [keep] the `trim keep` list
245
+ * @param {Activity|null} [usedMonth] servers used in 30 days; `--apply` leaves those on
232
246
  */
233
- export function startupReport(base, b, used, days, keep = []) {
234
- const s = measuredSavings(b.pieces, used, keep);
247
+ export function startupReport(base, b, used, days, keep = [], usedMonth = null) {
248
+ const s = measuredSavings(b.pieces, used, keep, usedMonth);
235
249
  const median = base?.median ?? 0;
236
250
  const lines = ['# limitcast trim', ''];
237
251
  if (base) {
@@ -245,16 +259,27 @@ export function startupReport(base, b, used, days, keep = []) {
245
259
  lines.push(
246
260
  `## Estimated removable context: ~${fmt(s.tokens)} tokens per session${pct}`,
247
261
  '',
248
- `From things you haven't used in the last ${days} days:`,
262
+ usedMonth
263
+ ? `From skills unused in the last ${days} days and MCP servers quiet for 30 days:`
264
+ : `From things you haven't used in the last ${days} days:`,
249
265
  '',
250
266
  );
251
- if (s.unusedMcp.length) {
252
- const total = s.unusedMcp.reduce((a, m) => a + m.chars, 0);
267
+ if (s.standingMcp.length) {
268
+ lines.push(
269
+ `- **Leave on ${s.standingMcp.length} MCP servers** used in the last 30 days but not in ${days} days: ${s.standingMcp
270
+ .slice(0, 10)
271
+ .map((m) => m.name)
272
+ .join(', ')}${s.standingMcp.length > 10 ? ', ...' : ''}.`,
273
+ ' `trim --apply` does not turn these off.',
274
+ );
275
+ }
276
+ if (s.staleMcp.length) {
277
+ const total = s.staleMcp.reduce((a, m) => a + m.chars, 0);
253
278
  lines.push(
254
- `- **Disable ${s.unusedMcp.length} MCP servers** (~${fmt(tok(total))}): ${s.unusedMcp
279
+ `- **Disable ${s.staleMcp.length} MCP servers** ${usedMonth ? 'quiet for 30 days' : `you haven't used in ${days} days`} (~${fmt(tok(total))}): ${s.staleMcp
255
280
  .slice(0, 10)
256
281
  .map((m) => `${m.name} ~${fmt(tok(m.chars))}`)
257
- .join(', ')}${s.unusedMcp.length > 10 ? ', ...' : ''}.`,
282
+ .join(', ')}${s.staleMcp.length > 10 ? ', ...' : ''}.`,
258
283
  ' Their instructions and tool names load into every session. Remove them in `/mcp`, or move them to the projects that use them.',
259
284
  );
260
285
  }
@@ -306,16 +331,17 @@ export function startupReport(base, b, used, days, keep = []) {
306
331
  * @param {Activity} used
307
332
  * @param {number} days
308
333
  * @param {string[]} [keep] the `trim keep` list; only its count is shown
334
+ * @param {Activity|null} [usedMonth] servers used in 30 days
309
335
  */
310
- export function shareSummary(base, b, used, days, keep = []) {
311
- const s = measuredSavings(b.pieces, used, keep);
336
+ export function shareSummary(base, b, used, days, keep = [], usedMonth = null) {
337
+ const s = measuredSavings(b.pieces, used, keep, usedMonth);
312
338
  /** @type {Map<string, number>} */
313
339
  const groups = new Map();
314
340
  for (const p of b.pieces) groups.set(p.group, (groups.get(p.group) ?? 0) + p.chars);
315
341
  const median = base?.median ?? 0;
316
342
  const lines = [
317
343
  `My Claude Code sessions start at ${fmt(median)} tokens before I type.`,
318
- `limitcast found ~${fmt(s.tokens)} per session${median ? ` (${Math.round((s.tokens / median) * 100)}%)` : ''} I haven't used in ${days} days: ${s.unusedMcp.length} MCP servers, ${s.unusedSkills.length} skills${s.kept.length ? ` (${s.kept.length} more kept on my keep-list)` : ''}.`,
344
+ `limitcast found ~${fmt(s.tokens)} per session${median ? ` (${Math.round((s.tokens / median) * 100)}%)` : ''} I haven't used in ${days} days: ${s.unusedMcp.length} MCP servers, ${s.unusedSkills.length} skills${s.standingMcp.length ? ` (${s.standingMcp.length} of the servers were used in 30 days and stay on)` : ''}${s.kept.length ? ` (${s.kept.length} more kept on my keep-list)` : ''}.`,
319
345
  'Where it comes from:',
320
346
  ...[...groups].sort((x, y) => y[1] - x[1]).map(([g, c]) => ` ${g}: ${fmt(tok(c))}`),
321
347
  ];
package/src/value.mjs CHANGED
@@ -149,6 +149,7 @@ export function valueTotals(v) {
149
149
  return {
150
150
  since: v.since,
151
151
  sessions: sessions.length,
152
+ contributed: sessions.filter((s) => s.savedPerTurn > 0).length,
152
153
  turns: sessions.reduce((a, s) => a + s.turns, 0),
153
154
  tokens: sessions.reduce((a, s) => a + s.turns * s.savedPerTurn, 0),
154
155
  hits: hits.length,
@@ -197,15 +198,28 @@ export function valuePeriod(v, since, until) {
197
198
  /**
198
199
  * The "since you installed" section at the top of `limitcast results`.
199
200
  * @param {ReturnType<typeof valueTotals>} t
200
- * @param {{now:number, pro:boolean}} o
201
+ * @param {{now:number, pro:boolean, start?:{first:number, last:number}|null}} o
202
+ * start: controllable starting context, in characters, the first time it was measured and now
201
203
  */
202
- export function valueSection(t, { now, pro }) {
204
+ export function valueSection(t, { now, pro, start = null }) {
203
205
  if (!t.since) return '';
204
206
  const days = Math.max(1, Math.round((now - t.since) / 86400_000));
205
207
  const out = [`## Since limitcast started watching (${new Date(t.since).toLocaleDateString()}, ${days} day${days === 1 ? '' : 's'})`];
208
+ if (start) {
209
+ const from = Math.round(start.first / 4);
210
+ const to = Math.round(start.last / 4);
211
+ const delta = to - from;
212
+ const change = delta === 0 ? 'no change' : `${delta > 0 ? '+' : '-'}${fmtBig(Math.abs(delta))}`;
213
+ out.push(`- The part of your starting context you control went from ~${fmtBig(from)} to ~${fmtBig(to)} tokens (${change}).`);
214
+ }
206
215
  if (pro && t.tokens > 0) {
216
+ const rest = Number.isFinite(t.contributed) ? t.sessions - t.contributed : null;
217
+ const who =
218
+ rest === null
219
+ ? ''
220
+ : ` ${t.contributed} of ${t.sessions} sessions started below that first snapshot${rest > 0 ? `; the other ${rest} were the same size or larger` : ''}.`;
207
221
  out.push(
208
- `- **Estimated ${fmtBig(t.tokens)} context tokens not re-sent.** Compared with your first recorded Claude Code starting context: ${t.turns.toLocaleString()} calls across ${t.sessions} sessions. Estimated from characters / 4; most would have been cached input. Project or manual configuration changes can also change this baseline; this is not a causal savings measurement.`,
222
+ `- **Estimated ${fmtBig(t.tokens)} context tokens not re-sent.** Compared with your first recorded Claude Code starting context: ${t.turns.toLocaleString()} calls across ${t.sessions} sessions.${who} Estimated from characters / 4; most would have been cached input. Project or manual configuration changes can also change this baseline; this is not a causal savings measurement.`,
209
223
  );
210
224
  if (t.windowPct !== null && t.calib)
211
225
  out.push(
package/src/where.mjs CHANGED
@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
4
4
  import { join } from 'node:path';
5
5
  import { createInterface } from 'node:readline';
6
6
  import { fmt } from './report.mjs';
7
+ import { attachmentPieces, pieceDiff } from './startup.mjs';
7
8
  import { stateDir } from './store.mjs';
8
9
  import { BIG_RESULT, tipFor, toolKey } from './toolcheck.mjs';
9
10
  import { jsonlFiles } from './usage.mjs';
@@ -13,8 +14,8 @@ import { jsonlFiles } from './usage.mjs';
13
14
  // call i-1: its own output (written to the cache) plus the tool results it asked for plus your messages. So the input
14
15
  // of call i, less call i-1's output, is attributed to the tools call i-1 used. Claude Code transcripts only.
15
16
 
16
- /** @typedef {{t:number, input:number, cacheWrite:number, cacheRead:number, output:number, tools:string[], side:boolean, entry:string, project:string, model?:string, prompt?:string, agentType?:string}} Call
17
- * prompt: first words of the session's first message, on its first main-thread call; agentType: a subagent transcript's type, on its first call */
17
+ /** @typedef {{t:number, input:number, cacheWrite:number, cacheRead:number, output:number, tools:string[], side:boolean, entry:string, project:string, model?:string, prompt?:string, agentType?:string, startup?:import('./startup.mjs').Piece[]}} Call
18
+ * prompt: first words of the session's first message, on its first main-thread call; agentType: a subagent transcript's type, on its first call; startup: context loaded before the first response */
18
19
 
19
20
  const COLD_MIN = 100_000; // prompt size from which a missed cache is called a rebuild after idle
20
21
  const NO_TOOL = '(your messages)';
@@ -48,7 +49,18 @@ export async function readCalls(file) {
48
49
  const calls = new Map();
49
50
  /** @type {string|undefined} */
50
51
  let prompt;
52
+ /** @type {import('./startup.mjs').Piece[]} */
53
+ const startup = [];
54
+ let startupOpen = true;
51
55
  for await (const line of createInterface({ input: createReadStream(file), crlfDelay: Infinity })) {
56
+ if (startupOpen && line.includes('"type":"attachment"')) {
57
+ try {
58
+ const ev = JSON.parse(line);
59
+ if (ev?.type === 'attachment') startup.push(...attachmentPieces(ev.attachment));
60
+ } catch {
61
+ /* a torn line: the call list is what matters */
62
+ }
63
+ }
52
64
  if (prompt === undefined && line.includes('"type":"user"')) prompt = firstPrompt(line);
53
65
  if (!line.includes('"usage"')) continue;
54
66
  let ev;
@@ -61,6 +73,7 @@ export async function readCalls(file) {
61
73
  const u = m?.usage;
62
74
  const t = Date.parse(ev?.timestamp);
63
75
  if (ev?.type !== 'assistant' || !u || !Number.isFinite(t)) continue;
76
+ startupOpen = false;
64
77
  const id = `${m.id ?? ''}:${ev.requestId ?? ''}`;
65
78
  let c = calls.get(id);
66
79
  if (!c || id === ':') {
@@ -85,6 +98,7 @@ export async function readCalls(file) {
85
98
  const all = [...calls.values()];
86
99
  const first = all.find((c) => !c.side);
87
100
  if (first && prompt) first.prompt = prompt;
101
+ if (first && startup.length) first.startup = startup;
88
102
  // A subagent's transcript has its type in a file next to it: agent-<id>.jsonl and agent-<id>.meta.json.
89
103
  if (all.length && file.includes('/subagents/')) {
90
104
  try {
@@ -117,7 +131,7 @@ export function attribute(sessions, since = 0) {
117
131
  tools: new Map(),
118
132
  /** @type {{tokens:number, tool:string, t:number, project:string}[]} */
119
133
  steps: [],
120
- /** @type {{t:number, tokens:number, size:number, calls:number, prompt:string, project:string, entry:string}[]} headless session starts: when, new tokens, and the whole starting prompt (cached or not) */
134
+ /** @type {{t:number, tokens:number, size:number, calls:number, prompt:string, project:string, entry:string, startup?:import('./startup.mjs').Piece[]}[]} headless session starts: when, new tokens, and the whole starting prompt (cached or not) */
121
135
  starts: [],
122
136
  /** @type {Map<string, number>} every new token, by model */
123
137
  byModel: new Map(),
@@ -165,6 +179,7 @@ export function attribute(sessions, since = 0) {
165
179
  prompt: c.prompt ?? '',
166
180
  project: c.project,
167
181
  entry: c.entry,
182
+ ...(c.startup?.length ? { startup: c.startup } : {}),
168
183
  });
169
184
  }
170
185
  return;
@@ -340,6 +355,40 @@ function coldSection(runs, jobs) {
340
355
  return lines;
341
356
  }
342
357
 
358
+ const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
359
+
360
+ /**
361
+ * Which startup piece changed between the earliest and latest recorded run of a job.
362
+ * Only jobs with two startup breakdowns are named. A stable prefix is omitted.
363
+ * @param {[string, {starts:{startup?:import('./startup.mjs').Piece[]}[]} ][]} ranked
364
+ */
365
+ function driftSection(ranked) {
366
+ /** @type {string[]} */
367
+ const rows = [];
368
+ for (const [name, job] of ranked) {
369
+ const marked = job.starts.filter((s) => s.startup?.length);
370
+ if (marked.length < 2) continue;
371
+ const diff = pieceDiff(
372
+ /** @type {import('./startup.mjs').Piece[]} */ (marked[0].startup),
373
+ /** @type {import('./startup.mjs').Piece[]} */ (marked[marked.length - 1].startup),
374
+ );
375
+ for (const d of diff.slice(0, 5)) {
376
+ rows.push(`| ${name.replace(/\|/g, '/').slice(0, 45)} | ${d.group}: ${d.name} | ${fmt(tok(d.from))} | ${fmt(tok(d.to))} |`);
377
+ }
378
+ }
379
+ if (!rows.length) return [];
380
+ return [
381
+ '',
382
+ '## What changed between runs',
383
+ '',
384
+ 'The earliest and latest run of each job that recorded its startup. A piece that changes every run (a hook that prints a date or a count) keeps the prompt cache from being reused, so running the job again sooner does not warm it.',
385
+ '',
386
+ '| job | piece | earlier | later |',
387
+ '|---|---|---:|---:|',
388
+ ...rows,
389
+ ];
390
+ }
391
+
343
392
  /**
344
393
  * Markdown: the scheduled (headless) jobs whose runs spent the most new tokens just starting. A run's start is what
345
394
  * it loads before reading its prompt: settings, plugins, hooks, MCP servers, skills and instruction files.
@@ -388,6 +437,7 @@ export function jobsReport(r, { since, now }) {
388
437
  );
389
438
  }
390
439
  lines.push(...coldSection(r.starts.length, [...jobs.values()]));
440
+ lines.push(...driftSection(ranked));
391
441
  const [leanJob, lean] = [...jobs].sort((a, b) => a[1].size / a[1].runs - b[1].size / b[1].runs)[0];
392
442
  lines.push(
393
443
  '',