skill-bar

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { SkillNames } from '../types'
5import { labelOf, runeOf } from './hotbar-client'
6import type { HotbarProps, HotbarSlot } from './hotbar-client'
7import { PANEL, colorFor, mix, toHex } from './colors'
8
9const skills = atom({ plugin: 'skill-bar', key: 'skills' } as const, [] as SkillNames)
10
11// Project skills only: the folders under .claude/skills that hold a SKILL.md.
12export async function listProjectSkills($: EngineInterface): Promise<string[]> {
13  const root = `${await $.session.cwd()}/.claude/skills`
14  if (!(await $.fs.exists(root))) return []
15  const entries = await $.fs.list(root)
16  const found: string[] = []
17  for (const entry of entries) {
18    if (entry.kind !== 'dir') continue
19    if (await $.fs.exists(`${root}/${entry.name}/SKILL.md`)) found.push(entry.name)
20  }
21  return found.sort((a, b) => a.localeCompare(b))
22}
23
24// The most used skills that get a slot beside the project's own.
25export const FAVORITES = 4
26
27// The slots: the project's skills, then the skills cast most (rpg-hud's lifetime count) that the session still
28// has and the project does not already hold, most used first.
29export const slotsFor = (project: readonly string[], uses: Readonly<Record<string, number>>, known: readonly string[]): string[] => {
30  const favorites = Object.entries(uses)
31    .filter(([name, count]) => count > 0 && known.includes(name) && !project.includes(name))
32    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
33    .slice(0, FAVORITES)
34    .map(([name]) => name)
35  return [...project, ...favorites]
36}
37
38// rpg-hud's skill counts and the session's skills, when that mod runs; nothing otherwise. Read while drawing, so
39// a cast there redraws the slots here. Another plugin's state is read-only, and typed by its own contract.
40async function readFavorites($: EngineInterface) {
41  const [progress, loadout] = await Promise.all([
42    $.state.get({ plugin: 'rpg-hud', key: 'progress' } as never).catch(() => undefined),
43    $.state.get({ plugin: 'rpg-hud', key: 'loadout' } as never).catch(() => undefined),
44  ])
45  const uses = (progress?.value as { skillUses?: Record<string, number> } | undefined)?.skillUses ?? {}
46  const known = ((loadout?.value as { skills?: { name: string }[] } | undefined)?.skills ?? []).map(skill => skill.name)
47  return { uses, known }
48}
49
50// One hotbar slot in its own colour: the keycap in full, the cell a dark tint of it that deepens under the pointer.
51export const hotbarSlot = (name: string, slot: number): HotbarSlot => {
52  const label = labelOf(name)
53  const color = colorFor(slot)
54  return {
55    name,
56    label,
57    rune: runeOf(label),
58    color: toHex(color),
59    tint: toHex(mix(color, PANEL, 0.18)),
60    glow: toHex(mix(color, PANEL, 0.38)),
61  }
62}
63
64// Pressing a slot puts the command in the prompt box, so arguments (an issue number) can follow.
65export const commandText = (skill: string): string => `/${skill} `
66
67async function refresh($: EngineInterface) {
68  const found = await listProjectSkills($).catch(() => [] as string[])
69  await update($, skills, () => found)
70}
71
72export const register: Register = on => {
73  on('session.start', async ($, e, next) => {
74    await refresh($)
75    return next(e)
76  })
77
78  // A /clear starts a new session without session.start; refill the slots for it.
79  on('classic.SessionStart', async ($, e, next) => {
80    if (e.source === 'clear') await refresh($)
81    return next(e)
82  })
83
84  // A new or removed skill folder shows up after the next turn.
85  on('turn.complete', async ($, e, next) => {
86    if (e.agentId === undefined) await refresh($)
87    return next(e)
88  })
89
90  // The hotbar Client posts `{ cast }` when a slot is clicked.
91  on('ui.message', async ($, e, next) => {
92    const data = (e.data ?? {}) as { cast?: unknown }
93    if (e.element !== 'hotbar' || typeof data.cast !== 'string') return next(e)
94    await $.prompt.fill({ text: commandText(data.cast) })
95    return {}
96  })
97
98  // Under the prompt: the engine's hint line first, the item slots below it.
99  on('ui.render', { component: 'PromptHint' }, async ($, e, next) => {
100    const engine = await next(e)
101    const favorites = await readFavorites($)
102    const project = await read($, skills)
103    const names = slotsFor(project, favorites.uses, favorites.known)
104    if (names.length === 0) return engine
105
106    const slots = names.map((name, slot) => hotbarSlot(name, slot))
107    const { Box, Button } = $.ui.resolve(e)
108
109    // The terminal draws an MMO skill bar: a rune keycap and a tinted cell a slot; a click casts it and it cools down.
110    if (e.surface === 'terminal') {
111      const { Client } = $.ui.resolve(e)
112      const hotbar = { slots } satisfies HotbarProps
113      return (
114        <Box flexDirection="column">
115          {engine}
116          <Box marginTop={1}>
117            <Client key="hotbar" module="./hotbar-client.tsx" props={hotbar} width="100%" />
118          </Box>
119        </Box>
120      )
121    }
122
123    // Other surfaces: a button a slot, wearing its rune.
124    return (
125      <Box flexDirection="column">
126        {engine}
127        <Box flexDirection="row" flexWrap="wrap" columnGap={2} marginY={1}>
128          {slots.map(one => (
129            <Button
130              key={one.name}
131              label={`[${one.rune}] ${one.label}`}
132              plain
133              dimColor
134              onPress={() => void $.prompt.fill({ text: commandText(one.name) })}
135            />
136          ))}
137        </Box>
138      </Box>
139    )
140  })
141}
142

