limitcast 0.18.0 → 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 CHANGED
@@ -10,7 +10,7 @@
10
10
  </p>
11
11
 
12
12
  <p align="center">
13
- <strong>See the limit. Stay ahead.</strong><br>
13
+ <strong>Claude Code usage limits: forecast Codex and Grok too.</strong><br>
14
14
  See when your usage window will run out, control subagent burn,<br>
15
15
  and remove starting context you never use.
16
16
  </p>
@@ -36,7 +36,7 @@
36
36
 
37
37
  - **Keep agents in check.** Hold new subagents when capacity is tight, with receipts and optional budgets. The guard also holds a second subagent of the same type and prompt while the first is still running. `limitcast install --guard`
38
38
 
39
- - **Start lighter.** Inspect unused skills and MCP servers, then trim with backups and undo. `limitcast trim`
39
+ - **Start lighter.** Inspect unused skills and MCP servers, then trim with backups and undo. Apply turns off only MCP servers quiet for 30 days. `limitcast trim`
40
40
 
41
41
  <a id="free-and-open-source"></a>
42
42
 
package/bin/limitcast.mjs CHANGED
@@ -5,8 +5,11 @@ import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'no
5
5
  import { join } from 'node:path';
6
6
  import { fileURLToPath } from 'node:url';
