@g3nomaly/g3n-mods 0.0.0-stage → 0.1.0

package/mods/mini-game/hooks/register.tsx

@@ -0,0 +1,211 @@
+// packages/g3n-mods/mods/mini-game/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Game } from '../types'
+
+const PANE = 'mini-game'
+const TITLE = 'Minesweeper'
+const game = atom({ plugin: 'mini-game', key: 'game' } as const, null)
+const best = atom({ plugin: 'mini-game', key: 'best' } as const, null)
+
+const SIZE = 9
+const MINES = 10
+const BEST_KEY = 'best-seconds'
+/** How long a turn runs before the mod suggests a game, once per session. */
+const HINT_AFTER_MS = 60_000
+const NUMBER_COLORS = [undefined, '#6b8fd6', '#7cc47f', '#e06c6c', '#9b87f5', '#e0775a', '#5fb3c4', '#d0d0d0', '#8a8f98']
+
+/** Cells around `cell` on a `size` × `size` board. */
+export function neighbors(cell: number, size: number): number[] {
+  const row = Math.floor(cell / size)
+  const col = cell % size
+  const found: number[] = []
+  for (let dr = -1; dr <= 1; dr++) {
+    for (let dc = -1; dc <= 1; dc++) {
+      const r = row + dr
+      const c = col + dc
+      if ((dr !== 0 || dc !== 0) && r >= 0 && r < size && c >= 0 && c < size) found.push(r * size + c)
+    }
+  }
+  return found
+}
+
+function adjacentMines(board: Game, cell: number): number {
+  return neighbors(cell, board.size).filter(n => board.mines.includes(n)).length
+}
+
+/** Places mines anywhere but `safe` and the cells around it. */
+function placeMines(board: Game, safe: number): number[] {
+  const banned = new Set([safe, ...neighbors(safe, board.size)])
+  const free = Array.from({ length: board.size * board.size }, (_, i) => i).filter(i => !banned.has(i))
+  for (let i = free.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[free[i], free[j]] = [free[j] ?? 0, free[i] ?? 0]
+  }
+  return free.slice(0, board.mineCount)
+}
+
+/**
+ * Reveals one cell: the first reveal places the mines, a zero opens its
+ * neighbours, a mine ends the game, and the last safe cell wins it.
+ *
+ * @param now - Milliseconds since the epoch, stamped as the start or end time
+ */
+export function reveal(board: Game, cell: number, now: number): Game {
+  if (board.status === 'won' || board.status === 'lost') return board
+  if (board.revealed.includes(cell) || board.flagged.includes(cell)) return board
+
+  const mines = board.status === 'ready' ? placeMines(board, cell) : board.mines
+  const started: Game = board.status === 'ready' ? { ...board, mines, status: 'playing', startedAt: now } : board
+  if (mines.includes(cell)) return { ...started, revealed: [...started.revealed, cell], status: 'lost', endedAt: now }
+
+  const open = new Set(started.revealed)
+  const queue = [cell]
+  while (queue.length > 0) {
+    const next = queue.pop() ?? cell
+    if (open.has(next) || started.flagged.includes(next)) continue
+    open.add(next)
+    if (adjacentMines(started, next) === 0) queue.push(...neighbors(next, started.size).filter(n => !open.has(n)))
+  }
+
+  const revealed = [...open]
+  const isWon = revealed.length === started.size * started.size - started.mineCount
+  return isWon ? { ...started, revealed, status: 'won', endedAt: now } : { ...started, revealed }
+}
+
+function newGame(now: number): Game {
+  return { size: SIZE, mineCount: MINES, mines: [], revealed: [], flagged: [], status: 'ready', isFlagMode: false, startedAt: now }
+}
+
+/** Starts a new board and shows the pane. */
+async function startGame($: EngineInterface): Promise<void> {
+  const now = await $.clock.now()
+  await update($, game, () => newGame(now))
+  await $.ui.open({ id: PANE, title: TITLE })
+}
+
+/** Reveals or flags a cell, as the flag mode says, and records a best time on a win. */
+async function pressCell($: EngineInterface, cell: number): Promise<void> {
+  const now = await $.clock.now()
+  const after = await update($, game, board => {
+    if (board === null) return board
+    if (!board.isFlagMode) return reveal(board, cell, now)
+    if (board.revealed.includes(cell) || board.status === 'won' || board.status === 'lost') return board
+    const flagged = board.flagged.includes(cell) ? board.flagged.filter(c => c !== cell) : [...board.flagged, cell]
+    return { ...board, flagged }
+  })
+  if (after?.status === 'won' && after.endedAt === now) {
+    const seconds = Math.round((now - after.startedAt) / 1000)
+    const previous = await read($, best)
+    if (previous === null || seconds < previous) {
+      await update($, best, () => seconds)
+      await $.store.set(BEST_KEY, seconds)
+    }
+    $.ui.toast(`Cleared in ${seconds}s${previous === null || seconds < previous ? ', a new best' : ''}`)
+  }
+}
+
+async function toggleFlagMode($: EngineInterface): Promise<void> {
+  await update($, game, board => (board === null ? board : { ...board, isFlagMode: !board.isFlagMode }))
+}
+
+/** Redraws the timer once a second while a game is on. */
+async function tick($: EngineInterface): Promise<void> {
+  if ((await read($, game))?.status === 'playing') $.ui.invalidate('ui.render')
+}
+
+let hintTurn: string | undefined
+let isHinted = false
+
+/** Suggests a game once per session, when a turn is still running after a minute. */
+async function hint($: EngineInterface, turnId: string): Promise<void> {
+  if (isHinted || hintTurn !== turnId) return
+  if ((await $.ui.panes()).some(pane => pane.id === PANE)) return
+  isHinted = true
+  $.ui.toast('Waiting on Claude? /mini-game opens Minesweeper.')
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'mini-game', description: 'Play Minesweeper while Claude works' })
+    const stored = await $.store.get(BEST_KEY)
+    if (typeof stored === 'number') await update($, best, () => stored)
+    $.clock.every(1000, () => void tick($))
+    return next(e)
+  })
+
+  on('command.run', { command: 'mini-game' }, async $ => {
+    const current = await read($, game)
+    if (current === null || current.status === 'won' || current.status === 'lost') await startGame($)
+    else await $.ui.open({ id: PANE, title: TITLE })
+    return { text: 'Minesweeper is open. Clear the board without hitting a mine.' }
+  })
+
+  on('turn.start', async ($, e, next) => {
+    hintTurn = e.turnId
+    const turnId = e.turnId
+    $.clock.after(HINT_AFTER_MS, () => void hint($, turnId))
+    return next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    if (e.agentId === undefined) hintTurn = undefined
+    return next(e)
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text, Button } = $.ui.resolve(e)
+    const board = await read($, game)
+    if (board === null) {
+      return <Button key="new" label="new game" variant="primary" onPress={() => startGame($)} />
+    }
+
+    const now = await $.clock.now()
+    const elapsed = board.status === 'ready' ? 0 : Math.round(((board.endedAt ?? now) - board.startedAt) / 1000)
+    const record = await read($, best)
+    const isOver = board.status === 'won' || board.status === 'lost'
+
+    const cellView = (cell: number) => {
+      const isRevealed = board.revealed.includes(cell)
+      const isMine = board.mines.includes(cell)
+      if (isRevealed || (isOver && isMine)) {
+        if (isMine) return <Text color="#e06c6c">✹ </Text>
+        const n = adjacentMines(board, cell)
+        return <Text color={NUMBER_COLORS[n]}>{n === 0 ? '  ' : `${n} `}</Text>
+      }
+      const label = board.flagged.includes(cell) ? '⚑' : '■'
+      if (isOver) return <Text dimColor>{label} </Text>
+      return (
+        <Button key={`cell:${cell}`} plain onPress={() => pressCell($, cell)}>
+          <Text color={label === '⚑' ? '#e0775a' : '#6b7280'}>{label}</Text>
+        </Button>
+      )
+    }
+
+    const rows = Array.from({ length: board.size }, (_, r) => (
+      <Box flexDirection="row" columnGap={1}>
+        {Array.from({ length: board.size }, (_, c) => cellView(r * board.size + c))}
+      </Box>
+    ))
+
+    const status = board.status === 'won'
+      ? <Text color="#7cc47f" bold>Cleared in {elapsed}s</Text>
+      : board.status === 'lost'
+        ? <Text color="#e06c6c" bold>Boom. {board.revealed.length} cells cleared</Text>
+        : <Text dimColor>💣 {board.mineCount - board.flagged.length} · ⏱ {elapsed}s{record === null ? '' : ` · best ${record}s`}</Text>
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        <Box flexDirection="row" justifyContent="space-between" alignItems="center">
+          {status}
+          <Box flexDirection="row" columnGap={1}>
+            {isOver ? '' : <Button key="flag" label={board.isFlagMode ? '⚑ flagging' : '⚑ flag'} variant={board.isFlagMode ? 'primary' : 'secondary'} onPress={() => toggleFlagMode($)} />}
+            <Button key="new" label="new game" onPress={() => startGame($)} />
+          </Box>
+        </Box>
+        <Box flexDirection="column">{rows}</Box>
+      </Box>
+    )
+  })
+}

