limitcast 0.0.0-stage → 0.6.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/LICENSE +95 -0
- package/README.md +73 -2
- package/bin/limitcast.mjs +256 -0
- package/package.json +14 -4
- package/src/forecast.mjs +89 -0
- package/src/formats.mjs +115 -0
- package/src/guard.mjs +65 -0
- package/src/install.mjs +241 -0
- package/src/license.mjs +71 -0
- package/src/overhead.mjs +101 -0
- package/src/polar.mjs +169 -0
- package/src/report.mjs +111 -0
- package/src/sources.mjs +95 -0
- package/src/startup.mjs +184 -0
- package/src/store.mjs +70 -0
- package/src/trim.mjs +312 -0
- package/src/usage.mjs +233 -0
package/src/trim.mjs
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import { join } from 'node:path';
|
|
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 { homedir } from 'node:os';
|
|
4
|
+
import { basename, join } from 'node:path';
|
|
5
|
+
import { createInterface } from 'node:readline';
|
|
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;
|