7
7
  import {
8
+ APPLY_BLOCKED,
9
+ applyBlocked,
8
10
  applyTrim,
9
11
  claudeJsonPath,
12
+ ensureDefaultKeep,
10
13
  getKeep,
11
14
  installedPlugins,
12
15
  isKept,
@@ -115,9 +118,12 @@ const HELP = `limitcast ${VERSION}: stretch your Claude Code, Codex and Grok pla
115
118
  All features are free (MIT License)
116
119
  limitcast trim [--days N] [--share] names what to cut and what each costs
117
120
  (--share: totals only, no names, safe to post)
118
- limitcast trim --apply / --undo hide those skills and turn off those MCP servers (backed up, reversible)
119
- limitcast trim --codex --apply / --undo turn off unused Codex MCP servers (enabled = false; reversible)
120
- limitcast trim --grok --apply / --undo turn off unused Grok MCP servers (enabled = false; reversible)
121
+ limitcast trim --apply [--yes] / --undo hide unused skills and turn off MCP servers quiet for 30 days
122
+ (backed up, reversible). Refuses while the keep-list is empty
123
+ unless you pass --yes. install, doctor --fix, and trim
124
+ seed ego-browser when that list was never set.
125
+ limitcast trim --codex --apply [--yes] / --undo the same for Codex MCP servers (enabled = false; reversible)
126
+ limitcast trim --grok --apply [--yes] / --undo the same for Grok MCP servers (enabled = false; reversible)
121
127
  limitcast trim keep <name>[,<name>…] never hide or turn off these (any --apply); --remove <name> drops one, no name lists them
122
128
  limitcast saved tokens saved since limitcast first measured you
123
129
  limitcast install --guard block new subagents when a window is on pace to run out, and run
@@ -584,6 +590,7 @@ if (cmd === 'status') {
584
590
  const wantGuard = args.includes('--guard');
585
591
  const wantAlerts = args.includes('--alerts');
586
592
  for (const c of install({ guard: wantGuard, alerts: wantAlerts })) console.log(`✓ ${c}`);
593
+ if (ensureDefaultKeep().seeded) console.log('Kept ego-browser: trim --apply will not turn it off. Add more with limitcast trim keep <name>.');
587
594
  console.log('Restart Claude Code, Codex and Grok to load it. Then: limitcast doctor');
588
595
  if (wantGuard && grokPresent() && !getGrokBudget())
589
596
  console.log('Grok stores spend, not a % used. Set a 5-hour dollar cap so the guard can block: limitcast budget grok <usd>');
@@ -644,6 +651,7 @@ if (cmd === 'status') {
644
651
  if (!f.statusLine) console.log('limitcast is not installed. Run `limitcast install` first.');
645
652
  else {
646
653
  for (const c of install({ guard: f.guard, alerts: f.alerts })) console.log(`✓ ${c}`);
654
+ ensureDefaultKeep();
647
655
  console.log('Restart Claude Code, Codex and Grok to load it. Codex asks you to approve the guard again: start Codex and accept it.');
648
656
  }
649
657
  }
@@ -691,6 +699,12 @@ if (cmd === 'status') {
691
699
  console.error('--share is read-only; run keep, --apply, or --undo separately.');
692
700
  process.exit(1);
693
701
  }
702
+ if (cmd === 'trim' && args[0] !== 'keep' && !args.includes('--undo') && !args.includes('--share')) ensureDefaultKeep();
703
+ if (cmd === 'trim' && args.includes('--apply') && applyBlocked(getKeep(), args.includes('--yes'))) {
704
+ console.log(APPLY_BLOCKED);
705
+ process.exit(1);
706
+ }
707
+ const monthSince = now - 30 * 86400_000;
694
708
  if (cmd === 'trim' && args[0] === 'keep') {
695
709
  // The keep-list: servers and skills `trim --apply` never touches (Claude, Codex and Grok). Free to manage; apply is Pro.
696
710
  const drop = args[1] === '--remove';
@@ -723,7 +737,17 @@ if (cmd === 'status') {
723
737
  process.exit(0);
724
738
  }
725
739
  const servers = codexServers(readFileSync(codexConfigPath(), 'utf8'));
726
- const r = codexTrimReport({ servers, used: await codexUsedServers(since), startup: await codexStartup(), days: days(), pro, keep: getKeep() });
740
+ const usedCodex = await codexUsedServers(since);
741
+ const usedCodexMonth = days() >= 30 ? null : await codexUsedServers(monthSince);
742
+ const r = codexTrimReport({
743
+ servers,
744
+ used: usedCodex,
745
+ usedMonth: usedCodexMonth,
746
+ startup: await codexStartup(),
747
+ days: days(),
748
+ pro,
749
+ keep: getKeep(),
750
+ });
727
751
  if (args.includes('--apply')) {
728
752
  const changed = applyCodexTrim(r.unused);
729
753
  console.log(
@@ -734,7 +758,7 @@ if (cmd === 'status') {
734
758
  } else
735
759
  console.log(
736
760
  args.includes('--share')
737
- ? `Codex trim: ${r.unused.length} unused MCP servers, ${r.kept.length} kept. Totals only; no names or paths. https://limitcast.dev`
761
+ ? `Codex trim: ${r.unused.length} unused MCP servers, ${r.kept.length} kept.${r.standing.length ? ` ${r.standing.length} used in the last 30 days and left on.` : ''} Totals only; no names or paths. https://limitcast.dev`
738
762
  : forTerminal(r.text),
739
763
  );
740
764
  process.exit(0);
