openrouter-balance

1// OpenRouter Balance: your OpenRouter credit, in a band above the prompt.
2// A management key sees the account: the real balance from /credits, and spend by model from /activity.
3// A regular API key sees only itself: its spend today and this month, and what its limit leaves.
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register, Timer } from 'claude-code'
6
7import type { Line } from '../types'
8
9const EVERY_MS = 5 * 60 * 1000 // the balance is live, but nobody needs it by the second
10const TICK_MS = 60 * 1000 // the timer checks every minute; nextTry decides whether to ask
11const RETRY_MS = 60 * 1000 // after a failed refresh
12const STUCK_MS = 2 * 60 * 1000 // a refresh still running after this is given up on (fetch has no timeout)
13const ACTIVITY_MS = 60 * 60 * 1000 // /activity holds completed days only, so once an hour is plenty
14const GRACE_S = 15 * 60 // a day first seen this soon after midnight UTC counts as seen from its start
15const KEYCHAIN_SERVICE = 'openrouter-key'
16const API = 'https://openrouter.ai/api/v1'
17const DAY_S = 86_400
18const LOW = 2 // dollars: red below this
19const MID = 5 // dollars: yellow below this
20const BRAND = '#8b9cff' // periwinkle: apart from the green gauge and openai-balance's violet
21const GAUGE = 10
22const EMPTY: Line = { kind: null, left: null, start: null, today: null, month: null, since: null, top: null, error: null, isLoaded: false, hasData: false }
23const SETUP =
24  'Needs an OpenRouter key. A **management key** (openrouter.ai → Settings → Management keys) shows the account balance and spend by model; a regular API key shows its own spend and limit. Put it in `/config` → openrouter-balance, or in `OPENROUTER_MANAGEMENT_KEY` or `OPENROUTER_API_KEY`, or on macOS in Keychain: `security add-generic-password -a "$USER" -s openrouter-key -w`.'
25
26// The account's all-time usage when this UTC day was first seen, so today's spend is the difference.
27type Mark = { day: number; usage: number; at: number }
28type Activity = { date: string; model: string; usage: number; requests: number; prompt_tokens: number; completion_tokens: number }
29
30// Held by the host, so the line survives a hot reload of this file.
31const line = atom({ plugin: 'openrouter-balance', key: 'line' } as const, EMPTY)
32
33let timers: Timer[] = [] // restarted on each session.start
34let configKey = ''
35let key = '' // kept in memory only, never in state, the store or a message
36let nextTry = 0
37let generation = 0 // a newer refresh wins; an older one that ends later is dropped
38let running: { since: number } | null = null
39let activityCache: { at: number; items: Promise<Activity[]> } | null = null
40let lastKey = '' // the key the cached numbers came from, in memory only
41
42class NoKey extends Error {}
43class KeyRejected extends Error {}
44class HttpError extends Error {
45  constructor(readonly status: number) {
46    super(`OpenRouter answered ${status}`)
47  }
48}
49
50export const register: Register = (on, options) => {
51  configKey = typeof options.apiKey === 'string' ? options.apiKey.trim() : ''
52  key = '' // a key changed in /config is read again
53
54  on('session.start', async ($, e, next) => {
55    const result = await next(e)
56    await $.command
57      .register({ name: 'openrouter-balance', description: 'OpenRouter credit, spend today and spend by model' })
58      .catch(() => {}) // a name Claude Code already has is refused: start anyway
59    void refresh($, true).catch(() => {}) // in the background: a slow API never holds up the session
60    for (const t of timers) t.cancel()
61    timers = [$.clock.every(TICK_MS, () => void refresh($, false).catch(() => {}))]
62    return result
63  })
64
65  on('turn.complete', async ($, e, next) => {
66    const result = await next(e)
67    if (!e.agentId) void refresh($, false).catch(() => {}) // main-loop turns only, not subagents
68    return result
69  })
70
71  on('command.run', { command: 'openrouter-balance' }, async $ => {
72    try {
73      return { text: await detail($) }
74    } catch (err) {
75      return { text: problem(err) }
76    }
77  })
78
79  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
80    const rest = await next(e) // what other mods and Claude Code draw here stays
81    const now = { ...EMPTY, ...(await read($, line)) } // a value an older version saved may lack a field
82    if (e.props.hasSurvey || !now.isLoaded) return rest
83
84    const { Box, Text } = $.ui.resolve(e)
85    const isWide = e.props.bodyColumns >= 60
86    const sep = <Text dimColor>{' · '}</Text>
87    const head = <Text color={BRAND} bold>{'◆ OpenRouter  '}</Text>
88    const today = now.today !== null && (
89      <Text>
90        <Text bold>{usd(now.today)}</Text>
91        <Text dimColor>{now.since !== null ? ` since ${clock(now.since)}` : ' today'}</Text>
92      </Text>
93    )
94
95    let body
96    if (now.error === 'no-key') body = <Text color="red">no key set, see /openrouter-balance</Text>
97    else if (now.error === 'rejected') body = <Text color="red">key rejected, see /openrouter-balance</Text>
98    else if (!now.hasData) body = <Text dimColor>{"can't reach OpenRouter yet"}</Text>
99    else if (now.left === null) {
100      // A regular key with no limit: its spend is all there is to show.
101      body = (
102        <Text>
103          {today}
104          {now.month !== null && sep}
105          {now.month !== null && <Text bold>{usd(now.month)}</Text>}
106          {now.month !== null && <Text dimColor>{' this month'}</Text>}
107          {isWide && sep}
108          {isWide && <Text dimColor>{'a management key shows the balance'}</Text>}
109          {now.error === 'offline' && <Text dimColor>{' · offline'}</Text>}
110        </Text>
111      )
112    } else {
113      const tone = now.left < LOW ? 'red' : now.left < MID ? 'yellow' : 'green'
114      const filled = now.start !== null && now.start > 0 ? Math.max(0, Math.min(GAUGE, Math.round((now.left / now.start) * GAUGE))) : 0
115      const of = now.start !== null ? ` of ${usd(now.start)}${now.kind === 'key' ? ' key limit' : ''}` : ''
116      body = (
117        <Text>
118          {isWide && <Text color={tone}>{'█'.repeat(filled)}</Text>}
119          {isWide && <Text dimColor>{'▁'.repeat(GAUGE - filled)}</Text>}
120          <Text color={tone} bold>{`${isWide ? ' ' : ''}${usd(now.left)}`}</Text>
121          <Text dimColor>{of}{now.left < LOW ? ' left, top up soon' : ' left'}</Text>
122          {today && sep}
123          {today}
124          {isWide && now.top && <Text dimColor>{', mostly '}</Text>}
125          {isWide && now.top && <Text color="cyan">{short(now.top)}</Text>}
126          {now.error === 'offline' && <Text dimColor>{' · offline'}</Text>}
127        </Text>
128      )
129    }
130
131    return (
132      <Box flexDirection="column">
133        <Box paddingX={1}>
134          <Text wrap="truncate-end">
135            {head}
136            {body}
137          </Text>
138        </Box>
139        {rest}
140      </Box>
141    )
142  })
143}
144
145// Updates what the band draws. Every 5 minutes, a minute after a failure, or now when forced.
146async function refresh($: EngineInterface, isForced: boolean) {
147  const now = await $.clock.now()
148  if (!isForced && (now < nextTry || (running && now - running.since < STUCK_MS))) return
149  const mine = ++generation
150  running = { since: now }
151  try {
152    const next = await snapshot($, now)
153    if (mine !== generation) return
154    nextTry = now + EVERY_MS
155    await update($, line, () => next)
156  } catch (err) {
157    if (mine !== generation) return
158    nextTry = now + RETRY_MS // a fixed key or a network back shows within a minute
159    const error: Line['error'] = err instanceof NoKey ? 'no-key' : err instanceof KeyRejected ? 'rejected' : 'offline'
160    await update($, line, l => ({ ...EMPTY, ...l, error, isLoaded: true })) // offline keeps the last numbers, marked
161  } finally {
162    if (mine === generation) running = null
163  }
164}
165
166async function snapshot($: EngineInterface, now: number): Promise<Line> {
167  const info = await keyInfo($)
168  const loaded = { ...EMPTY, isLoaded: true, hasData: true }
169  if (!isManagement(info)) {
170    return { ...loaded, kind: 'key', left: num(info.limit_remaining), start: num(info.limit), today: num(info.usage_daily), month: num(info.usage_monthly) }
171  }
172  const credits = await account($)
173  const mark = await dayMark($, Math.floor(now / 1000), credits.total_usage)
174  const items = await activity($, now).catch(() => []) // a hiccup here never hides the balance
175  return {
176    ...loaded,
177    kind: 'account',
178    left: credits.total_credits - credits.total_usage,
179    start: credits.total_credits,
180    today: Math.max(0, credits.total_usage - mark.usage),
181    since: mark.at - mark.day > GRACE_S ? mark.at : null,
182    top: byModel(items)[0]?.model ?? null,
183  }
184}
185
186// The first all-time usage seen this UTC day. A day first seen late says "since" instead of "today".
187async function dayMark($: EngineInterface, nowS: number, usage: number): Promise<Mark> {
188  const day = dayStart(nowS)
189  const saved = (await $.store.get('mark')) as Mark | undefined
190  if (saved && saved.day === day && typeof saved.usage === 'number') return saved
191  const mark = { day, usage, at: nowS }
192  await $.store.set('mark', mark)
193  return mark
194}
195
196async function detail($: EngineInterface) {
197  const now = await $.clock.now()
198  const info = await keyInfo($)
199  const lines = ['## OpenRouter balance', '']
200
201  if (!isManagement(info)) {
202    lines.push(
203      `A regular API key: it sees only its own spend. A management key shows the account balance.`,
204      '',
205      `- **Today (UTC):** ${usd(num(info.usage_daily) ?? 0)}`,
206      `- **This week:** ${usd(num(info.usage_weekly) ?? 0)}`,
207      `- **This month:** ${usd(num(info.usage_monthly) ?? 0)}`,
208      `- **All time:** ${usd(num(info.usage) ?? 0)}`,
209    )
210    if (num(info.limit) !== null) {
211      const reset = info.limit_reset ? `, resets ${info.limit_reset}` : ''
212      lines.push(`- **Key limit:** ${usd(num(info.limit_remaining) ?? 0)} left of ${usd(info.limit)}${reset}`)
213    } else lines.push('- **Key limit:** none')
214    const b = info.effective_budget
215    if (b && typeof b.limit_usd === 'number') lines.push(`- **Budget:** ${usd(b.remaining_usd ?? 0)} left of ${usd(b.limit_usd)}${b.reset_interval ? ` ${b.reset_interval}` : ''}`)
216    const free = info.free_model_daily_requests
217    if (info.is_free_tier && free) lines.push(`- **Free model requests today:** ${free.remaining} of ${free.limit} left`)
218    return lines.join('\n')
219  }
220
221  const credits = await account($)
222  const mark = await dayMark($, Math.floor(now / 1000), credits.total_usage)
223  const items = await activity($, now)
224  const yesterday = new Date((dayStart(Math.floor(now / 1000)) - DAY_S) * 1000).toISOString().slice(0, 10)
225  const today = Math.max(0, credits.total_usage - mark.usage)
226  lines.push(
227    `- **Balance:** ${usd(credits.total_credits - credits.total_usage)} (${usd(credits.total_credits)} bought, ${usd(credits.total_usage)} used)`,
228    `- **Today (UTC):** ${usd(today)}${mark.at - mark.day > GRACE_S ? ` since ${clock(mark.at)} UTC, when this mod first saw the day` : ''}`,
229    `- **Yesterday:** ${usd(sum(items.filter(i => i.date === yesterday)))}`,
230    `- **Last 30 days:** ${usd(sum(items))}`,
231    '',
232    '**By model, last 30 days**',
233  )
234  const models = byModel(items)
235  if (models.length === 0) lines.push('- none')
236  for (const m of models) lines.push(`- ${m.model}: ${usd4(m.usage)}, ${int(m.requests)} requests, ${int(m.input)} in / ${int(m.output)} out`)
237  lines.push('', '_Spend by model counts completed UTC days only, as OpenRouter reports it. Today is the all-time usage now minus where it stood when the day began._')
238  return lines.join('\n')
239}
240
241// The last 30 days' spend per model, biggest first.
242function byModel(items: Activity[]) {
243  const map = new Map<string, { model: string; usage: number; requests: number; input: number; output: number }>()
244  for (const i of items) {
245    const m = map.get(i.model) ?? { model: i.model, usage: 0, requests: 0, input: 0, output: 0 }
246    m.usage += Number(i.usage) || 0
247    m.requests += Number(i.requests) || 0
248    m.input += Number(i.prompt_tokens) || 0
249    m.output += Number(i.completion_tokens) || 0
250    map.set(i.model, m)
251  }
252  return [...map.values()].filter(m => m.usage > 0).sort((a, b) => b.usage - a.usage)
253}
254
255const sum = (items: Activity[]) => items.reduce((s, i) => s + (Number(i.usage) || 0), 0)
256
257const keyInfo = async ($: EngineInterface) => (await call($, 'key')).data ?? {}
258const account = async ($: EngineInterface) => {
259  const d = (await call($, 'credits')).data ?? {}
260  const total_credits = num(d.total_credits)
261  const total_usage = num(d.total_usage)
262  if (total_credits === null || total_usage === null) throw new Error('OpenRouter sent no credit numbers')
263  return { total_credits, total_usage }
264}
265const isManagement = (info: any) => info.is_management_key === true || info.is_provisioning_key === true
266
267// One lookup shared by concurrent callers, kept an hour. A failed one is tried again next time.
268async function activity($: EngineInterface, now: number): Promise<Activity[]> {
269  if (!activityCache || now - activityCache.at > ACTIVITY_MS) {
270    const entry = {
271      at: now,
272      items: call($, 'activity').then(
273        d => (Array.isArray(d.data) ? d.data : []),
274        err => {
275          if (activityCache === entry) activityCache = null
276          throw err
277        },
278      ),
279    }
280    activityCache = entry
281  }
282  return activityCache.items
283}
284
285async function call($: EngineInterface, path: string) {
286  const res = await $.http.fetch(`${API}/${path}`, { headers: { authorization: `Bearer ${await apiKey($)}` } })
287  if (res.status === 401 || res.status === 403) {
288    key = '' // read it again next time, in case it was replaced
289    throw new KeyRejected()
290  }
291  if (!res.ok) throw new HttpError(res.status)
292  return JSON.parse(res.text)
293}
294
295// From /config first, then OPENROUTER_MANAGEMENT_KEY, OPENROUTER_API_KEY, then the macOS Keychain, and last the
296// same two variables as your login shell sets them: an app started from the Dock never read ~/.zshrc.
297async function apiKey($: EngineInterface) {
298  if (key) return key
299  const run = async (argv: string[], timeoutMs?: number) => {
300    const r = await $.process.run(argv, { timeoutMs }).catch(() => null)
301    return r && r.exitCode === 0 ? r.stdout.trim() : ''
302  }
303  const k =
304    configKey ||
305    (await run(['printenv', 'OPENROUTER_MANAGEMENT_KEY'])) ||
306    (await run(['printenv', 'OPENROUTER_API_KEY'])) ||
307    (await run(['security', 'find-generic-password', '-s', KEYCHAIN_SERVICE, '-w'])) ||
308    fromShell(await run([(await run(['printenv', 'SHELL'])) || '/bin/zsh', '-ilc', SHELL_PRINT], SHELL_MS))
309  if (!k.startsWith('sk-or-')) throw new NoKey()
310  if (lastKey && k !== lastKey) {
311    activityCache = null // another key may be another account: drop its numbers
312    await $.store.set('mark', null).catch(() => {}) // and its start-of-day mark
313  }
314  lastKey = k
315  return (key = k)
316}
317
318// Each variable on its own marked line, so whatever the shell's startup files print is skipped.
319const SHELL_PRINT = 'printf "\\n@or@%s\\n@or@%s\\n" "$OPENROUTER_MANAGEMENT_KEY" "$OPENROUTER_API_KEY"'
320const SHELL_MS = 10_000 // a slow ~/.zshrc must not hold the line up for long
321const fromShell = (out: string) =>
322  out
323    .split('\n')
324    .filter(l => l.startsWith('@or@sk-or-'))
325    .map(l => l.slice(4).trim())[0] ?? ''
326
327function problem(err: unknown) {
328  if (err instanceof NoKey) return `No OpenRouter key found. ${SETUP}`
329  if (err instanceof KeyRejected) return `OpenRouter refused the key (401/403): it may be revoked or disabled. ${SETUP}`
330  return `Couldn't reach OpenRouter: ${err instanceof Error ? err.message : String(err)}`
331}
332
333// A model id without its provider or variant: "anthropic/claude-sonnet-4.5" → "claude-sonnet-4.5",
334// "meta-llama/llama-3.3-70b-instruct:free" → "llama-3.3-70b-instruct".
335const short = (model: string) => model.split('/').pop()!.split(':')[0]
336const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : null)
337const dayStart = (s: number) => s - (s % DAY_S)
338const usd = (n: number) => {
339  const cents = Math.round(n * 100)
340  return `${cents < 0 ? '-' : ''}$${(Math.abs(cents) / 100).toFixed(2)}`
341}
342const usd4 = (n: number) => `$${n.toFixed(4)}`
343const int = (n: number) => Math.round(n).toLocaleString('en-US')
344const clock = (s: number) => {
345  const d = new Date(s * 1000)
346  return `${String(d.getUTCHours()).padStart(2, '0')}:${String(d.getUTCMinutes()).padStart(2, '0')}`
347}
348

1// What the band above the prompt draws.
2export type Line = {
3  kind: 'account' | 'key' | null // a management key sees the account; a regular key only itself
4  left: number | null // account credit, or what the key's limit leaves; null when neither is known
5  start: number | null // credits bought, or the key's limit, for the gauge
6  today: number | null // spend in the current UTC day, null when it can't be told yet
7  month: number | null // the key's spend this UTC month (regular key only)
8  since: number | null // unix seconds: "today" counts from here when the mod first saw the day after it began
9  top: string | null // the model the last 30 days' money mostly went to (management key only)
10  error: 'no-key' | 'rejected' | 'offline' | null // offline keeps the last numbers, marked
11  isLoaded: boolean
12  hasData: boolean // a refresh has succeeded at least once
13}
14
15declare module 'claude-code' {
16  interface PluginState {
17    'openrouter-balance': { line: Line }
18  }
19}
20