ledger-widget

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, Register, RenderElement, RenderSurface } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import { fit, folder, plural } from './lib'
6
7type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text'>
8type Entry = { usd: number | null; at: number; size: number; isOurs: boolean }
9type Sessions = Record<string, Entry>
10type View = { key: string; name: string; roots: string[]; id: string; sessions: Sessions; scannedAt: number; fault: boolean }
11type Kept = { sessions: Sessions; scannedAt: number }
12type Book = { projects: Record<string, unknown> }
13type Saved = { id: string; path: string; size: number; mtimeMs: number; isExact: boolean }
14type Tally = { isEmpty: boolean; total: number; counted: number; since: number | null; unpriced: number; long: number; mine: number }
15
16const PANE = 'widgets'
17const CARD_COLUMNS = 40
18const LONG_COLUMNS = 36
19const USAGE = 'Usage: /ledger-widget [on|off|scan|show|clear]'
20const OFF = 'Ledger is off.'
21const FILE = 'ledger.json'
22const GIT_MS = 3000
23const MAX_READ = 3_500_000
24const MAX_SCAN = 40_000_000
25const WORKTREE = 'worktree '
26const COST = '"type":"cost-state"'
27const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] as const
28const EMPTY = ['Nothing counted yet.', "Each turn's cost is added here.", "/ledger-widget scan adds this project's saved sessions."] as const
29const BLANK: View = { key: '', name: '', roots: [], id: '', sessions: {}, scannedAt: 0, fault: false }
30const site = { plugin: 'widgets', key: 'site' } as const
31const widths = { plugin: 'widgets', key: 'widths' } as const
32const isOn = atom({ plugin: 'ledger-widget', key: 'isOn' } as const, false)
33const view = atom({ plugin: 'ledger-widget', key: 'view' } as const, BLANK)
34
35const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
36
37const isAmount = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0
38
39const parsed = (line: string): Record<string, unknown> | undefined => {
40  try {
41    const value: unknown = JSON.parse(line)
42
43    return isRecord(value) ? value : undefined
44  } catch {
45    return undefined
46  }
47}
48
49const bookOf = (text: string): Book => {
50  const projects = parsed(text)?.projects
51
52  return { projects: isRecord(projects) ? projects : {} }
53}
54
55const keptOf = (book: Book, key: string): Kept => {
56  const raw = book.projects[key]
57  if (!isRecord(raw) || !isRecord(raw.sessions)) return { sessions: {}, scannedAt: 0 }
58
59  const sessions: Sessions = {}
60  for (const [id, entry] of Object.entries(raw.sessions)) {
61    if (!isRecord(entry)) continue
62    const { usd, at, size, isOurs } = entry
63    if ((usd === null || isAmount(usd)) && isAmount(at) && isAmount(size) && typeof isOurs === 'boolean') sessions[id] = { usd, at, size, isOurs }
64  }
65
66  return { sessions, scannedAt: isAmount(raw.scannedAt) ? raw.scannedAt : 0 }
67}
68
69const enc = (path: string): string => path.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase()
70
71const isWithin = (cwd: string, roots: readonly string[]): boolean =>
72  roots.some(root => folder(cwd) === folder(root) || folder(cwd).startsWith(`${folder(root)}/`))
73
74const money = (usd: number): string => {
75  const cents = Math.round(usd * 100) / 100
76
77  return cents < 100 ? `$${cents.toFixed(2)}` : `$${String(Math.round(usd)).replace(/\B(?=(\d{3})+$)/g, ',')}`
78}
79
80const dated = (at: number): string => {
81  const day = new Date(at)
82
83  return `${day.getDate()} ${MONTHS[day.getMonth()]} ${day.getFullYear()}`
84}
85
86const tallied = ({ sessions, id }: View): Tally => {
87  const ours = Object.values(sessions).filter(entry => entry.isOurs)
88  const counted = ours.flatMap(({ usd, at }) => (usd === null ? [] : [{ usd, at }]))
89  const blank = ours.filter(entry => entry.usd === null)
90  const long = blank.filter(entry => entry.size > MAX_READ).length
91
92  return {
93    isEmpty: ours.length === 0,
94    total: counted.reduce((sum, entry) => sum + entry.usd, 0),
95    counted: counted.length,
96    since: counted.reduce<number | null>((least, entry) => (least === null || entry.at < least ? entry.at : least), null),
97    unpriced: blank.length - long,
98    long,
99    mine: sessions[id]?.usd ?? 0,
100  }
101}
102
103const summary = (held: View): string => {
104  const { total, counted, since, unpriced, long } = tallied(held)
105  const priced = since === null ? `Nothing counted yet for ${held.name}.` : `${money(total)} over ${plural(counted, 'session')} since ${dated(since)}.`
106
107  return `${priced}${unpriced > 0 ? ` ${unpriced} without a cost record.` : ''}${long > 0 ? ` ${long} too long to read.` : ''}`
108}
109
110const savedOf = (text: string, fallback: number): { cwd: string | undefined; start: number; usd: number | undefined } => {
111  const lines = text.split('\n')
112  let first: Record<string, unknown> | undefined
113  for (const line of lines) {
114    const row = line.includes('"cwd"') ? parsed(line) : undefined
115    if (typeof row?.cwd !== 'string') continue
116    first = row
117    break
118  }
119  let usd: number | undefined
120  for (let at = lines.length - 1; at >= 0 && usd === undefined; at -= 1) {
121    const cost = lines[at]?.includes(COST) === true ? parsed(lines[at] ?? '')?.totalCostUSD : undefined
122    if (isAmount(cost)) usd = cost
123  }
124  const start = typeof first?.timestamp === 'string' ? Date.parse(first.timestamp) : Number.NaN
125
126  return { cwd: typeof first?.cwd === 'string' ? first.cwd : undefined, start: isAmount(start) ? start : fallback, usd }
127}
128
129const load = async ($: EngineInterface): Promise<Book> => bookOf(await $.fs.read(`${$.plugin.root}/${FILE}`).catch(() => ''))
130
131const save = async ($: EngineInterface, projects: Record<string, unknown>): Promise<void> => {
132  await $.fs.write(`${$.plugin.root}/${FILE}`, JSON.stringify({ projects })).catch(() => undefined)
133}
134
135const refresh = async ($: EngineInterface): Promise<View> => {
136  const book = await load($)
137
138  return update($, view, held => ({ ...(held ?? BLANK), ...keptOf(book, (held ?? BLANK).key) }))
139}
140
141const open = async ($: EngineInterface): Promise<void> => {
142  if ((await read($, view)).key === '') {
143    const root = await $.session.root()
144    const listed = await $.process
145      .run(['git', '--no-optional-locks', 'worktree', 'list', '--porcelain'], { cwd: root, timeoutMs: GIT_MS })
146      .catch(() => undefined)
147    const found =
148      listed === undefined || listed.exitCode !== 0 || listed.isStdoutTruncated
149        ? []
150        : listed.stdout
151            .split('\n')
152            .filter(line => line.startsWith(WORKTREE))
153            .map(line => line.slice(WORKTREE.length).replace(/\r$/, ''))
154            .filter(path => path !== '')
155    const roots = found.length > 0 ? found : [root]
156    const main = roots[0] ?? root
157    const id = await $.session.id().catch(() => '')
158    const name = main.replace(/[\\/]+$/, '').split(/[\\/]/).pop() || main
159    await update($, view, held => ({ ...(held ?? BLANK), key: folder(main) || main, name, roots, id }))
160  }
161  await refresh($)
162}
163
164const measure = async ($: EngineInterface): Promise<void> => {
165  const { key, id } = await read($, view)
166  if (key === '' || id === '') return
167
168  const usd = (await $.session.usage().catch(() => undefined))?.cost?.usd
169  if (!isAmount(usd)) return
170
171  const now = await $.clock.now()
172  const book = await load($)
173  const { sessions, scannedAt } = keptOf(book, key)
174  const kept = sessions[id]
175  const entry: Entry = { usd: Math.max(kept?.usd ?? 0, usd), at: kept?.at ?? now, size: kept?.size ?? 0, isOurs: true }
176  const next = { sessions: { ...sessions, [id]: entry }, scannedAt }
177  await save($, { ...book.projects, [key]: next })
178  await update($, view, held => ({ ...(held ?? BLANK), ...next }))
179}
180
181const failed = async ($: EngineInterface, text: string): Promise<string> => {
182  await update($, view, held => ({ ...(held ?? BLANK), fault: true }))
183
184  return text
185}
186
187const scan = async ($: EngineInterface): Promise<string> => {
188  const { key, name, roots } = await read($, view)
189  const config = await $.env.get('CLAUDE_CONFIG_DIR').catch(() => undefined)
190  const home = config || (await $.env.get('HOME').catch(() => undefined)) || (await $.env.get('USERPROFILE').catch(() => undefined))
191  if (!home) return failed($, 'Could not find where sessions are saved.')
192
193  const base = config ? `${config}/projects` : `${home}/.claude/projects`
194  const folders = await $.fs.list(base).catch(() => undefined)
195  if (folders === undefined) return failed($, `Could not read ${base}.`)
196
197  const now = await $.clock.now()
198  const book = await load($)
199  const sessions = { ...keptOf(book, key).sessions }
200  const names = roots.map(enc)
201  const fresh: Saved[] = []
202  for (const entry of folders) {
203    const lower = entry.name.toLowerCase()
204    const isExact = names.includes(lower)
205    if (entry.kind === 'file' || !(isExact || names.some(start => lower.startsWith(`${start}-`)))) continue
206
207    const files = await $.fs.list(`${base}/${entry.name}`).catch(() => [])
208    for (const file of files) {
209      if (file.kind !== 'file' || !file.name.endsWith('.jsonl')) continue
210      const id = file.name.slice(0, -'.jsonl'.length)
211      const kept = sessions[id]
212      if (kept?.size === file.size) continue
213      if (file.size <= MAX_READ) fresh.push({ id, path: `${base}/${entry.name}/${file.name}`, size: file.size, mtimeMs: file.mtimeMs, isExact })
214      else if (isExact) sessions[id] = { usd: kept?.usd ?? null, at: kept?.at ?? file.mtimeMs, size: file.size, isOurs: true }
215    }
216  }
217
218  fresh.sort((one, other) => other.mtimeMs - one.mtimeMs)
219  let spent = 0
220  let count = 0
221  let reached = 0
222  for (const { id, path, size, mtimeMs } of fresh) {
223    if (reached > 0 && spent + size > MAX_SCAN) break
224    reached += 1
225    spent += size
226    const text = await $.fs.read(path).catch(() => undefined)
227    if (text === undefined) continue
228
229    count += 1
230    const kept = sessions[id]
231    const { cwd, start, usd } = savedOf(text, mtimeMs)
232    if (cwd !== undefined && isWithin(cwd, roots)) {
233      sessions[id] = { usd: usd === undefined ? (kept?.usd ?? null) : Math.max(kept?.usd ?? 0, usd), at: Math.min(kept?.at ?? start, start), size, isOurs: true }
234    } else {
235      sessions[id] = kept?.isOurs === true ? { ...kept, size } : { usd: null, at: mtimeMs, size, isOurs: false }
236    }
237  }
238
239  const next = { sessions, scannedAt: now }
240  await save($, { ...book.projects, [key]: next })
241  const held = await update($, view, old => ({ ...(old ?? BLANK), ...next, fault: false }))
242  const waiting = fresh.length - reached
243
244  return [`Read ${plural(count, 'saved session')} of ${name}.`, summary(held), ...(waiting > 0 ? [`${waiting} more to read: run scan again.`] : [])].join('\n')
245}
246
247const tell = async ($: EngineInterface): Promise<string> => {
248  const held = await refresh($)
249
250  return [
251    `${held.name} (${held.roots[0] ?? ''})`,
252    summary(held),
253    `This session: ${money(tallied(held).mine)}`,
254    ...(held.scannedAt === 0 ? ['Saved sessions not read yet: /ledger-widget scan'] : []),
255  ].join('\n')
256}
257
258const wipe = async ($: EngineInterface): Promise<string> => {
259  const { key, name } = await read($, view)
260  const book = await load($)
261  await save($, Object.fromEntries(Object.entries(book.projects).filter(([other]) => other !== key)))
262  await update($, view, held => ({ ...(held ?? BLANK), sessions: {}, scannedAt: 0 }))
263
264  return `Ledger cleared for ${name}.`
265}
266
267const wrapped = (sentence: string, inner: number): string[] =>
268  sentence.split(' ').reduce<string[]>((rows, word) => {
269    const last = rows.at(-1)
270
271    return last !== undefined && last.length + 1 + word.length <= inner ? [...rows.slice(0, -1), `${last} ${word}`] : [...rows, word]
272  }, [])
273
274const paired =(left: string, rights: readonly string[], inner: number): { gap: string; right: string } => {
275  const right = rights.find(wanted => left.length + 1 + wanted.length <= inner) ?? ''
276
277  return { gap: ' '.repeat(Math.max(0, inner - left.length - right.length)), right }
278}
279
280const show = async (
281  $: EngineInterface,
282  { Box, Text }: Tags,
283  beneath: RenderElement,
284  place: WidgetsPlace,
285  columns: number,
286): Promise<RenderElement> => {
287  if (!(await read($, isOn))) return beneath
288  if ((await $.state.get(site)).value !== place) return beneath
289
290  const width = fit((await $.state.get(widths)).value?.['ledger-widget'] ?? CARD_COLUMNS, columns)
291  const inner = width - 4
292  const isLong = inner >= LONG_COLUMNS
293  const held = await read($, view)
294  const { isEmpty, total, counted, since, unpriced, long, mine } = tallied(held)
295  const count = plural(counted, 'session')
296  const top = paired(money(total), [count], inner)
297  const spent = `this session ${money(mine)}`
298  const from = paired(spent, since === null ? [] : [`since ${dated(since)}`, dated(since)], inner)
299  const fault = held.fault && (
300    <Text color="yellow" wrap="truncate-end">
301      {isLong ? 'Saved sessions could not be read' : 'scan failed'}
302    </Text>
303  )
304
305  return $.widgets.card({
306    beneath,
307    width,
308    title: 'Ledger',
309    note: held.name,
310    body: isEmpty ? (
311      <Box flexDirection="column">
312        {EMPTY.flatMap((sentence, at) => wrapped(sentence, inner).map(row => ({ row, isDim: at > 0 }))).map(({ row, isDim }, at) => (
313          <Text key={`empty-${at + 1}`} dimColor={isDim} wrap="truncate-end">
314            {row}
315          </Text>
316        ))}
317        {fault}
318      </Box>
319    ) : (
320      <Box flexDirection="column">
321        {isLong ? (
322          <Text wrap="truncate-end">
323            <Text bold>{money(total)}</Text>
324            {top.gap}
325            <Text dimColor>{top.right}</Text>
326          </Text>
327        ) : (
328          <Text bold wrap="truncate-end">
329            {money(total)}
330          </Text>
331        )}
332        {!isLong && (
333          <Text wrap="truncate-end">
334            {count}
335          </Text>
336        )}
337        {isLong ? (
338          <Text wrap="truncate-end">
339            {spent}
340            {from.gap}
341            <Text dimColor>{from.right}</Text>
342          </Text>
343        ) : (
344          <Text wrap="truncate-end">
345            now {money(mine)}
346          </Text>
347        )}
348        {unpriced > 0 && (
349          <Text dimColor wrap="truncate-end">
350            {isLong ? `${unpriced} without a cost record` : `${unpriced} no record`}
351          </Text>
352        )}
353        {long > 0 && (
354          <Text dimColor wrap="truncate-end">
355            {isLong ? `${long} too long to read` : `${long} too long`}
356          </Text>
357        )}
358        {fault ||
359          (held.scannedAt === 0 && (
360            <Text dimColor wrap="truncate-end">
361              {isLong ? '/ledger-widget scan adds saved ones' : 'scan adds more'}
362            </Text>
363          ))}
364      </Box>
365    ),
366  })
367}
368
369export const register: Register = on => {
370  on('session.start', async ($, e, next) => {
371    await $.command.register({
372      name: 'ledger-widget',
373      description: 'Toggle the Ledger card, or scan, show or clear what the project has cost',
374      argumentHint: '[on|off|scan|show|clear]',
375    })
376    if ((await $.store.get('isOn')) === true) {
377      await update($, isOn, () => true)
378      await open($)
379    }
380
381    return next(e)
382  })
383
384  on('command.run', { command: 'ledger-widget' }, async ($, e) => {
385    const arg = e.args.trim().toLowerCase()
386    if (arg === 'scan' || arg === 'show' || arg === 'clear') {
387      if (!(await read($, isOn))) return { text: OFF }
388
389      return { text: await (arg === 'scan' ? scan($) : arg === 'show' ? tell($) : wipe($)) }
390    }
391    if (arg !== '' && arg !== 'on' && arg !== 'off') return { text: USAGE }
392
393    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
394    await $.store.set('isOn', isShown)
395    if (isShown) await open($)
396
397    return { text: isShown ? 'Ledger on; /widgets places it.' : 'Ledger off.' }
398  })
399
400  on('turn.complete', async ($, e, next) => {
401    const done = await next(e)
402    if (e.agentId === undefined && (await read($, isOn))) await measure($)
403
404    return done
405  })
406
407  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
408    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns),
409  )
410
411  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
412    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns),
413  )
414
415  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
416    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80),
417  )
418}
419

