context-band

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { formatTokens, headerOf, labelOf, layoutBar, legendRows, toSnapshot } from './view'
5
6const snapshot = atom({ plugin: 'context-band', key: 'snapshot' } as const, null)
7
8// summary는 로컬 추정이라 API 호출이 없다. 실패하면 band는 직전 값을 그대로 보여준다.
9const refresh = async ($: EngineInterface): Promise<void> => {
10  try {
11    const { context } = await $.session.usage({ breakdown: 'summary' })
12    if (!context.breakdown) return
13    const value = toSnapshot(context.breakdown)
14    await update($, snapshot, () => value)
15  } catch {
16    // 세션이 아직 묶이지 않은 시점 등
17  }
18}
19
20export const register: Register = on => {
21  on('session.start', async ($, e, next) => {
22    const result = await next(e)
23    await refresh($)
24    return result
25  })
26
27  on('turn.complete', async ($, e, next) => {
28    const result = await next(e)
29    await refresh($)
30    return result
31  })
32
33  // 압축을 막는 일이 없도록, 실패하면 재생 안전한 next로 원래 결과를 돌려준다.
34  on('session.compact', async ($, e, next) => {
35    const result = await next(e)
36    await refresh($)
37    return result
38  }).catch(($, e, next) => next(e))
39
40  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
41    const snap = await read($, snapshot)
42    if (e.props.hasSurvey || snap === null) {
43      return next(e)
44    }
45
46    const { Box, Text } = $.ui.resolve(e)
47
48    // 터미널은 글자 한 개가 한 칸이라 █를 칸 수만큼 잇는다.
49    // Desktop은 글꼴 폭이 칸과 달라 글자 막대가 넘쳐 접히므로, 배경색 Box를 토큰 비율로 나눈다.
50    // flexGrow는 10000 이하만, 퍼센트 폭은 소수점 없이만 받아서 만분율 정수로 넣는다.
51    const sum = snap.rows.reduce((acc, r) => acc + r.tokens, 0) || 1
52    const bar =
53      e.surface === 'terminal' ? (
54        <Box key="bar">
55          {layoutBar(snap.rows, Math.max(10, e.props.bodyColumns)).map((s, i) => (
56            <Text key={`bar-${i}`} color={s.color}>
57              {'█'.repeat(s.width)}
58            </Text>
59          ))}
60        </Box>
61      ) : (
62        <Box key="bar" width="100%" height={1}>
63          {snap.rows.map(r => (
64            <Box
65              key={`bar-${r.name}`}
66              flexGrow={Math.round((r.tokens / sum) * 10000)}
67              width={0}
68              height={1}
69              backgroundColor={r.color}
70            />
71          ))}
72        </Box>
73      )
74
75    return (
76      <Box flexDirection="column">
77        <Text>
78          <Text bold>컨텍스트</Text> <Text dimColor>{headerOf(snap)}</Text>
79        </Text>
80        {bar}
81        <Box key="legend" flexWrap="wrap">
82          {legendRows(snap.rows).map(r => (
83            <Box key={`legend-${r.name}`} marginRight={2}>
84              <Text color={r.color}>■ </Text>
85              <Text dimColor>
86                {labelOf(r.name)} {formatTokens(r.tokens)}
87              </Text>
88            </Box>
89          ))}
90        </Box>
91      </Box>
92    )
93  })
94}
95

1import type { SessionContextBreakdown } from 'claude-code'
2
3import type { ContextRow, ContextSnapshot } from '../types'
4
5// /context가 쓰는 영문 행 이름 → band 라벨. 모르는 이름은 원문 그대로 둔다.
6const LABELS: Record<string, string> = {
7  'System prompt': '시스템 프롬프트',
8  'System tools': '시스템 도구',
9  'MCP tools': 'MCP 도구',
10  'MCP server instructions': 'MCP 서버 지침',
11  'Custom agents': '커스텀 에이전트',
12  'Memory files': '메모리 파일',
13  Skills: '스킬',
14  Messages: '대화',
15  'Free space': '남은 공간',
16  'Autocompact buffer': '자동 압축 예비 공간',
17}
18
19export const labelOf = (name: string): string => LABELS[name] ?? name
20
21// deferred 행은 필요할 때만 불러오는 도구 스키마라 창을 차지하지 않으므로 뺀다.
22export const toSnapshot = (b: SessionContextBreakdown): ContextSnapshot => ({
23  model: b.model,
24  totalTokens: b.totalTokens,
25  maxTokens: b.rawMaxTokens,
26  percentage: b.percentage,
27  rows: b.categories.flatMap(c =>
28    c.kind === 'deferred' ? [] : [{ name: c.name, tokens: c.tokens, color: c.color, kind: c.kind }],
29  ),
30})
31
32const trim = (n: number): string => n.toFixed(1).replace(/\.0$/, '')
33
34export const formatTokens = (n: number): string => {
35  if (n < 1000) return String(Math.round(n))
36  if (n < 1_000_000) return `${trim(n / 1000)}k`
37  return `${trim(n / 1_000_000)}m`
38}
39
40// 2k 이하 분류는 막대에서 거의 보이지 않아 색으로 구분되지 않으므로 범례에서도 뺀다.
41export const LEGEND_MIN_TOKENS = 2_000
42
43export const legendRows = (rows: ContextRow[]): ContextRow[] =>
44  rows.filter(r => r.tokens > LEGEND_MIN_TOKENS)
45
46export type Segment = { color: string; width: number }
47
48// 누적 경계를 반올림해 나누므로 칸 수의 합이 항상 width와 같다. 0칸인 분류는 막대에서 빠진다.
49export const layoutBar = (rows: ContextRow[], width: number): Segment[] => {
50  const sum = rows.reduce((acc, r) => acc + r.tokens, 0)
51  if (sum <= 0) return []
52
53  let cum = 0
54  const segments = rows.map(r => {
55    const start = Math.round((cum / sum) * width)
56    cum += r.tokens
57    const end = Math.round((cum / sum) * width)
58    return { color: r.color, width: end - start }
59  })
60  return segments.filter(s => s.width > 0)
61}
62
63export const headerOf = (s: ContextSnapshot): string => {
64  const free = s.rows.find(r => r.kind === 'free')
65  const parts = [`${formatTokens(s.totalTokens)} / ${formatTokens(s.maxTokens)} (${s.percentage}%)`]
66  if (free) parts.push(`남은 공간 ${formatTokens(free.tokens)}`)
67  parts.push(s.model)
68  return parts.join(' · ')
69}
70

1export type ContextRow = {
2  name: string
3  tokens: number
4  color: string
5  kind: 'used' | 'free' | 'buffer'
6}
7
8export type ContextSnapshot = {
9  model: string
10  totalTokens: number
11  maxTokens: number
12  percentage: number
13  rows: ContextRow[]
14}
15
16declare module 'claude-code' {
17  interface PluginState {
18    'context-band': { snapshot: ContextSnapshot | null }
19  }
20}
21