@@ -758,6 +782,7 @@ if (cmd === 'status') {
758
782
  const r = grokTrimReport({
759
783
  servers: grokServers(),
760
784
  used: grokUsedServers(since),
785
+ usedMonth: days() >= 30 ? null : grokUsedServers(monthSince),
761
786
  startup: grokStartup(),
762
787
  days: days(),
763
788
  pro,
@@ -773,7 +798,7 @@ if (cmd === 'status') {
773
798
  } else
774
799
  console.log(
775
800
  args.includes('--share')
776
- ? `Grok trim: ${r.unused.length} unused MCP servers, ${r.kept.length} kept. Totals only; no names or paths. https://limitcast.dev`
801
+ ? `Grok trim: ${r.unused.length} unused MCP servers, ${r.kept.length} kept.${r.standing.length ? ` ${r.standing.length} used in the last 30 days and left on.` : ''} Totals only; no names or paths. https://limitcast.dev`
777
802
  : forTerminal(r.text),
778
803
  );
779
804
  process.exit(0);
@@ -783,6 +808,12 @@ if (cmd === 'status') {
783
808
  const jobs = cmd === 'report' && args.includes('--jobs');
784
809
  const why = cmd === 'report' && args.includes('--why');
785
810
  const usage = why || jobs ? [] : await readUsage(since, {}, cmd === 'trim' ? used : undefined);
811
+ /** @type {import('../src/trim.mjs').Activity|null} */
812
+ let usedMonth = null;
813
+ if (cmd === 'trim' && days() < 30) {
814
+ usedMonth = { skills: new Set(), mcp: new Set() };
815
+ await readUsage(monthSince, {}, usedMonth);
816
+ }
786
817
  let text;
787
818
  if (why || jobs) {
788
819
  const r = attribute(await whySessions(claudeRoot(), since), since);
@@ -795,21 +826,21 @@ if (cmd === 'status') {
795
826
  if (latest) recordOverhead(snapshot(latest));
796
827
  // The share view omits private names; the local view includes actionable detail.
797
828
  if (args.includes('--apply') || args.includes('--undo')) {
798
- console.log(args.includes('--undo') ? undoMessage(undoTrim()) : applyMessage(latest, used));
829
+ console.log(args.includes('--undo') ? undoMessage(undoTrim()) : applyMessage(latest, used, usedMonth));
799
830
  process.exit(0);
800
831
  }
801
832
  const keep = getKeep();
802
- if (latest && args.includes('--share')) text = shareSummary(baseline(usage), latest, used, days(), keep);
833
+ if (latest && args.includes('--share')) text = shareSummary(baseline(usage), latest, used, days(), keep, usedMonth);
803
834
  else
804
835
  text = latest
805
- ? startupReport(baseline(usage), latest, used, days(), keep)
836
+ ? startupReport(baseline(usage), latest, used, days(), keep, usedMonth)
806
837
  : trimReport(baseline(usage), contributors(), used, days(), args.includes('--share'));
807
838
  if (latest && !args.includes('--share')) {
808
839
  const still = stillLoading(latest);
809
840
  text += still.length
810
841
  ? `\n\nStill loading after \`trim --apply\`: ${still.join(', ')}. A Claude Code session that was running may have rewritten ~/.claude.json; quit Claude Code and run \`limitcast trim --apply\` again.`
811
- : measuredSavings(latest.pieces, used, keep).tokens > 0
812
- ? '\n\nApply these cuts: `limitcast trim --apply` (backed up; `limitcast trim --undo` reverses it).'
842
+ : measuredSavings(latest.pieces, used, keep, usedMonth).tokens > 0
843
+ ? '\n\nApply these cuts: `limitcast trim --apply` turns off MCP servers quiet for 30 days and hides unused skills (backed up; `limitcast trim --undo` reverses it).'
813
844
  : '';
814
845
  }
815
846
  }
@@ -863,10 +894,13 @@ if (cmd === 'status') {
863
894
  const since = now - days() * 86400_000;
864
895
  let saved = '';
865
896
  let perSession = null;
897
+ /** @type {{first:number, last:number}|null} */
898
+ let start = null;
866
899
  if (pro) {
867
900
  const latest = await latestInteractiveTranscript(claudeRoot());
868
901
  if (latest) recordOverhead(snapshot(latest));
869
902
  const s = loadOverhead();
903
+ start = s ? { first: s.first.chars, last: s.last.chars } : null;
870
904
  perSession = s ? savedPerSession(s) : null;
871
905
  saved =
872
906
  s && !args.includes('--share')
@@ -895,7 +929,16 @@ if (cmd === 'status') {
895
929
  const burn = burnReport(await readUsage(since, {}), { since, now }).replace(/^(#{1,2}) /gm, '#$1 ');
896
930
  const md = [
897
931
  insightsReport(insight, pro),
898
- resultsReport({ now, days: days(), samples, blocks, pro, saved, value: valueSection(totals, { now, pro }), subagents: loadSubagents(since) }),
932
+ resultsReport({
933
+ now,
934
+ days: days(),
935
+ samples,
936
+ blocks,
937
+ pro,
938
+ saved,
939
+ value: valueSection(totals, { now, pro, start }),
940
+ subagents: loadSubagents(since),
941
+ }),
899
942
  '## Right now',
900
943
  '```',
901
944
  rows.length ? table(rows) : 'No readings yet.',
@@ -922,7 +965,7 @@ if (cmd === 'status') {
922
965
  blocks,
923
966
  pro,
924
967
  saved,
925
- value: valueSection(totals, { now, pro }),
968
+ value: valueSection(totals, { now, pro, start }),
926
969
  subagents: loadSubagents(since),
927
970
  }),
928
971
  ].join('\n\n'),
@@ -1102,13 +1145,13 @@ async function refreshValue() {
1102
1145
  * @param {Awaited<ReturnType<typeof latestInteractiveTranscript>>} latest
1103
1146
  * @param {import('../src/trim.mjs').Activity} used
1104
1147
  */
1105
- function applyMessage(latest, used) {
1148
+ function applyMessage(latest, used, usedMonth) {
1106
1149
  if (!latest) return '`limitcast trim --apply` needs one Claude Code session first.';
1107
- const s = measuredSavings(latest.pieces, used);
1150
+ const s = measuredSavings(latest.pieces, used, getKeep(), usedMonth);
1108
1151
  const cwd = transcriptCwd(latest.file) ?? process.cwd();
1109
1152
  const plan = planTrim({
1110
1153
  skills: s.unusedSkills.map((k) => k.name),
1111
- mcp: s.unusedMcp.map((m) => m.name),
1154
+ mcp: s.staleMcp.map((m) => m.name),
1112
1155
  cwd,
1113
1156
  settings: readSettings(settingsPath()),
1114
1157
  claudeJson: readSettings(claudeJsonPath()),
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "limitcast",
3
- "version": "0.18.0",
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.",
3
+ "version": "0.18.1",
4
+ "description": "Claude Code usage limits: forecast Codex and Grok too.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "limitcast": "bin/limitcast.mjs"
package/src/apply.mjs CHANGED
@@ -32,6 +32,13 @@ const ledgerPath = () => join(stateDir(), 'trim-applied.json');
32
32
  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '_');
33
33
  const configFile = () => join(stateDir(), 'config.json');
34
34
 
35
+ /** Seeded the first time the keep-list is created. `trim --apply` must not turn this off. */
36
+ export const DEFAULT_KEEP = ['ego-browser'];
37
+
38
+ /** Shown when `--apply` would run with nothing protected. */
39
+ export const APPLY_BLOCKED =
40
+ 'Nothing on the keep-list, so `trim --apply` would turn off every server that looks unused, including ego-browser. Run `limitcast trim keep ego-browser` first, or repeat with `--yes`.';
41
+
35
42
  /** Names `trim --apply` never turns off or hides, from `limitcast trim keep`. @returns {string[]} */
36
43
  export function getKeep() {
37
44
  try {
@@ -42,6 +49,25 @@ export function getKeep() {
42
49
  }
43
50
  }
44
51
 
52
+ /**
53
+ * Write the default keep-list when `trimKeep` has never been set. An explicit empty list stays empty.
54
+ * @returns {{keep:string[], seeded:boolean}}
55
+ */
56
+ export function ensureDefaultKeep() {
57
+ let cfg = {};
58
+ try {
59
+ cfg = JSON.parse(readFileSync(configFile(), 'utf8'));
60
+ } catch {
61
+ cfg = {};
62
+ }
63
+ if (Object.hasOwn(cfg, 'trimKeep')) return { keep: getKeep(), seeded: false };
64
+ setKeep(DEFAULT_KEEP);
65
+ return { keep: [...DEFAULT_KEEP], seeded: true };
66
+ }
67
+
68
+ /** True when `--apply` must stop because nothing is protected and the user did not pass `--yes`. */
69
+ export const applyBlocked = (/** @type {string[]} */ keep, /** @type {boolean} */ yes) => !yes && keep.length === 0;
70
+
45
71
  /** @param {string[]} names */
46
72
  export function setKeep(names) {
47
73
  let cfg = {};
package/src/codex.mjs CHANGED
@@ -118,14 +118,16 @@ export async function codexStartup(root = join(codexHome(), 'sessions')) {
118
118
  }
119
119
 
120
120
  /**
121
- * @param {{servers:{name:string, enabled:boolean|undefined}[], used:Set<string>, startup:{agentsMd:number, base:number}|null, days:number, pro:boolean, keep?:string[]}} r
122
- * keep: the `trim keep` list; unused servers on it are reported as kept and left out of `unused`
121
+ * @param {{servers:{name:string, enabled:boolean|undefined}[], used:Set<string>, usedMonth?:Set<string>|null, startup:{agentsMd:number, base:number}|null, days:number, pro:boolean, keep?:string[]}} r
122
+ * keep: the `trim keep` list; unused servers on it are reported as kept and left out of `unused`.
123
+ * usedMonth: normalized names used in 30 days. Servers in it stay out of `unused`.
123
124
  */
124
- export function codexTrimReport({ servers, used, startup, days, pro, keep = [] }) {
125
+ export function codexTrimReport({ servers, used, usedMonth = null, startup, days, pro, keep = [] }) {
125
126
  const on = servers.filter((s) => s.enabled !== false);
126
127
  const idle = on.filter((s) => !used.has(norm(s.name)));
127
128
  const kept = idle.filter((s) => keep.some((k) => norm(k) === norm(s.name)));
128
- const unused = idle.filter((s) => !kept.includes(s));
129
+ const standing = usedMonth ? idle.filter((s) => !kept.includes(s) && usedMonth.has(norm(s.name))) : [];
130
+ const unused = idle.filter((s) => !kept.includes(s) && !standing.includes(s));
129
131
  const tok = (/** @type {number} */ c) => `${(c / 4000).toFixed(1)}k`;
130
132
  const out = ['# limitcast trim --codex', ''];
131
133
  if (startup)
@@ -133,17 +135,28 @@ export function codexTrimReport({ servers, used, startup, days, pro, keep = [] }
133
135
  `Codex sessions start with ~${tok(startup.agentsMd)} tokens of AGENTS.md (your instruction files) and ~${tok(startup.base)} of Codex's own instructions, re-sent on every turn.`,
134
136
  '',
135
137
  );
136
- out.push(`## MCP servers: ${on.length} on, ${unused.length} not used in ${days} days`);
137
- if (!unused.length) out.push(kept.length ? 'Nothing else to turn off.' : 'Every server that is on was used.');
138
+ out.push(`## MCP servers: ${on.length} on, ${unused.length + standing.length} not used in ${days} days`);
139
+ if (standing.length)
140
+ out.push('', `${standing.length} used in the last 30 days, so \`trim --apply\` leaves them on:`, ...standing.map((s) => `- ${s.name}`));
141
+ if (!unused.length) out.push(kept.length || standing.length ? 'Nothing else to turn off.' : 'Every server that is on was used.');
138
142
  else if (pro)
139
- out.push(...unused.map((s) => `- ${s.name}`), '', 'Turn them off: `limitcast trim --codex --apply` (backed up; `--undo` reverses it).');
143
+ out.push(
144
+ ...unused.map((s) => `- ${s.name}`),
145
+ '',
146
+ `${usedMonth ? 'Turn the servers that have been quiet for 30 days off' : 'Turn them off'}: \`limitcast trim --codex --apply\` (backed up; \`--undo\` reverses it).`,
147
+ );
140
148
  else out.push(`Pro names them and turns them off for you: https://limitcast.dev/#pricing`);
141
149
  if (kept.length) out.push('', `Would keep (your keep-list): ${kept.map((s) => s.name).join(', ')}.`);
142
150
  out.push(
143
151
  '',
144
152
  'Each server that is on starts with every Codex session and adds its tool list to the context. AGENTS.md: every 1k tokens you move into files read on demand saves 1k per turn.',
145
153
  );
146
- return { text: out.join('\n'), unused: unused.map((s) => s.name), kept: kept.map((s) => s.name) };
154
+ return {
155
+ text: out.join('\n'),
156
+ unused: unused.map((s) => s.name),
157
+ standing: standing.map((s) => s.name),
158
+ kept: kept.map((s) => s.name),
159
+ };
147
160
  }
148
161
 
149
162
  /** @param {string} path @param {string} text */
package/src/grok.mjs CHANGED
@@ -73,14 +73,16 @@ export function grokStartup(root = grokRoot()) {
73
73
  }
74
74
 
75
75
  /**
76
- * @param {{servers:{name:string, enabled:boolean|undefined}[], used:Set<string>, startup:{prompt:number, tools:number}|null, days:number, pro:boolean, keep?:string[]}} r
77
- * keep: the `trim keep` list; unused servers on it are reported as kept and left out of `unused`
76
+ * @param {{servers:{name:string, enabled:boolean|undefined}[], used:Set<string>, usedMonth?:Set<string>|null, startup:{prompt:number, tools:number}|null, days:number, pro:boolean, keep?:string[]}} r
77
+ * keep: the `trim keep` list; unused servers on it are reported as kept and left out of `unused`.
78
+ * usedMonth: normalized names used in 30 days. Servers in it stay out of `unused`.
78
79
  */
79
- export function grokTrimReport({ servers, used, startup, days, pro, keep = [] }) {
80
+ export function grokTrimReport({ servers, used, usedMonth = null, startup, days, pro, keep = [] }) {
80
81
  const on = servers.filter((s) => s.enabled !== false);
81
82
  const idle = on.filter((s) => !used.has(norm(s.name)));
82
83
  const kept = idle.filter((s) => keep.some((k) => norm(k) === norm(s.name)));
83
- const unused = idle.filter((s) => !kept.includes(s));
84
+ const standing = usedMonth ? idle.filter((s) => !kept.includes(s) && usedMonth.has(norm(s.name))) : [];
85
+ const unused = idle.filter((s) => !kept.includes(s) && !standing.includes(s));
84
86
  const tok = (/** @type {number} */ c) => `${(c / 4000).toFixed(1)}k`;
85
87
  const out = ['# limitcast trim --grok', ''];
86
88
  if (startup)
@@ -88,17 +90,28 @@ export function grokTrimReport({ servers, used, startup, days, pro, keep = [] })
88
90
  `Grok sessions start with ~${tok(startup.prompt)} tokens of system prompt and ~${tok(startup.tools)} of tool definitions, re-sent on every turn.`,
89
91
  '',
90
92
  );
91
- out.push(`## MCP servers: ${on.length} on, ${unused.length} not used in ${days} days`);
92
- if (!unused.length) out.push(kept.length ? 'Nothing else to turn off.' : 'Every server that is on was used.');
93
+ out.push(`## MCP servers: ${on.length} on, ${unused.length + standing.length} not used in ${days} days`);
94
+ if (standing.length)
95
+ out.push('', `${standing.length} used in the last 30 days, so \`trim --apply\` leaves them on:`, ...standing.map((s) => `- ${s.name}`));
96
+ if (!unused.length) out.push(kept.length || standing.length ? 'Nothing else to turn off.' : 'Every server that is on was used.');
93
97
  else if (pro)
94
- out.push(...unused.map((s) => `- ${s.name}`), '', 'Turn them off: `limitcast trim --grok --apply` (backed up; `--undo` reverses it).');
98
+ out.push(
99
+ ...unused.map((s) => `- ${s.name}`),
100
+ '',
101
+ `${usedMonth ? 'Turn the servers that have been quiet for 30 days off' : 'Turn them off'}: \`limitcast trim --grok --apply\` (backed up; \`--undo\` reverses it).`,
102
+ );
95
103
  else out.push(`Pro names them and turns them off for you: https://limitcast.dev/#pricing`);
96
104
  if (kept.length) out.push('', `Would keep (your keep-list): ${kept.map((s) => s.name).join(', ')}.`);
97
105
  out.push(
98
106
  '',
99
107
  'Each server that is on starts with every Grok session and adds its tool list to the context. Moving unused servers off is `enabled = false` in ~/.grok/config.toml.',
100
108
  );
101
- return { text: out.join('\n'), unused: unused.map((s) => s.name), kept: kept.map((s) => s.name) };
109
+ return {
110
+ text: out.join('\n'),
111
+ unused: unused.map((s) => s.name),
112
+ standing: standing.map((s) => s.name),
113
+ kept: kept.map((s) => s.name),
114
+ };
102
115
  }
103
116
 
104
117
  /**
package/src/guard.mjs CHANGED
@@ -8,6 +8,16 @@ import { budgetMessage, budgetSpent, getBudget, getTodayHold, loadSubagents, pin
8
8
 
9
9
  const NAMES = { claude: 'Claude', codex: 'Codex', grok: 'Grok' };
10
10
 
11
+ /**
12
+ * How far back a Codex guard read must go. Today's share of a weekly window needs a reading from before
13
+ * local midnight. Just after midnight, keep the last two hours so the pace still has a slope.
14
+ * @param {number} now epoch ms
15
+ */
16
+ export function codexGuardSince(now) {
17
+ const midnight = new Date(now).setHours(0, 0, 0, 0);
18
+ return Math.min(now - 2 * 3600_000, midnight - 60_000);
19
+ }
20
+
11
21
  /**
12
22
  * Whose limits a subagent-spawning tool call draws on, or null if the call spawns nothing.
13
23
  * Claude Code: Task/Agent. Codex: spawn_agent (reported with a namespace prefix). Grok: spawn_subagent.
@@ -65,12 +75,13 @@ export async function runGuard(hook, now, minutes, { preview = false } = {}) {
65
75
  const tool = String(hook?.tool_name ?? hook?.toolName ?? hook?.tool ?? '');
66
76
  const src = spawnSource(tool);
67
77
  const operation = hook?.tool_use_id ?? hook?.toolUseId ?? hook?.call_id;
68
- // Codex: only the last two hours of rollouts, so the hook stays fast. Grok: spend vs the user's dollar cap.
78
+ // Codex: back to local midnight, and at least two hours, so today's share can see a reading from before midnight.
79
+ // A two-hour cap hid that reading and the share read low. Grok: spend vs the user's dollar cap.
69
80
  const samples =
70
81
  src === 'claude'
71
82
  ? oneClaudeAccount(load(now - KEEP_MS), hook.session_id ?? hook.sessionId)
72
83
  : src === 'codex'
73
- ? await readCodex(now - 2 * 3600_000)
84
+ ? await readCodex(codexGuardSince(now))
74
85
  : src === 'grok'
75
86
  ? grokSamples(now)
76
87
  : [];
@@ -99,7 +110,7 @@ export async function runGuard(hook, now, minutes, { preview = false } = {}) {
99
110
  if (reason) return preview ? null : reason;
100
111
  // Today's share of a weekly window is used up: hold new subagents until local midnight, when the share starts over.
101
112
  // Opt-in for Pro (`limitcast budget today on`; the default is a notification at 80%); a free preview records it either way.
102
- // A window already at 100% is left to the tool. shortcut: Codex readings here span only 2 hours, so its share reads low.
113
+ // A window already at 100% is left to the tool.
103
114
  const day = todayOver(src, forecasts);
104
115
  if (day && (preview || getTodayHold())) {
105
116
  try {
package/src/trim.mjs CHANGED
@@ -207,9 +207,11 @@ const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
207
207
  * @param {import('./startup.mjs').Piece[]} pieces
208
208
  * @param {Activity} used
209
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.
210
211
  */
211
- export function measuredSavings(pieces, used, keep = []) {
212
+ export function measuredSavings(pieces, used, keep = [], usedMonth = null) {
212
213
  const usedMcp = new Set([...used.mcp].map(norm));
214
+ const month = usedMonth ? new Set([...usedMonth.mcp].map(norm)) : null;
213
215
  // Instructions and tool names spell a server differently ("claude.ai Postman" / "claude_ai_Postman"): merge by normalized name.
214
216
  /** @type {Map<string, {name:string, chars:number}>} */
215
217
  const mcp = new Map();
@@ -226,9 +228,11 @@ export function measuredSavings(pieces, used, keep = []) {
226
228
  const kept = [...mcp.values(), ...skills].filter((x) => keep.some((k) => norm(k) === norm(x.name))).map((x) => x.name);
227
229
  const isKept = (/** @type {{name:string}} */ x) => kept.includes(x.name);
228
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;
229
233
  const unusedSkills = skills.filter((s) => !isKept(s));
230
- const chars = unusedMcp.reduce((a, m) => a + m.chars, 0) + unusedSkills.reduce((a, s) => a + s.chars, 0);
231
- 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 };
232
236
  }
233
237
 
234
238
  /**
@@ -238,9 +242,10 @@ export function measuredSavings(pieces, used, keep = []) {
238
242
  * @param {Activity} used
239
243
  * @param {number} days
240
244
  * @param {string[]} [keep] the `trim keep` list
245
+ * @param {Activity|null} [usedMonth] servers used in 30 days; `--apply` leaves those on
241
246
  */
242
- export function startupReport(base, b, used, days, keep = []) {
243
- 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);
244
249
  const median = base?.median ?? 0;
245
250
  const lines = ['# limitcast trim', ''];
246
251
  if (base) {
@@ -254,16 +259,27 @@ export function startupReport(base, b, used, days, keep = []) {
254
259
  lines.push(
255
260
  `## Estimated removable context: ~${fmt(s.tokens)} tokens per session${pct}`,
256
261
  '',
257
- `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:`,
258
265
  '',
259
266
  );
260
- if (s.unusedMcp.length) {
261
- 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);
262
278
  lines.push(
263
- `- **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
264
280
  .slice(0, 10)
265
281
  .map((m) => `${m.name} ~${fmt(tok(m.chars))}`)
266
- .join(', ')}${s.unusedMcp.length > 10 ? ', ...' : ''}.`,
282
+ .join(', ')}${s.staleMcp.length > 10 ? ', ...' : ''}.`,
267
283
  ' Their instructions and tool names load into every session. Remove them in `/mcp`, or move them to the projects that use them.',
268
284
  );
269
285
  }
@@ -315,16 +331,17 @@ export function startupReport(base, b, used, days, keep = []) {
315
331
  * @param {Activity} used
316
332
  * @param {number} days
317
333
  * @param {string[]} [keep] the `trim keep` list; only its count is shown
334
+ * @param {Activity|null} [usedMonth] servers used in 30 days
318
335
  */
319
- export function shareSummary(base, b, used, days, keep = []) {
320
- 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);
321
338
  /** @type {Map<string, number>} */
322
339
  const groups = new Map();
323
340
  for (const p of b.pieces) groups.set(p.group, (groups.get(p.group) ?? 0) + p.chars);
324
341
  const median = base?.median ?? 0;
325
342
  const lines = [
326
343
  `My Claude Code sessions start at ${fmt(median)} tokens before I type.`,
327
- `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)` : ''}.`,
328
345
  'Where it comes from:',
329
346
  ...[...groups].sort((x, y) => y[1] - x[1]).map(([g, c]) => ` ${g}: ${fmt(tok(c))}`),
330
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(