1const MIN_CARD = 20
2const BARS = '▁▂▃▄▅▆▇█'
3
4export const fit = (wanted: number, columns: number): number => Math.min(wanted, Math.max(MIN_CARD, columns))
5
6export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
7
8export const span = (ms: number): string => {
9  const seconds = Math.max(0, Math.round(ms / 1000))
10  if (seconds < 60) return `${seconds}s`
11  const minutes = Math.floor(seconds / 60)
12  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`
13  const hours = Math.floor(minutes / 60)
14  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
15
16  return `${Math.floor(hours / 24)}d ${hours % 24}h`
17}
18
19export const spark = (values: readonly number[], width: number): string => {
20  const shown = width > 0 ? values.slice(-width) : []
21  const top = Math.max(...shown, 0)
22
23  return shown
24    .map(value => (top <= 0 ? BARS[0] : BARS[Math.min(BARS.length - 1, Math.round((Math.max(0, value) / top) * (BARS.length - 1)))]))
25    .join('')
26}
27
28export const hash = (text: string): number => {
29  let held = 2166136261
30  for (const letter of text) held = Math.imul(held ^ (letter.codePointAt(0) ?? 0), 16777619)
31
32  return held >>> 0
33}
34
35export const shade = (color: number, factor: number): number =>
36  (Math.round((color >> 16) * factor) << 16) |
37  (Math.round(((color >> 8) & 255) * factor) << 8) |
38  Math.round((color & 255) * factor)
39
40export const folder = (path: string): string => {
41  const flat = path.replaceAll('\\', '/').replace(/\/+$/, '')
42
43  return /^[a-z]:/i.test(flat) ? flat.toLowerCase() : flat
44}
45

1export type LedgerSwitch = boolean
2
3declare module 'claude-code' {
4  interface PluginState {
5    'ledger-widget': {
6      isOn: LedgerSwitch
7      view: {
8        key: string
9        name: string
10        roots: string[]
11        id: string
12        sessions: Record<string, { usd: number | null; at: number; size: number; isOurs: boolean }>
13        scannedAt: number
14        fault: boolean
15      }
16    }
17  }
18}
19