session-meter

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, SessionContextUsage } from 'claude-code'
3
4import type { CacheReading, ContextReading } from '../types'
5
6const context = atom({ plugin: 'session-meter', key: 'context' } as const, null)
7const cache = atom({ plugin: 'session-meter', key: 'cache' } as const, null)
8const now = atom({ plugin: 'session-meter', key: 'now' } as const, 0)
9
10const TICK_MS = 15_000
11// Label and bar in fixed cells, shared with usage-meter, so the bars line up in any font.
12const LABEL_CELLS = 9
13const BAR_TRACK = '#3a3a3a'
14const HOUR_MS = 60 * 60_000
15const FIVE_MIN_MS = 5 * 60_000
16
17function toReading(c: SessionContextUsage): ContextReading {
18  return { tokens: c.tokens, window: c.window, percent: c.percent }
19}
20
21async function tick($: EngineInterface) {
22  try {
23    const t = await $.clock.now()
24    await update($, now, () => t)
25  } catch {
26    // A missed tick only delays the countdowns by one period.
27  }
28}
29
30function formatTokens(n: number): string {
31  if (n >= 1_000_000) {
32    return `${(n / 1_000_000).toFixed(n >= 10_000_000 ? 0 : 1)}M`
33  }
34
35  return n >= 1_000 ? `${Math.round(n / 1_000)}k` : `${n}`
36}
37
38function formatDuration(ms: number): string {
39  const totalSeconds = Math.max(0, Math.ceil(ms / 1_000))
40  const totalMinutes = Math.floor(totalSeconds / 60)
41  const hours = Math.floor(totalMinutes / 60)
42
43  if (hours > 0) {
44    return `${hours}h ${totalMinutes % 60}m`
45  }
46
47  return totalMinutes >= 1 ? `${totalMinutes}m` : `${totalSeconds}s`
48}
49
50function levelColor(percent: number): string {
51  return percent >= 80 ? 'red' : percent >= 50 ? 'yellow' : 'green'
52}
53
54export const register: Register = (on, options) => {
55  const ttlMs = options.cacheTtl === '5m' ? FIVE_MIN_MS : HOUR_MS
56
57  on('session.start', async ($, e, next) => {
58    const started = await next(e)
59
60    const usage = await $.session.usage()
61    await update($, context, () => toReading(usage.context))
62
63    await tick($)
64    $.clock.every(TICK_MS, () => void tick($))
65
66    return started
67  })
68
69  // A resumed session (a restart included) picks up the cache where the transcript left it.
70  on('classic.SessionStart', async ($, e, next) => {
71    const seconds = e.seconds_since_last_response
72    if ((e.source === 'resume' || e.source === 'fork') && seconds !== undefined) {
73      const reading: CacheReading = {
74        lastAt: (await $.clock.now()) - seconds * 1_000,
75        readTokens: e.context_tokens ?? 0,
76        writeTokens: 0,
77        inputTokens: 0,
78      }
79      const current = await read($, cache)
80      if (current === null || current.lastAt < reading.lastAt) {
81        await update($, cache, () => reading)
82      }
83    }
84
85    return next(e)
86  })
87
88  // A /clear starts a new conversation: the old cache entry no longer applies.
89  on('session.end', async ($, e, next) => {
90    if (e.reason === 'clear') {
91      await update($, cache, () => null)
92    }
93
94    return next(e)
95  })
96
97  on('session.measure', async ($, e, next) => {
98    if (e.changed.includes('context')) {
99      await update($, context, () => toReading(e.context))
100    }
101
102    return next(e)
103  })
104
105  // Every main-thread API response restarts the cache's TTL.
106  on('turn.step', async function* ($, e, next) {
107    const result = yield* next(e)
108
109    if (!e.agentId && result.usage) {
110      const u = result.usage
111      const reading: CacheReading = {
112        lastAt: await $.clock.now(),
113        readTokens: u.cache_read_input_tokens,
114        writeTokens: u.cache_creation_input_tokens,
115        inputTokens: u.input_tokens,
116      }
117      await update($, cache, () => reading)
118      await update($, now, () => reading.lastAt)
119    }
120
121    return result
122  })
123
124  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
125    const below = await next(e)
126    if (e.props.hasSurvey) {
127      return below
128    }
129
130    const ctx = await read($, context)
131    const c = await read($, cache)
132    await read($, now) // subscribes the band to the countdown ticker
133    const t = await $.clock.now()
134    const { Box, Text } = $.ui.resolve(e)
135
136    const width = Math.max(10, Math.min(24, e.props.bodyColumns - 70))
137
138    const label = (text: string) => (
139      <Box width={LABEL_CELLS} flexShrink={0}>
140        <Text bold>{text}</Text>
141      </Box>
142    )
143
144    // Solid cells, not glyphs: a proportional font draws █ and ░ wider than a cell.
145    const bar = (percent: number, color: string) => {
146      const filled = Math.round((Math.max(0, Math.min(percent, 100)) / 100) * width)
147      const parts = []
148      if (filled > 0) {
149        parts.push(
150          <Box width={filled} flexShrink={0} backgroundColor={color}>
151            <Text>{' '.repeat(filled)}</Text>
152          </Box>,
153        )
154      }
155      if (filled < width) {
156        parts.push(
157          <Box width={width - filled} flexShrink={0} backgroundColor={BAR_TRACK}>
158            <Text>{' '.repeat(width - filled)}</Text>
159          </Box>,
160        )
161      }
162
163      return (
164        <Box width={width} flexShrink={0} overflow="hidden">
165          {parts}
166        </Box>
167      )
168    }
169
170    const pct = ctx?.percent
171    const ctxColor = pct === undefined ? 'gray' : levelColor(pct)
172    const ctxText =
173      ctx === null || pct === undefined
174        ? ' no reading yet'
175        : ` ${pct}% · ${formatTokens(ctx.tokens ?? 0)} / ${formatTokens(ctx.window)}`
176
177    const leftMs = c === null ? 0 : c.lastAt + ttlMs - t
178    const isLive = leftMs > 0
179    const cacheColor = !isLive ? 'red' : leftMs > 5 * 60_000 ? 'green' : 'yellow'
180    const cacheText = isLive
181      ? ` · cold in ${formatDuration(leftMs)}`
182      : c === null
183        ? ''
184        : ` · re-caches ~${formatTokens(c.readTokens + c.writeTokens)} next message`
185
186    const mine = (
187      <Box>
188        {label('context')}
189        {bar(pct ?? 0, ctxColor)}
190        <Text color={ctxColor} bold>
191          {ctxText}
192        </Text>
193        <Text dimColor> │ </Text>
194        <Text bold>cache </Text>
195        <Text color={cacheColor} bold>
196          {isLive ? '● live' : '○ cold'}
197        </Text>
198        <Text dimColor>{cacheText}</Text>
199      </Box>
200    )
201
202    // Stack above any band another plugin drew beneath this one.
203    return below.type === 'engine' ? mine : (
204      <Box flexDirection="column">
205        {mine}
206        {below}
207      </Box>
208    )
209  })
210}
211

1export type ContextReading = {
2  /** Input tokens the last response was answered over; absent before the first response. */
3  tokens?: number
4  /** The model's context window, in tokens. */
5  window: number
6  /** `tokens` over `window`, 0 to 100; absent before the first response. */
7  percent?: number
8}
9
10export type CacheReading = {
11  /** When the last main-thread response arrived, epoch ms. */
12  lastAt: number
13  /** Input tokens that response read from the prompt cache. */
14  readTokens: number
15  /** Input tokens that response wrote to the prompt cache. */
16  writeTokens: number
17  /** Uncached input tokens of that response. */
18  inputTokens: number
19}
20
21declare module 'claude-code' {
22  interface PluginState {
23    'session-meter': {
24      context: ContextReading | null
25      cache: CacheReading | null
26      now: number
27    }
28  }
29}
30