1import type { ClientModule } from 'claude-code'
2
3import { PANEL, toHex } from './colors'
4
5export type HotbarSlot = {
6  // The skill's full name, what a cast fills the prompt with.
7  name: string
8  // What the slot shows: the name past any `plugin:` prefix.
9  label: string
10  // The rune on the slot's keycap: the label's first letter or digit.
11  rune: string
12  // The slot's own colour, and its cell at rest and under the pointer, as hex.
13  color: string
14  tint: string
15  glow: string
16}
17
18export type HotbarProps = { slots: HotbarSlot[] }
19
20type HotbarState = {
21  tick: number
22  // The slot under the pointer.
23  hover?: number
24  // The slot just cast and the tick its cooldown began.
25  cast?: { index: number; start: number }
26}
27
28const FRAME_MS = 80
29// How long a cast slot cools down, dark to lit, left to right.
30export const COOLDOWN_TICKS = 15
31// Ticks between the hover sparks' twinkles.
32const TWINKLE_TICKS = 4
33// A slot is one row: `✦▐C▌ label ✦`, the sparks lit only under the pointer.
34export const SLOT_ROWS = 1
35const GAP = 2
36// The longest label a slot shows whole.
37const MAX_LABEL = 18
38// Around the label: spark, keycap (▐ rune ▌), space, space, spark.
39const CHROME = 1 + 3 + 1 + 1 + 1
40// The rune's ink on its coloured keycap, and the cooling cell's.
41const INK = toHex(PANEL)
42const COOLING = '#2a2533'
43// The width laid out before the first layout reports the region's.
44const FALLBACK_COLUMNS = 80
45
46// `name` past its `plugin:` prefix, cut to fit a slot.
47export const labelOf = (name: string): string => {
48  const bare = name.slice(name.lastIndexOf(':') + 1)
49  return bare.length > MAX_LABEL ? `${bare.slice(0, MAX_LABEL - 1)}…` : bare
50}
51
52export const runeOf = (label: string): string => (label.match(/[a-z0-9]/i)?.[0] ?? '?').toUpperCase()
53
54export const slotWidth = (slot: Pick<HotbarSlot, 'label'>): number => slot.label.length + CHROME
55
56// The cell's text while it cools: what has come back shows, the rest is shade, lightest at the sweep's front.
57export const cooldownText = (text: string, elapsed: number): string => {
58  const chars = [...text]
59  const lit = Math.min(chars.length, Math.floor((elapsed / COOLDOWN_TICKS) * chars.length))
60  return chars.map((ch, at) => (at < lit ? ch : at === lit ? '░' : at === lit + 1 ? '▒' : '▓')).join('')
61}
62
63// The slots in lines that fit `columns`: each line as many as fit, a slot wider than the whole bar alone on one.
64export const hotbarLines = (widths: readonly number[], columns: number): { index: number; x: number }[][] => {
65  const lines: { index: number; x: number }[][] = []
66  let line: { index: number; x: number }[] = []
67  let x = 0
68  widths.forEach((width, index) => {
69    if (line.length > 0 && x + width > columns) {
70      lines.push(line)
71      line = []
72      x = 0
73    }
74    line.push({ index, x })
75    x += width + GAP
76  })
77  if (line.length > 0) lines.push(line)
78  return lines
79}
80
81const Hotbar: ClientModule<HotbarProps, HotbarState> = (props, surface) => {
82  const { Box, Text } = surface.elements
83  if (surface.state === undefined) {
84    // Frames since the sparks last twinkled, while nothing cools.
85    let idle = 0
86    surface.every(FRAME_MS, () => {
87      const now = surface.state
88      // Only a cooldown or a hovered slot's sparks move; at rest nothing redraws.
89      if (now === undefined || (now.cast === undefined && now.hover === undefined)) return
90      // Sparks alone change once a twinkle: skip the frames between, then step the clock a whole twinkle.
91      if (now.cast === undefined) {
92        idle += 1
93        if (idle < TWINKLE_TICKS) return
94        idle = 0
95        surface.setState({ ...now, tick: now.tick + TWINKLE_TICKS })
96        return
97      }
98      const isCool = now.cast !== undefined && now.tick + 1 - now.cast.start >= COOLDOWN_TICKS
99      surface.setState({ ...now, tick: now.tick + 1, ...(isCool ? { cast: undefined } : {}) })
100    })
101    surface.setState({ tick: 0 })
102  }
103  const state = surface.state ?? { tick: 0 }
104  const widths = props.slots.map(slotWidth)
105  const lines = hotbarLines(widths, surface.columns > 0 ? surface.columns : FALLBACK_COLUMNS)
106
107  const cast = (index: number) => {
108    const slot = props.slots[index]
109    if (slot === undefined) return
110    surface.setState({ ...state, cast: { index, start: state.tick } })
111    surface.post({ cast: slot.name })
112  }
113
114  const slotAt = (x: number, y: number): number | undefined =>
115    lines[Math.floor(y / SLOT_ROWS)]?.find(one => x >= one.x && x < one.x + (widths[one.index] ?? 0))?.index
116
117  surface.onPointer(e => {
118    const index = e.type === 'leave' ? undefined : slotAt(e.x, e.y)
119    if (e.type === 'up' && e.button === 'left' && index !== undefined) return cast(index)
120    if (state.hover !== index && e.type !== 'down') surface.setState({ ...state, hover: index })
121  })
122
123  const drawSlot = (slot: HotbarSlot, index: number) => {
124    const elapsed = state.cast?.index === index ? state.tick - state.cast.start : undefined
125    const isCooling = elapsed !== undefined
126    const isHover = !isCooling && state.hover === index
127    const spark = isHover ? (Math.floor(state.tick / TWINKLE_TICKS) % 2 === 0 ? '✦' : '✧') : ' '
128    const cap = isCooling ? COOLING : slot.color
129    const cell = isCooling ? COOLING : isHover ? slot.glow : slot.tint
130    const text = ` ${slot.label} `
131
132    return (
133      <Box key={slot.name} flexDirection="row" width={widths[index] ?? 0} height={1}>
134        <Text color={slot.color}>{spark}</Text>
135        <Text color={cap}>▐</Text>
136        <Text bold color={isCooling ? slot.color : INK} backgroundColor={cap}>
137          {slot.rune}
138        </Text>
139        <Text color={cap} backgroundColor={cell}>
140          ▌
141        </Text>
142        <Text bold={isHover} color={isCooling || isHover ? slot.color : 'white'} dimColor={isCooling} backgroundColor={cell}>
143          {isCooling ? cooldownText(text, elapsed) : text}
144        </Text>
145        <Text color={slot.color}>{spark}</Text>
146      </Box>
147    )
148  }
149
150  return (
151    <Box flexDirection="column">
152      {lines.map((line, at) => (
153        <Box key={`line-${at}`} flexDirection="row" columnGap={GAP} height={SLOT_ROWS}>
154          {line.map(one => {
155            const slot = props.slots[one.index]
156            return slot === undefined ? null : drawSlot(slot, one.index)
157          })}
158        </Box>
159      ))}
160    </Box>
161  )
162}
163
164export default Hotbar
165

