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/README.md +147 -84
- package/bin/limitcast.mjs +225 -45
- package/package.json +2 -2
- package/src/apply.mjs +26 -0
- package/src/codex.mjs +21 -8
- package/src/cold.mjs +47 -10
- package/src/grok.mjs +21 -8
- package/src/guard.mjs +14 -3
- package/src/inflight.mjs +99 -0
- package/src/install.mjs +9 -0
- package/src/results.mjs +21 -1
- package/src/startup.mjs +28 -0
- package/src/toollimit.mjs +137 -0
- package/src/trim.mjs +40 -14
- package/src/value.mjs +17 -3
- package/src/where.mjs +53 -3
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 =
|
|
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
|
-
|
|
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.
|
|
252
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
'',
|