package/mods/mini-game/types/index.d.ts

@@ -0,0 +1,21 @@
+// packages/g3n-mods/mods/mini-game/types/index.d.ts
+
+/** A Minesweeper board; cells are numbered row by row from 0. Times are milliseconds since the epoch. */
+export type Game = {
+  size: number
+  mineCount: number
+  /** Empty until the first reveal, which never hits a mine */
+  mines: number[]
+  revealed: number[]
+  flagged: number[]
+  status: 'ready' | 'playing' | 'won' | 'lost'
+  isFlagMode: boolean
+  startedAt: number
+  endedAt?: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'mini-game': { game: Game | null; best: number | null }
+  }
+}

package/mods/tool-timeline/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "tool-timeline",
+  "version": "0.1.0",
+  "description": "Each tool call with its duration; a denied call is struck through next to the call that replaced it.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts"
+}

package/mods/tool-timeline/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/tool-timeline/hooks/register.tsx

@@ -0,0 +1,259 @@
+// packages/g3n-mods/mods/tool-timeline/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { CallStatus, TimelineCall } from '../types'
+
+const PANE = 'tool-timeline'
+const TITLE = 'Tool timeline'
+const calls = atom({ plugin: 'tool-timeline', key: 'calls' } as const, [])
+
+/** Calls kept in state; older ones fall off. */
+const KEEP = 100
+
+/** Approximate pixel width of one cell of the editor's code font. */
+const CELL_PX = 7
+
+const TRACK = '#2b3240'
+const ERROR = '#e06c6c'
+const DIM = '#8a8f98'
+
+/** Badge color per tool family. */
+const TOOL_COLORS: ReadonlyArray<[RegExp, string]> = [
+  [/^Bash$|^PowerShell$/, '#e5b567'],
+  [/^Read$/, '#5b8def'],
+  [/^(Edit|Write|NotebookEdit)$/, '#7cc47f'],
+  [/^(Grep|Glob|LS)$/, '#9b87f5'],
+  [/^Web/, '#5fb3c4'],
+  [/^(Agent|Task)$/, '#f09bb5'],
+]
+
+/** Input fields that say most about a call, tried in order. */
+const LABEL_FIELDS = ['command', 'file_path', 'notebook_path', 'pattern', 'url', 'query', 'description', 'skill', 'prompt'] as const
+
+function colorOf(tool: string): string {
+  return TOOL_COLORS.find(([match]) => match.test(tool))?.[1] ?? DIM
+}
+
+function badgeOf(tool: string): string {
+  if (tool === 'Bash' || tool === 'PowerShell') return '$'
+  return tool.replace(/^mcp__[^_]+__/, '').charAt(0).toUpperCase()
+}
+
+/** Short form of a call's input: a command, a file's name, a pattern, or the first text field. */
+export function labelOf(input: Record<string, unknown>): string {
+  for (const field of LABEL_FIELDS) {
+    const value = input[field]
+    if (typeof value !== 'string' || value.length === 0) continue
+    const text = field === 'file_path' || field === 'notebook_path' ? value.split('/').pop() ?? value : value
+    return text.replace(/\s+/g, ' ').trim()
+  }
+  const first = Object.values(input).find((value): value is string => typeof value === 'string')
+  return first?.replace(/\s+/g, ' ').trim() ?? ''
+}
+
+/** Text of a tool result's content, which is a string or a list of text blocks. */
+function resultText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => (typeof block === 'object' && block !== null && 'text' in block && typeof block.text === 'string' ? block.text : ''))
+    .join('\n')
+}
+
+/** Whether an error text reads as a refusal: a hook's deny, the permission dialog's no, a blocked call. */
+function isRefusal(text: string): boolean {
+  return /\bdenied\b|\bblocked\b|doesn't want to proceed|was rejected|permission/i.test(text)
+}
+
+function seconds(ms: number): string {
+  return ms >= 10_000 ? `${Math.round(ms / 1000)}s` : `${(ms / 1000).toFixed(1)}s`
+}
+
+/** Short note for the callout, e.g. `use the trash` for delete-guard's deny. */
+function shortNote(note: string | undefined): string {
+  if (note === undefined) return ''
+  if (/trash/i.test(note)) return 'use the trash'
+  const text = note.replace(/^[\w-]+:\s*/, '')
+  return text.length > 40 ? `${text.slice(0, 39)}…` : text
+}
+
+/** Adds a call or changes the one with its id; the list stays in start order and capped. */
+async function patchCall($: EngineInterface, id: string, patch: (call: TimelineCall | undefined) => TimelineCall): Promise<void> {
+  await update($, calls, list => {
+    const index = list.findIndex(call => call.id === id)
+    if (index === -1) return [...list, patch(undefined)].slice(-KEEP)
+    return list.map((call, i) => (i === index ? patch(call) : call))
+  })
+}
+
+/** Ends a call with its status, keeping the first ending it got. */
+async function settleCall($: EngineInterface, id: string, status: CallStatus, note?: string): Promise<void> {
+  const endedAt = await $.clock.now()
+  await patchCall($, id, call =>
+    call === undefined
+      ? { id, tool: 'tool', label: '', status, startedAt: endedAt, endedAt, note }
+      : call.endedAt !== undefined ? call : { ...call, status, endedAt, note },
+  )
+}
+
+/** Redraws the pane while a call runs, so its bar and time move. */
+async function tick($: EngineInterface): Promise<void> {
+  const list = await read($, calls)
+  if (list.some(call => call.status === 'running')) $.ui.invalidate('ui.render')
+}
+
+/** The call a denied call was replaced by: the next call of the same tool. */
+function replacementOf(list: readonly TimelineCall[], index: number): TimelineCall | undefined {
+  const denied = list[index]
+  return denied === undefined ? undefined : list.slice(index + 1).find(call => call.tool === denied.tool)
+}
+
+function barSvg(width: number, fill: number, color: string): string {
+  const w = Math.max(0, Math.min(width, fill))
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="8" viewBox="0 0 ${width} 8"><rect width="${width}" height="8" rx="2" fill="${TRACK}"/><rect width="${w.toFixed(1)}" height="8" rx="2" fill="${color}"/></svg>`
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'tool-timeline', description: 'Show or hide the tool call timeline' })
+    void $.ui.open({ id: PANE, title: TITLE })
+    $.clock.every(1000, () => void tick($))
+    return next(e)
+  })
+
+  on('command.run', { command: 'tool-timeline' }, async $ => {
+    if ((await $.ui.panes()).some(pane => pane.id === PANE)) {
+      await $.ui.close({ id: PANE })
+      return { text: 'Tool timeline hidden.' }
+    }
+    await $.ui.open({ id: PANE, title: TITLE })
+    return { text: 'Tool timeline shown.' }
+  })
+
+  on('tool.call', async ($, e, next) => {
+    const startedAt = await $.clock.now()
+    const label = labelOf(e as unknown as Record<string, unknown>)
+    await patchCall($, e.tool_use_id, call => ({
+      ...call,
+      id: e.tool_use_id,
+      tool: e.tool,
+      label,
+      status: 'running',
+      startedAt,
+      agentId: e.agentId,
+    }))
+
+    const ran = await next(e)
+    if ('deny' in ran) await settleCall($, e.tool_use_id, 'denied', ran.deny)
+    else if (ran.isError === true) await settleCall($, e.tool_use_id, isRefusal(ran.text ?? '') ? 'denied' : 'error', ran.text)
+    else await settleCall($, e.tool_use_id, 'ok')
+    return ran
+  }).catch(($, e, next) => next(e))
+
+  on('session.append', async ($, e, next) => {
+    const stored = await next(e)
+    if (e.door === 'response') {
+      const now = await $.clock.now()
+      for (const block of e.message.content) {
+        if (block.type !== 'tool_use' || typeof block.id !== 'string' || typeof block.name !== 'string') continue
+        const input = typeof block.input === 'object' && block.input !== null ? (block.input as Record<string, unknown>) : {}
+        const id = block.id
+        const tool = block.name
+        await patchCall($, id, call => call ?? { id, tool, label: labelOf(input), status: 'queued', startedAt: now, agentId: e.agentId })
+      }
+    }
+    if (e.door === 'tool-result') {
+      for (const block of e.message.content) {
+        if (block.type !== 'tool_result' || typeof block.tool_use_id !== 'string') continue
+        const list = await read($, calls)
+        const call = list.find(one => one.id === block.tool_use_id)
+        if (call?.status === 'queued') {
+          const text = resultText(block.content)
+          await settleCall($, block.tool_use_id, block.is_error === true ? 'denied' : 'ok', text)
+        }
+      }
+    }
+    return stored
+  }).catch(($, e, next) => next(e))
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const list = await read($, calls)
+    if (list.length === 0) return <Text dimColor>No tool calls yet.</Text>
+
+    const now = await $.clock.now()
+    const room = Math.max(4, (e.viewport?.rows ?? 30) - 6)
+    const shown = list.slice(-room)
+    const durationOf = (call: TimelineCall): number => (call.endedAt ?? now) - call.startedAt
+    const longest = Math.max(1, ...shown.map(durationOf))
+    const total = list.reduce((sum, call) => sum + (call.status === 'denied' ? 0 : durationOf(call)), 0)
+    const barCells = Math.max(8, Math.floor(e.props.bodyColumns * 0.3))
+    const labelCells = Math.max(12, e.props.bodyColumns - barCells - 12)
+
+    const bar = (call: TimelineCall) => {
+      const color = call.status === 'error' ? ERROR : call.status === 'ok' && /^Bash$/.test(call.tool) ? '#5fae6e' : colorOf(call.tool)
+      const share = call.status === 'denied' ? 0.04 : Math.max(0.03, durationOf(call) / longest)
+      if (e.surface === 'terminal') {
+        const filled = Math.max(1, Math.round(share * barCells))
+        return (
+          <Text>
+            <Text color={color}>{'▬'.repeat(filled)}</Text>
+            <Text color={TRACK}>{'▬'.repeat(barCells - filled)}</Text>
+          </Text>
+        )
+      }
+      const { Svg } = $.ui.resolve(e)
+      const width = barCells * CELL_PX
+      return <Svg source={barSvg(width, share * width, color)} alt={`${call.tool} ${seconds(durationOf(call))}`} width={width} height={8} />
+    }
+
+    const outcome = (call: TimelineCall) => {
+      switch (call.status) {
+        case 'denied': return <Text color={ERROR}>denied</Text>
+        case 'error': return <Text color={ERROR}>{seconds(durationOf(call))} ✗</Text>
+        case 'ok': return <Text dimColor>{seconds(durationOf(call))}</Text>
+        case 'running': return <Text color="#e5b567">{seconds(durationOf(call))}…</Text>
+        case 'queued': return <Text dimColor>queued</Text>
+      }
+    }
+
+    const rows = shown.map((call, index) => {
+      const replacement = call.status === 'denied' ? replacementOf(shown, index) : undefined
+      return (
+        <Box flexDirection="column">
+          <Box flexDirection="row" columnGap={1}>
+            <Text bold color="#1b1f27" backgroundColor={colorOf(call.tool)}> {badgeOf(call.tool)} </Text>
+            <Box width={labelCells}>
+              <Text wrap="truncate-end" strikethrough={call.status === 'denied'} color={call.status === 'denied' ? ERROR : undefined}>
+                {call.agentId === undefined ? '' : '↳ '}{call.tool} <Text dimColor>{call.label}</Text>
+              </Text>
+            </Box>
+            {bar(call)}
+            <Box width={8} justifyContent="flex-end">{outcome(call)}</Box>
+          </Box>
+          {call.status === 'denied' && (
+            <Box borderStyle="round" borderColor="#7a3b3b" paddingX={1} flexDirection="row" justifyContent="space-between">
+              <Text wrap="truncate-end">
+                <Text color={ERROR}>⊘ </Text>
+                <Text strikethrough dimColor>{call.label}</Text>
+                {replacement === undefined ? '' : <Text> → <Text color="#7cc47f">{replacement.label}</Text></Text>}
+              </Text>
+              <Text color={ERROR}>denied{call.note === undefined ? '' : ` · ${shortNote(call.note)}`}</Text>
+            </Box>
+          )}
+        </Box>
+      )
+    })
+
+    return (
+      <Box flexDirection="column" gap={0}>
+        <Box flexDirection="row" justifyContent="space-between" marginBottom={1}>
+          <Text bold>Tool timeline</Text>
+          <Text dimColor>{list.length} call{list.length === 1 ? '' : 's'} · {seconds(total)}</Text>
+        </Box>
+        {rows}
+      </Box>
+    )
+  })
+}

package/mods/tool-timeline/types/index.d.ts

@@ -0,0 +1,25 @@
+// packages/g3n-mods/mods/tool-timeline/types/index.d.ts
+
+/** How a call ended: still waiting or running, done, failed, or refused before it ran. */
+export type CallStatus = 'queued' | 'running' | 'ok' | 'error' | 'denied'
+
+/** One tool call on the timeline; times are milliseconds since the epoch. */
+export type TimelineCall = {
+  id: string
+  tool: string
+  /** Short form of the call's input, e.g. `rm -rf dist` or `package.json` */
+  label: string
+  status: CallStatus
+  startedAt: number
+  endedAt?: number
+  /** Why it was denied or failed, as the deny or error text said */
+  note?: string
+  /** Set on calls a subagent made */
+  agentId?: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'tool-timeline': { calls: TimelineCall[] }
+  }
+}

package/mods/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "types": [],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment"
+  },
+  "include": ["../types/claude-code.d.ts", "*/hooks", "*/types"]
+}

package/mods/you-should-know/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "you-should-know",
+  "version": "0.1.0",
+  "description": "A card under long replies that flags their key point: a headline and one supporting line.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "minChars": {
+      "type": "number",
+      "title": "Minimum reply length",
+      "default": 1500,
+      "description": "Replies shorter than this many characters get no card"
+    },
+    "model": {
+      "type": "string",
+      "title": "Model",
+      "default": "haiku",
+      "description": "Model that picks the key point"
+    }
+  }
+}

package/mods/you-should-know/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/you-should-know/hooks/register.tsx

@@ -0,0 +1,98 @@
+// packages/g3n-mods/mods/you-should-know/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Card } from '../types'
+
+const cards = atom({ plugin: 'you-should-know', key: 'cards' } as const, [])
+
+const DEFAULT_MIN_CHARS = 1500
+const DEFAULT_MODEL = 'haiku'
+const TAIL = 200
+const KEEP = 20
+/** Most of a reply sent to the model; the end of a reply carries its conclusion. */
+const MAX_PROMPT_CHARS = 40_000
+
+const SYSTEM = [
+  'You read one reply that an AI coding assistant wrote to its user, and pick the single point the user must not miss:',
+  'a cost, a risk, a decision they have to make, a breaking change, or a surprising fact.',
+  'Answer with JSON only, no prose and no code fence: {"headline": "...", "detail": "..."}.',
+  'The headline is a plain statement of at most 70 characters. The detail is one supporting line of at most 120 characters.',
+  'Use the reply\'s own facts and numbers. If nothing in the reply stands out, answer {"skip": true}.',
+].join(' ')
+
+const BULB_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="#3d3424"/><path d="M20 11a6 6 0 0 0-3.6 10.8c.8.6 1.1 1.3 1.1 2.2v1h5v-1c0-.9.3-1.6 1.1-2.2A6 6 0 0 0 20 11z" fill="none" stroke="#e5b567" stroke-width="1.6"/><path d="M17.5 28h5M18.3 30.5h3.4" stroke="#e5b567" stroke-width="1.6" stroke-linecap="round"/></svg>'
+
+function normalize(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/** Reads the model's answer: a card's headline and detail, or `undefined` for a skip or anything malformed. */
+export function parseCard(text: string): Omit<Card, 'tail'> | undefined {
+  const json = /\{[\s\S]*\}/.exec(text)?.[0]
+  if (json === undefined) return undefined
+  let value: unknown
+  try {
+    value = JSON.parse(json)
+  } catch {
+    return undefined
+  }
+  if (typeof value !== 'object' || value === null || !('headline' in value) || !('detail' in value)) return undefined
+  const { headline, detail } = value
+  if (typeof headline !== 'string' || typeof detail !== 'string' || headline.trim().length === 0) return undefined
+  return { headline: headline.trim().slice(0, 90), detail: detail.trim().slice(0, 160) }
+}
+
+/** Asks the model for the reply's key point and keeps the card when there is one. */
+async function extract($: EngineInterface, answer: string, model: string): Promise<void> {
+  const result = await $.model.complete({ model, system: SYSTEM, prompt: answer.slice(-MAX_PROMPT_CHARS), maxTokens: 300 })
+  if (!result.isAnswered) return
+  const card = parseCard(result.text)
+  if (card === undefined) return
+  const tail = normalize(answer).slice(-TAIL)
+  await update($, cards, list => [...list.filter(one => one.tail !== tail), { tail, ...card }].slice(-KEEP))
+}
+
+export const register: Register = (on, options) => {
+  const minChars = Number(options.minChars ?? DEFAULT_MIN_CHARS)
+  const model = typeof options.model === 'string' && options.model.length > 0 ? options.model : DEFAULT_MODEL
+
+  on('turn.complete', async ($, e, next) => {
+    const result = await next(e)
+    if (e.agentId === undefined && e.reason === 'answer' && e.answer.length >= minChars) {
+      const answer = e.answer
+      $.clock.after(0, () => void extract($, answer, model))
+    }
+    return result
+  }).catch(($, e, next) => next(e))
+
+  on('ui.render', { component: 'AssistantMessage' }, async ($, e, next) => {
+    if (e.props.isSummary === true) return next(e)
+    const text = normalize(e.props.text)
+    if (text.length < 20) return next(e)
+    const card = (await read($, cards)).find(one => one.tail.endsWith(text.slice(-TAIL)))
+    if (card === undefined) return next(e)
+
+    const { Box, Text } = $.ui.resolve(e)
+    const icon = e.surface === 'terminal'
+      ? <Text color="#e5b567">💡</Text>
+      : (() => {
+          const { Svg } = $.ui.resolve(e)
+          return <Svg source={BULB_SVG} alt="key point" width={40} height={40} />
+        })()
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        {await next(e)}
+        <Box borderStyle="round" borderColor="#3a3f4b" paddingX={2} paddingY={1} flexDirection="row" columnGap={2} alignItems="center">
+          {icon}
+          <Box flexDirection="column">
+            <Text bold color="#e5b567">YOU SHOULD KNOW</Text>
+            <Text bold>{card.headline}</Text>
+            <Text dimColor>{card.detail}</Text>
+          </Box>
+        </Box>
+      </Box>
+    )
+  })
+}