1// Each slot's own colour, for its frame and label under the pointer: bright game-item colours, in a shuffled
2// order so neighbours never look like a gradient.
3export const SKILL_COLORS = [0x5ad27a, 0xff5a5a, 0x56c8dc, 0xffd23c, 0xc88cff, 0xffa53c, 0x5aa9ff, 0xff8caa] as const
4
5// By slot: up to eight skills each get a different colour, and the same list keeps the same colours.
6export const colorFor = (slot: number): number => SKILL_COLORS[slot % SKILL_COLORS.length] ?? SKILL_COLORS[0]
7
8export const toHex = (rgb: number): string => `#${rgb.toString(16).padStart(6, '0')}`
9
10// The panel colour the cells are tinted from, as rpg-hud's dark cards.
11export const PANEL = 0x14111c
12
13// `rgb` mixed into `base`: 0 is all base, 1 all rgb.
14export const mix = (rgb: number, base: number, amount: number): number => {
15  const channel = (shift: number) => {
16    const from = (base >> shift) & 0xff
17    const to = (rgb >> shift) & 0xff
18    return Math.round(from + (to - from) * amount) << shift
19  }
20  return channel(16) | channel(8) | channel(0)
21}
22

1export type SkillNames = string[]
2
3declare module 'claude-code' {
4  interface PluginState {
5    'skill-bar': { skills: SkillNames }
6  }
7}
8