limitcast 0.0.0-stage → 0.6.0

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 ADDED
@@ -0,0 +1,312 @@
1
+ // @ts-check
2
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { homedir } from 'node:os';
5
+ import { fmt } from './report.mjs';
6
+
7
+ /** @typedef {import('./usage.mjs').Usage} Usage */
8
+ /** @typedef {{skills:Set<string>, mcp:Set<string>}} Activity skills and MCP servers used in the period */
9
+
10
+ const DESC_CAP = 1536; // Claude Code's default skillListingMaxDescChars
11
+
12
+ /**
13
+ * Fixed overhead: tokens every Claude Code session pays before you type anything,
14
+ * measured from the first response of each main (non-subagent) session.
15
+ * Counts interactive sessions so headless SDK/`claude -p` runs don't drag the median down:
16
+ * launched from the CLI where the transcript says so, else 5+ responses.
17
+ * @param {Usage[]} usage
18
+ */
19
+ export function baseline(usage) {
20
+ /** @type {Map<string, {first:Usage, n:number}>} */
21
+ const sessions = new Map();
22
+ for (const u of usage) {
23
+ if (u.src !== 'claude' || u.sidechain) continue;
24
+ const s = sessions.get(u.session);
25
+ if (!s) sessions.set(u.session, { first: u, n: 1 });
26
+ else {
27
+ s.n++;
28
+ if (u.t < s.first.t) s.first = u;
29
+ }
30
+ }
31
+ const interactive = [...sessions.values()].filter((s) => (s.first.entry ? s.first.entry === 'cli' : s.n >= 5));
32
+ const picked = interactive.length ? interactive : [...sessions.values()];
33
+ const sizes = picked.map(({ first: u }) => u.input + u.cacheWrite + u.cacheRead).sort((a, b) => a - b);
34
+ if (!sizes.length) return null;
35
+ return { sessions: sizes.length, median: sizes[Math.floor(sizes.length / 2)], max: sizes[sizes.length - 1] };
36
+ }
37
+
38
+ /**
39
+ * What loads into every session: instruction files (~4 bytes per token), each user skill's listing entry
40
+ * (name + description, honoring skillOverrides), and configured MCP servers.
41
+ * @param {{home?:string, cwd?:string}} [where]
42
+ */
43
+ export function contributors({ home = homedir(), cwd = process.cwd() } = {}) {
44
+ const claudeDir = join(home, '.claude');
45
+ /** @type {{what:string, tokens:number, path:string}[]} */
46
+ const files = [];
47
+ const file = (/** @type {string} */ p, /** @type {string} */ what) => {
48
+ if (existsSync(p)) files.push({ what, tokens: Math.round(statSync(p).size / 4), path: p.replace(home, '~') });
49
+ };
50
+ file(join(claudeDir, 'CLAUDE.md'), 'Global CLAUDE.md');
51
+ if (cwd !== home) file(join(cwd, 'CLAUDE.md'), 'Project CLAUDE.md');
52
+ file(join(home, 'CLAUDE.md'), 'Home CLAUDE.md');
53
+ file(join(claudeDir, 'projects', cwd.replace(/[^A-Za-z0-9]/g, '-'), 'memory', 'MEMORY.md'), 'Auto-memory index');
54
+ files.sort((a, b) => b.tokens - a.tokens);
55
+
56
+ const overrides = readJson(join(claudeDir, 'settings.json'))?.skillOverrides ?? {};
57
+ /** @type {{name:string, tokens:number, hidden:boolean}[]} */
58
+ const skills = [];
59
+ const skillsDir = join(claudeDir, 'skills');
60
+ if (existsSync(skillsDir)) {
61
+ for (const e of readdirSync(skillsDir, { withFileTypes: true })) {
62
+ const md = join(skillsDir, e.name, 'SKILL.md');
63
+ if (!e.isDirectory() || !existsSync(md)) continue;
64
+ const { name, desc } = skillListing(readFileSync(md, 'utf8'), e.name);
65
+ const mode = overrides[name] ?? overrides[e.name];
66
+ const hidden = mode === 'off' || mode === 'user-invocable-only';
67
+ const text = mode === 'name-only' ? name : `${name}: ${desc}`;
68
+ skills.push({ name, tokens: hidden ? 0 : Math.ceil((text.length + 4) / 4), hidden });
69
+ }
70
+ }
71
+
72
+ const cfg = readJson(join(home, '.claude.json'));
73
+ const mcp = [...new Set([...Object.keys(cfg?.mcpServers ?? {}), ...Object.keys(cfg?.projects?.[cwd]?.mcpServers ?? {})])];
74
+ return { files, skills, mcp };
75
+ }
76
+
77
+ /**
78
+ * A skill's name and listing description from its SKILL.md frontmatter.
79
+ * @param {string} md
80
+ * @param {string} fallbackName
81
+ */
82
+ export function skillListing(md, fallbackName) {
83
+ const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '';
84
+ const unquote = (/** @type {string} */ s) => s.trim().replace(/^(['"])(.*)\1$/, '$2');
85
+ const name = unquote(fm.match(/^name:\s*(.+)$/m)?.[1] ?? '') || fallbackName;
86
+ let desc = '';
87
+ const m = fm.match(/^description:[ \t]*(.*)$/m);
88
+ if (m) {
89
+ if (/^[>|][-+]?$/.test(m[1].trim())) {
90
+ // YAML block scalar: the indented lines that follow
91
+ const rest = fm
92
+ .slice((m.index ?? 0) + m[0].length)
93
+ .split(/\r?\n/)
94
+ .slice(1);
95
+ const block = [];
96
+ for (const l of rest) {
97
+ if (/^\s+\S/.test(l) || l.trim() === '') block.push(l.trim());
98
+ else break;
99
+ }
100
+ desc = block.join(' ').trim();
101
+ } else desc = unquote(m[1]);
102
+ }
103
+ return { name, desc: desc.slice(0, DESC_CAP) };
104
+ }
105
+
106
+ /** @param {string} p */
107
+ function readJson(p) {
108
+ try {
109
+ return JSON.parse(readFileSync(p, 'utf8'));
110
+ } catch {
111
+ return null;
112
+ }
113
+ }
114
+
115
+ /**
116
+ * Was this skill used? Usage names can be plugin-qualified ("plugin:skill").
117
+ * @param {string} name
118
+ * @param {Set<string>} used
119
+ */
120
+ const skillUsed = (name, used) => used.has(name) || [...used].some((u) => u.endsWith(`:${name}`));
121
+ /** MCP tool names keep the server name but may normalize punctuation. @param {string} s */
122
+ const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '_');
123
+
124
+ /**
125
+ * Measured savings: unused visible skills (exact listing size), unused MCP servers (named; their size
126
+ * isn't visible offline), and the instruction files that load every time.
127
+ * @param {ReturnType<typeof contributors>} c
128
+ * @param {Activity} used
129
+ */
130
+ export function savings(c, used) {
131
+ const unusedSkills = c.skills.filter((s) => !s.hidden && !skillUsed(s.name, used.skills)).sort((a, b) => b.tokens - a.tokens);
132
+ const usedMcp = new Set([...used.mcp].map(norm));
133
+ const unusedMcp = c.mcp.filter((s) => !usedMcp.has(norm(s)));
134
+ return { unusedSkills, skillTokens: unusedSkills.reduce((a, s) => a + s.tokens, 0), unusedMcp };
135
+ }
136
+
137
+ /**
138
+ * @param {ReturnType<typeof baseline>} base
139
+ * @param {ReturnType<typeof contributors>} c
140
+ * @param {Activity} used
141
+ * @param {number} days
142
+ */
143
+ export function trimReport(base, c, used, days) {
144
+ const s = savings(c, used);
145
+ const fileTokens = c.files.reduce((a, f) => a + f.tokens, 0);
146
+ const visible = c.skills.filter((k) => !k.hidden);
147
+ const listing = visible.reduce((a, k) => a + k.tokens, 0);
148
+ const lines = ['# limitcast trim', ''];
149
+ if (base) {
150
+ lines.push(
151
+ `Every Claude Code session starts at **${fmt(base.median)} tokens** before your first message (median of ${base.sessions} interactive sessions, max ${fmt(base.max)}).`,
152
+ 'That context is re-sent on every turn and to every subagent, so every token you cut stretches your limit windows.',
153
+ '',
154
+ );
155
+ } else lines.push('No interactive Claude Code sessions in the period yet.', '');
156
+
157
+ const pct = base && s.skillTokens ? ` (${Math.round((s.skillTokens / base.median) * 100)}% of your fixed overhead)` : '';
158
+ lines.push(`## Measured savings: ~${fmt(s.skillTokens)} tokens per session${pct}`, '');
159
+ if (s.unusedSkills.length) {
160
+ const names = s.unusedSkills.slice(0, 12).map((k) => k.name);
161
+ lines.push(
162
+ `- **Hide ${s.unusedSkills.length} skills you haven't used in ${days} days** (~${fmt(s.skillTokens)} tokens): ${names.join(', ')}${s.unusedSkills.length > 12 ? ', ...' : ''}.`,
163
+ ' In `~/.claude/settings.json`, set each to `"user-invocable-only"` under `skillOverrides`: `/name` still works, the model just stops seeing it.',
164
+ );
165
+ } else if (visible.length) lines.push(`- Every visible skill was used in the last ${days} days.`);
166
+ if (s.unusedMcp.length) {
167
+ lines.push(
168
+ `- **Disable ${s.unusedMcp.length} MCP servers you haven't used in ${days} days**: ${s.unusedMcp.join(', ')}.`,
169
+ " Each loads its tool definitions into every session; the size isn't visible offline, so check `/context` before and after.",
170
+ );
171
+ }
172
+ if (c.files.length) {
173
+ lines.push(
174
+ `- **Instruction files load in full every time** (~${fmt(fileTokens)} tokens): ${c.files.map((f) => `${f.what} ~${fmt(f.tokens)}`).join(', ')}.`,
175
+ ' Every 1k tokens you move into files read on demand saves 1k per session.',
176
+ );
177
+ }
178
+ lines.push('', '## Where the fixed overhead comes from', '', '| | est. tokens |', '|---|---:|');
179
+ for (const f of c.files) lines.push(`| ${f.what} (${f.path}) | ${fmt(f.tokens)} |`);
180
+ lines.push(`| Skill listing: ${visible.length} visible of ${c.skills.length} skills | ${fmt(listing)} |`);
181
+ if (c.mcp.length) lines.push(`| ${c.mcp.length} MCP servers | not measurable offline |`);
182
+ if (base) {
183
+ const rest = Math.max(0, base.median - fileTokens - listing);
184
+ lines.push(`| Everything else: Claude Code's own prompt, built-in tools, MCP and plugin tool definitions | ~${fmt(rest)} |`);
185
+ }
186
+ lines.push(
187
+ '',
188
+ '_Estimates: files at ~4 bytes per token; skill entries from their SKILL.md (Claude Code may shorten the listing to fit its budget, so real savings can be lower)._',
189
+ );
190
+ return lines.join('\n');
191
+ }
192
+
193
+ const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
194
+
195
+ /**
196
+ * From a measured startup breakdown: MCP servers and listed skills unused in the period, with their exact size.
197
+ * @param {import('./startup.mjs').Piece[]} pieces
198
+ * @param {Activity} used
199
+ */
200
+ export function measuredSavings(pieces, used) {
201
+ const usedMcp = new Set([...used.mcp].map(norm));
202
+ // Instructions and tool names spell a server differently ("claude.ai Postman" / "claude_ai_Postman"): merge by normalized name.
203
+ /** @type {Map<string, {name:string, chars:number}>} */
204
+ const mcp = new Map();
205
+ for (const p of pieces) {
206
+ if ((p.group === 'MCP server instructions' || p.group === 'Tool names') && p.name !== '(built-in)' && !usedMcp.has(norm(p.name))) {
207
+ const k = norm(p.name);
208
+ const m = mcp.get(k) ?? { name: p.name, chars: 0 };
209
+ m.chars += p.chars;
210
+ if (p.group === 'MCP server instructions') m.name = p.name; // the human spelling
211
+ mcp.set(k, m);
212
+ }
213
+ }
214
+ const skills = pieces.filter((p) => p.group === 'Skill listing' && !skillUsed(p.name, used.skills)).sort((a, b) => b.chars - a.chars);
215
+ const unusedMcp = [...mcp.values()].sort((a, b) => b.chars - a.chars);
216
+ const chars = unusedMcp.reduce((a, m) => a + m.chars, 0) + skills.reduce((a, s) => a + s.chars, 0);
217
+ return { unusedMcp, unusedSkills: skills, tokens: tok(chars) };
218
+ }
219
+
220
+ /**
221
+ * Trim report built on the measured starting context of your latest interactive session.
222
+ * @param {ReturnType<typeof baseline>} base
223
+ * @param {{pieces:import('./startup.mjs').Piece[], at:number}} b
224
+ * @param {Activity} used
225
+ * @param {number} days
226
+ */
227
+ export function startupReport(base, b, used, days) {
228
+ const s = measuredSavings(b.pieces, used);
229
+ const median = base?.median ?? 0;
230
+ const lines = ['# limitcast trim', ''];
231
+ if (base) {
232
+ lines.push(
233
+ `Every Claude Code session starts at **${fmt(median)} tokens** before your first message (median of ${base.sessions} interactive sessions).`,
234
+ 'That context is re-sent on every turn and to every subagent, so every token you cut stretches your limit windows.',
235
+ '',
236
+ );
237
+ }
238
+ const pct = median ? ` (${Math.round((s.tokens / median) * 100)}% of your starting context)` : '';
239
+ lines.push(`## Measured savings: ~${fmt(s.tokens)} tokens per session${pct}`, '', `From things you haven't used in the last ${days} days:`, '');
240
+ if (s.unusedMcp.length) {
241
+ const total = s.unusedMcp.reduce((a, m) => a + m.chars, 0);
242
+ lines.push(
243
+ `- **Disable ${s.unusedMcp.length} MCP servers** (~${fmt(tok(total))}): ${s.unusedMcp
244
+ .slice(0, 10)
245
+ .map((m) => `${m.name} ~${fmt(tok(m.chars))}`)
246
+ .join(', ')}${s.unusedMcp.length > 10 ? ', ...' : ''}.`,
247
+ ' Their instructions and tool names load into every session. Remove them in `/mcp`, or move them to the projects that use them.',
248
+ );
249
+ }
250
+ if (s.unusedSkills.length) {
251
+ const total = s.unusedSkills.reduce((a, k) => a + k.chars, 0);
252
+ lines.push(
253
+ `- **Hide ${s.unusedSkills.length} skills from the model** (~${fmt(tok(total))}): ${s.unusedSkills
254
+ .slice(0, 10)
255
+ .map((k) => k.name)
256
+ .join(', ')}${s.unusedSkills.length > 10 ? ', ...' : ''}.`,
257
+ ' Set each to `"user-invocable-only"` under `skillOverrides` in `~/.claude/settings.json`: `/name` still works.',
258
+ );
259
+ }
260
+ if (!s.unusedMcp.length && !s.unusedSkills.length) lines.push('- Nothing unused. Everything that loads was used in the period.');
261
+
262
+ /** @type {Map<string, number>} */
263
+ const groups = new Map();
264
+ for (const p of b.pieces) groups.set(p.group, (groups.get(p.group) ?? 0) + p.chars);
265
+ const measured = tok([...groups.values()].reduce((a, c) => a + c, 0));
266
+ lines.push('', `## Where your starting context comes from`, '', `Measured from your latest session (${new Date(b.at).toLocaleString()}).`, '');
267
+ lines.push('| | ~tokens | biggest items |', '|---|---:|---|');
268
+ for (const [g, chars] of [...groups].sort((x, y) => y[1] - x[1])) {
269
+ const top = b.pieces
270
+ .filter((p) => p.group === g)
271
+ .sort((x, y) => y.chars - x.chars)
272
+ .slice(0, 3)
273
+ .map((p) => `${p.name.replace(/^\/Users\/[^/]+/, '~')} ${fmt(tok(p.chars))}`)
274
+ .join(', ');
275
+ lines.push(`| ${g} | ${fmt(tok(chars))} | ${top} |`);
276
+ }
277
+ if (median)
278
+ lines.push(`| Claude Code's own prompt and built-in tool definitions (not in transcripts) | ~${fmt(Math.max(0, median - measured))} | |`);
279
+ const hooks = b.pieces.filter((p) => p.group === 'SessionStart hooks').sort((x, y) => y.chars - x.chars);
280
+ if (hooks.length) {
281
+ lines.push(
282
+ '',
283
+ `**SessionStart hooks inject ~${fmt(tok(hooks.reduce((a, p) => a + p.chars, 0)))} tokens into every session.** If a hook's output isn't needed every time, shorten it or have it print only when relevant.`,
284
+ );
285
+ }
286
+ lines.push('', '_Token counts are estimated at ~4 characters per token._');
287
+ return lines.join('\n');
288
+ }
289
+
290
+ /**
291
+ * A summary safe to post publicly: totals and counts only, no project, file, skill, server or hook names.
292
+ * @param {ReturnType<typeof baseline>} base
293
+ * @param {{pieces:import('./startup.mjs').Piece[]}} b
294
+ * @param {Activity} used
295
+ * @param {number} days
296
+ */
297
+ export function shareSummary(base, b, used, days) {
298
+ const s = measuredSavings(b.pieces, used);
299
+ /** @type {Map<string, number>} */
300
+ const groups = new Map();
301
+ for (const p of b.pieces) groups.set(p.group, (groups.get(p.group) ?? 0) + p.chars);
302
+ const median = base?.median ?? 0;
303
+ const lines = [
304
+ `My Claude Code sessions start at ${fmt(median)} tokens before I type.`,
305
+ `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.`,
306
+ 'Where it comes from:',
307
+ ...[...groups].sort((x, y) => y[1] - x[1]).map(([g, c]) => ` ${g}: ${fmt(tok(c))}`),
308
+ ];
309
+ if (median) lines.push(` Claude Code's own prompt and tools: ${fmt(Math.max(0, median - tok([...groups.values()].reduce((a, c) => a + c, 0))))}`);
310
+ lines.push('Measured with limitcast (https://limitcast.dev)');
311
+ return lines.join('\n');
312
+ }
package/src/usage.mjs ADDED
@@ -0,0 +1,233 @@
1
+ // @ts-check
2
+ import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
+ import { createInterface } from 'node:readline';
4
+ import { basename, join } from 'node:path';
5
+ import { homedir } from 'node:os';
6
+
7
+ /**
8
+ * One model response's token usage.
9
+ * @typedef {{t:number, src:'claude'|'codex'|'grok', session:string, project:string, model:string, sidechain:boolean,
10
+ * input:number, cacheWrite:number, cacheRead:number, output:number, entry?:string}} Usage entry: how Claude Code was launched (cli, sdk-py, ...)
11
+ */
12
+
13
+ export const claudeRoot = () => join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'projects');
14
+ export const codexRoot = () => join(process.env.CODEX_HOME ?? join(homedir(), '.codex'), 'sessions');
15
+ export const grokRoot = () => join(process.env.GROK_HOME ?? join(homedir(), '.grok'), 'sessions');
16
+
17
+ /**
18
+ * Claude Code transcript lines → usage, one per API message.
19
+ * Transcripts repeat the same usage on every content block of a message, so count each message id once.
20
+ * @param {string} line
21
+ * @param {Set<string>} seen message ids already counted
22
+ * @param {string} session
23
+ * @returns {Usage|null}
24
+ */
25
+ export function claudeUsage(line, seen, session) {
26
+ if (!line.includes('"usage"')) return null;
27
+ let ev;
28
+ try {
29
+ ev = JSON.parse(line);
30
+ } catch {
31
+ return null;
32
+ }
33
+ const u = ev?.message?.usage;
34
+ const t = Date.parse(ev?.timestamp);
35
+ if (ev?.type !== 'assistant' || !u || !Number.isFinite(t)) return null;
36
+ const id = `${ev.message.id ?? ''}:${ev.requestId ?? ''}`;
37
+ if (id !== ':' && seen.has(id)) return null;
38
+ seen.add(id);
39
+ return {
40
+ t,
41
+ src: 'claude',
42
+ session,
43
+ project: ev.cwd ?? '',
44
+ model: ev.message.model ?? '',
45
+ sidechain: !!ev.isSidechain,
46
+ input: u.input_tokens ?? 0,
47
+ cacheWrite: u.cache_creation_input_tokens ?? 0,
48
+ cacheRead: u.cache_read_input_tokens ?? 0,
49
+ output: u.output_tokens ?? 0,
50
+ ...(ev.entrypoint ? { entry: String(ev.entrypoint) } : {}),
51
+ };
52
+ }
53
+
54
+ /**
55
+ * Record which skills and MCP servers a Claude Code transcript line used: Skill tool calls, /slash commands, mcp__server__tool calls.
56
+ * @param {string} line
57
+ * @param {import('./trim.mjs').Activity} act
58
+ */
59
+ export function claudeActivity(line, act) {
60
+ if (line.includes('<command-name>')) {
61
+ for (const m of line.matchAll(/<command-name>\/?([^<\s]+)<\/command-name>/g)) act.skills.add(m[1]);
62
+ }
63
+ if (!line.includes('"name":"Skill"') && !line.includes('"name":"mcp__')) return;
64
+ let ev;
65
+ try {
66
+ ev = JSON.parse(line);
67
+ } catch {
68
+ return;
69
+ }
70
+ const content = ev?.message?.content;
71
+ if (!Array.isArray(content)) return;
72
+ for (const c of content) {
73
+ if (c?.type !== 'tool_use' || typeof c.name !== 'string') continue;
74
+ if (c.name === 'Skill' && c.input?.skill) act.skills.add(String(c.input.skill));
75
+ else if (c.name.startsWith('mcp__')) act.mcp.add(c.name.split('__')[1] ?? '');
76
+ }
77
+ }
78
+
79
+ /**
80
+ * Codex rollout lines → usage. token_count events carry a running total, so emit the increase since the last one.
81
+ * @param {string} line
82
+ * @param {{prev:any, cwd:string, model:string}} st per-file state
83
+ * @param {string} session
84
+ * @returns {Usage|null}
85
+ */
86
+ export function codexUsage(line, st, session) {
87
+ let ev;
88
+ if (line.includes('"session_meta"') || line.includes('"turn_context"')) {
89
+ try {
90
+ ev = JSON.parse(line);
91
+ } catch {
92
+ return null;
93
+ }
94
+ st.cwd = ev?.payload?.cwd ?? st.cwd;
95
+ st.model = ev?.payload?.model ?? st.model;
96
+ return null;
97
+ }
98
+ if (!line.includes('"total_token_usage"')) return null;
99
+ try {
100
+ ev = JSON.parse(line);
101
+ } catch {
102
+ return null;
103
+ }
104
+ const tot = ev?.payload?.info?.total_token_usage;
105
+ const t = Date.parse(ev?.timestamp);
106
+ if (!tot || !Number.isFinite(t)) return null;
107
+ const p = st.prev ?? { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 };
108
+ st.prev = tot;
109
+ const cached = (tot.cached_input_tokens ?? 0) - (p.cached_input_tokens ?? 0);
110
+ const input = (tot.input_tokens ?? 0) - (p.input_tokens ?? 0) - cached;
111
+ const output = (tot.output_tokens ?? 0) - (p.output_tokens ?? 0);
112
+ if (input + cached + output <= 0) return null;
113
+ return { t, src: 'codex', session, project: st.cwd, model: st.model, sidechain: false, input, cacheWrite: 0, cacheRead: cached, output };
114
+ }
115
+
116
+ /**
117
+ * A Grok session's usage.json ledger → usage, one record per turn (each turn's own tokens, stamped when it ended).
118
+ * @param {any} ledger parsed usage.json
119
+ * @param {string} session
120
+ * @param {string} project
121
+ * @returns {Usage[]}
122
+ */
123
+ export function grokUsage(ledger, session, project) {
124
+ /** @type {Usage[]} */
125
+ const out = [];
126
+ for (const turn of Array.isArray(ledger?.turns) ? ledger.turns : []) {
127
+ const t = Date.parse(turn?.endedAt);
128
+ if (!Number.isFinite(t)) continue;
129
+ const cacheRead = turn.cachedReadTokens ?? 0;
130
+ const cacheWrite = turn.cacheCreationTokens ?? 0;
131
+ const input = Math.max(0, (turn.inputTokens ?? 0) - cacheRead - cacheWrite);
132
+ const output = turn.outputTokens ?? 0;
133
+ const model = turn.primaryModelId ?? Object.keys(turn.modelUsage ?? {})[0] ?? '';
134
+ out.push({ t, src: 'grok', session, project, model, sidechain: false, input, cacheWrite, cacheRead, output });
135
+ }
136
+ return out;
137
+ }
138
+
139
+ /**
140
+ * Grok session ledgers modified since `since`: <root>/<url-encoded project dir>/<session id>/usage.json.
141
+ * @param {string} root
142
+ * @param {number} since
143
+ */
144
+ function grokLedgers(root, since) {
145
+ if (!existsSync(root)) return [];
146
+ const out = [];
147
+ for (const proj of readdirSync(root, { withFileTypes: true })) {
148
+ if (!proj.isDirectory()) continue;
149
+ for (const sess of readdirSync(join(root, proj.name), { withFileTypes: true })) {
150
+ const file = join(root, proj.name, sess.name, 'usage.json');
151
+ if (sess.isDirectory() && existsSync(file) && statSync(file).mtimeMs >= since) {
152
+ out.push({ file, session: sess.name, project: safeDecode(proj.name) });
153
+ }
154
+ }
155
+ }
156
+ return out;
157
+ }
158
+
159
+ /**
160
+ * All usage since `since` from Claude Code, Codex and Grok.
161
+ * @param {number} since epoch ms
162
+ * @param {{claude?:string, codex?:string, grok?:string}} [roots]
163
+ * @param {import('./trim.mjs').Activity} [activity] if given, filled with the skills and MCP servers Claude Code used
164
+ * @returns {Promise<Usage[]>}
165
+ */
166
+ export async function readUsage(since, roots = {}, activity) {
167
+ /** @type {Usage[]} */
168
+ const out = [];
169
+ for (const file of jsonlFiles(roots.claude ?? claudeRoot(), since, () => true)) {
170
+ const seen = new Set();
171
+ const session = basename(file, '.jsonl');
172
+ for await (const line of lines(file)) {
173
+ if (activity) claudeActivity(line, activity);
174
+ const u = claudeUsage(line, seen, session);
175
+ if (u && u.t >= since) out.push(u);
176
+ }
177
+ }
178
+ for (const file of jsonlFiles(roots.codex ?? codexRoot(), since, (n) => n.startsWith('rollout-'))) {
179
+ const st = { prev: null, cwd: '', model: '' };
180
+ // rollout-2026-10-23T18-39-41-<session uuid>.jsonl → the uuid
181
+ const session = basename(file, '.jsonl').replace(/^rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-/, '');
182
+ for await (const line of lines(file)) {
183
+ const u = codexUsage(line, st, session);
184
+ if (u && u.t >= since) out.push(u);
185
+ }
186
+ }
187
+ for (const { file, session, project } of grokLedgers(roots.grok ?? grokRoot(), since)) {
188
+ let ledger;
189
+ try {
190
+ ledger = JSON.parse(readFileSync(file, 'utf8'));
191
+ } catch {
192
+ continue; // being written right now; picked up next run
193
+ }
194
+ for (const u of grokUsage(ledger, session, project)) if (u.t >= since) out.push(u);
195
+ }
196
+ return out;
197
+ }
198
+
199
+ /** @param {string} s */
200
+ function safeDecode(s) {
201
+ try {
202
+ return decodeURIComponent(s);
203
+ } catch {
204
+ return s;
205
+ }
206
+ }
207
+
208
+ /** @param {string} file */
209
+ function lines(file) {
210
+ return createInterface({ input: createReadStream(file), crlfDelay: Infinity });
211
+ }
212
+
213
+ /**
214
+ * .jsonl files under `dir` modified since `since`.
215
+ * @param {string} dir
216
+ * @param {number} since
217
+ * @param {(name:string)=>boolean} keep
218
+ * @returns {string[]}
219
+ */
220
+ export function jsonlFiles(dir, since, keep) {
221
+ if (!existsSync(dir)) return [];
222
+ /** @type {string[]} */
223
+ const out = [];
224
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
225
+ const p = join(dir, e.name);
226
+ if (e.isDirectory()) out.push(...jsonlFiles(p, since, keep));
227
+ else if (e.name.endsWith('.jsonl') && keep(e.name) && statSync(p).mtimeMs >= since) out.push(p);
228
+ }
229
+ return out;
230
+ }
231
+
232
+ /** @param {Usage} u */
233
+ export const total = (u) => u.input + u.cacheWrite + u.cacheRead + u.output;