@g3nomaly/g3n-mods 0.1.5 → 0.1.7

package/.claude-plugin/marketplace.json

@@ -49,7 +49,7 @@
     {
       "name": "mini-game",
       "source": "./mods/mini-game",
-      "description": "Minesweeper to play while Claude works.",
+      "description": "Minesweeper and whack-a-mole to play while Claude works.",
       "version": "0.1.0"
     },
     {

package/README.md

@@ -22,13 +22,13 @@ Then open the project in VS Code and trust the workspace. New sessions load the
 |---|---|---|
 | `agents-panel` | The agents in `.claude/agents` with their model and a run button. A running agent shows a spinner, and a toast says when it starts and finishes | `/agents-panel` |
 | `context-bar` | One bar of context-window use split by source, with the total and where compaction starts | `/context-bar` |
-| `custom-crab-agents` | Adds each subagent to the agents panel as a crab: its role (from its name or type) picks its hat and what it holds, such as a reviewer's deerstalker and magnifying glass, a tester's work helmet and wrench, a designer's top hat and brush. Shows model, effort, steps, context, tokens, cost and time. Click a crab to open its whole conversation in a tab and message it there. Needs `agents-panel`, which installing it adds | `/agents-panel` |
+| `custom-crab-agents` | Adds each subagent to the agents panel as a crab drawn as Claude's mascot, walking while it works and blinking when done: its role (from its name or type) picks its hat and what it holds, such as a reviewer's deerstalker and magnifying glass, a tester's work helmet and wrench, a designer's top hat and brush. Shows model, effort, steps, context, tokens, cost and time. Click anywhere on a crab to open its whole conversation in a tab and message it there. Needs `agents-panel`, which installing it adds | `/agents-panel` |
 | `delete-guard` | Off by default: deletes run unasked. Turn it on with the switch in its pane, or `/delete-guard on`; it stays on in later sessions. While on, `rm -rf` and other permanent deletes wait on a card listing the files, their sizes and whether git can restore them, until you press **Delete** or **Cancel**. Cancel tells Claude which trash command to use instead. With nothing to draw the card on, the delete is refused | `/delete-guard on \| off` |
 | `focus-mode` | A timed focus block in which you're away: Claude's questions are refused, so it picks for itself and says what it assumed, and permission prompts are refused, so it works around the step and lists it for later. Countdown, progress bar and end button. Set the length with − and + in the pane, or pass the minutes; the length you pick is kept for later blocks | `/focus-mode [minutes] \| end` |
 | `handoff` | Writes a handoff with the `handoff` skill, clears the session, and attaches the handoff to your next prompt | `/handoff-new [what the next session is for]` |
 | `hide-personal-data` | Masks names, emails, phone numbers, IBANs and card numbers in replies. Hover a mask to read it | `/hide-personal-data on \| off` |
-| `mini-game` | Minesweeper, to play while Claude works | `/mini-game` |
-| `tool-timeline` | Each tool call with its duration. A denied call is struck through, next to the call that replaced it | `/tool-timeline` |
+| `mini-game` | Minesweeper, or whack-a-mole when you want zero thinking: hit the mole before it hides, three misses and the round ends, and it speeds up as you score. Both keep a high score. Switch games with the tabs in its pane | `/mini-game [mines \| mole]` |
+| `tool-timeline` | The last ten tool calls, one line each, with their durations, in a pane that keeps one height. Click a call to see it in full in the box under them. A denied call is struck through, next to the call that replaced it | `/tool-timeline` |
 | `you-should-know` | A card under long replies with their key point, a headline and one supporting line. It costs one small Haiku call per reply of 1500 characters or more | none |
 
 For `agents-panel`, `context-bar` and `tool-timeline`, the command opens the pane and running it again closes it.
@@ -55,9 +55,22 @@ mods/<name>/
 ├── .claude-plugin/plugin.json   # name, version, description
 ├── hooks/hooks.json             # { "modules": ["./register.tsx"] }
 ├── hooks/register.tsx           # exports `register`
-└── types/index.d.ts
+├── types/index.d.ts
+└── view/                        # optional: how the VS Code viewer draws it
+    ├── view.ts                  # exports `mount(root, api)`
+    └── view.css
 ```
 
+### Drawing a mod with HTML and CSS
+
+On every surface but the VS Code viewer, a mod draws with the engine's elements (`Box`, `Text`, `Button`, `Svg`). In the viewer it can draw with its own HTML and CSS instead, as `tool-timeline`, `agents-panel` and `custom-crab-agents` do:
+
+1. **The hook hands over data.** On `e.surface === 'vscode'`, the render hook returns a view box: a `Box` keyed `g3n-view:<mod>` holding the data as JSON in one `Text`, and a hidden `Input` keyed `g3n-act:<mod>` that receives the view's actions.
+2. **The view draws it.** `view/view.ts` exports `mount(root, api)`. `root` is a shadow root of the mod's own, so `view.css` applies only there and the editor's theme variables still reach it. `mount` returns `{ update(data) }`, which gets the data each time the pane is drawn. Keep elements across updates, and animations and anything typed in the view keep going.
+3. **Actions go back to the hook.** `api.act(name, arg)` arrives at the hidden Input's `onSubmit` as JSON of `{ name, arg }`.
+
+The installer bundles `view/view.ts` into `view/view.js` where the mod is installed, so the mod's source stays TypeScript. A view may import plain modules of its mod, such as `hooks/sprite.ts`, but not `claude-code`.
+
 The folder name must match `name` in `plugin.json`. Mods are TypeScript only, and the installer refuses a mod that contains any `.js`, `.mjs`, `.cjs` or `.jsx` file. To share your own mods, put them in a git repository, npm package or local folder with the same layout and register it with `bunx @g3nomaly/mods source add`.
 
 ## Development

package/mods/agents-panel/hooks/register.tsx

@@ -2,13 +2,12 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, Register, RenderElement } from 'claude-code'
 
-import type { AgentDef, RunningAgent } from '../types'
+import type { AgentDef, AgentsViewData, RunningAgent } from '../types'
 
 const PANE = 'agents-panel'
 const TITLE = 'Agents'
 const agents = atom({ plugin: 'agents-panel', key: 'agents' } as const, [])
 const running = atom({ plugin: 'agents-panel', key: 'running' } as const, [])
-const task = atom({ plugin: 'agents-panel', key: 'task' } as const, '')
 
 const AGENTS_DIR = '.claude/agents'
 const DEFAULT_TASK = 'Do the job your instructions describe for this project, then report what you did and what you found.'
@@ -113,15 +112,14 @@ async function loadAgents($: EngineInterface): Promise<void> {
 }
 
 /**
- * Starts one agent with the task typed in the panel, or its standing job when none was typed.
+ * Starts one agent on its standing job: what its own instructions describe. A specific task goes through the chat.
  *
  * @param $ - Engine handle the hook received, see `EngineInterface`.
  * @param agent - Definition of the agent to start.
  */
 async function runAgent($: EngineInterface, agent: AgentDef): Promise<void> {
-  const typed = (await read($, task)).trim()
   const started = await $.agent.spawn({
-    prompt: typed.length > 0 ? typed : DEFAULT_TASK,
+    prompt: DEFAULT_TASK,
     subagentType: agent.name,
     description: `Run ${agent.name} from the agents panel`,
   })
@@ -169,6 +167,26 @@ async function reportAnswer($: EngineInterface, run: RunningAgent, answer: strin
   await $.session.append({ message: { type: 'system', content: [{ type: 'text', text: `${run.name} finished:\n\n${text}` }] } })
 }
 
+/**
+ * Carries out an action the panel's view sent: `run` an agent by name.
+ *
+ * @param $ - Engine handle the action came through.
+ * @param value - The action as the view sent it, JSON of `{ name, arg }`.
+ */
+async function act($: EngineInterface, value: string): Promise<void> {
+  let action: { name?: unknown; arg?: unknown }
+  try {
+    action = JSON.parse(value) as { name?: unknown; arg?: unknown }
+  } catch {
+    return
+  }
+  const arg = typeof action.arg === 'object' && action.arg !== null ? (action.arg as Record<string, unknown>) : {}
+  if (action.name === 'run' && typeof arg.name === 'string') {
+    const agent = (await read($, agents)).find(one => one.name === arg.name)
+    if (agent !== undefined) await runAgent($, agent)
+  }
+}
+
 /**
  * Registers this mod's `agents-panel` command, its session and turn hooks, and its pane.
  *
@@ -217,6 +235,32 @@ export const register: Register = on => {
     const now = await $.clock.now()
     const frame = SPINNER[Math.floor(now / 250) % SPINNER.length] ?? '◐'
 
+    // The viewer draws the panel with the mod's own view: hand it the agents as data, inside the key an add-on looks for.
+    if (e.surface === 'vscode') {
+      const { Input } = $.ui.resolve(e)
+      const data: AgentsViewData = {
+        agents: list.map((agent, index) => {
+          const run = runs.find(one => one.name === agent.name)
+          return {
+            name: agent.name,
+            description: agent.description,
+            model: agent.model,
+            color: dotColor(agent, index),
+            scope: agent.scope,
+            ...(run === undefined ? {} : { runningFor: Math.max(0, Math.round((now - run.startedAt) / 1000)) }),
+          }
+        }),
+      }
+      return withAddOn(
+        <Box key={`${OWN_KEY}body`}>
+          <Box key="g3n-view:agents-panel">
+            <Text>{JSON.stringify(data)}</Text>
+            <Input key="g3n-act:agents-panel" onSubmit={value => act($, value)} />
+          </Box>
+        </Box>,
+      )
+    }
+
     const header = (
       <Box flexDirection="row" justifyContent="space-between">
         <Text>
@@ -276,25 +320,9 @@ export const register: Register = on => {
       )
     }
 
-    const input = e.surface === 'mobile'
-      ? ''
-      : (() => {
-          const { Input } = $.ui.resolve(e)
-          return (
-            <Input
-              key="task"
-              label="Task"
-              placeholder="what the next run should do (optional)"
-              onInput={value => update($, task, () => value)}
-              onSubmit={value => update($, task, () => value)}
-            />
-          )
-        })()
-
     return withAddOn(
       <Box key={`${OWN_KEY}body`} flexDirection="column" gap={1}>
         {header}
-        {input}
         {section('project')}
         {section('user')}
         <Text dimColor>click ▶ run to start one · /agents-panel to hide</Text>

package/mods/agents-panel/types/index.d.ts

@@ -17,8 +17,23 @@ export type RunningAgent = {
   startedAt: number
 }
 
+/** One agent as the panel's view draws it; `runningFor` is set while a run started from the panel goes on, in seconds. */
+export type AgentView = {
+  name: string
+  description: string
+  model: string
+  color: string
+  scope: 'project' | 'user'
+  runningFor?: number
+}
+
+/** What the panel's view gets: the agents. */
+export type AgentsViewData = {
+  agents: AgentView[]
+}
+
 declare module 'claude-code' {
   interface PluginState {
-    'agents-panel': { agents: AgentDef[]; running: RunningAgent[]; task: string }
+    'agents-panel': { agents: AgentDef[]; running: RunningAgent[] }
   }
 }

package/mods/agents-panel/view/view.css

@@ -0,0 +1,51 @@
+/* packages/g3n-mods/mods/agents-panel/view/view.css */
+.ap {
+  --dim: var(--vscode-descriptionForeground, #9d9d9d);
+  --line: color-mix(in srgb, var(--vscode-foreground) 10%, transparent);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.ap-head { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; }
+.ap-title { display: inline-flex; align-items: baseline; gap: 6px; font-weight: 600; font-size: 14px; }
+.ap-mark { color: #d97757; }
+.ap-sub { color: var(--dim); font-weight: 400; font-size: 13px; }
+.ap-busy { color: var(--dim); font-size: 12px; }
+.ap-busy.is-on::before { content: ''; display: inline-block; width: 7px; height: 7px; margin-right: 6px; border-radius: 50%; background: #d97757; animation: ap-pulse 1.2s ease-in-out infinite; }
+@keyframes ap-pulse { 50% { opacity: 0.3; } }
+
+.ap-sections { display: flex; flex-direction: column; gap: 12px; }
+.ap-label { display: flex; align-items: baseline; gap: 8px; margin-bottom: 4px; }
+.ap-scope { font-size: 11px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: #8fa1d6; }
+.ap-path { color: var(--dim); font-size: 12px; }
+.ap-list { display: flex; flex-direction: column; }
+
+.ap-row { display: grid; grid-template-columns: 8px minmax(0, 1fr) auto; align-items: center; column-gap: 10px; padding: 6px 8px; border-radius: 8px; }
+.ap-row:hover { background: color-mix(in srgb, var(--vscode-foreground) 5%, transparent); }
+.ap-dot { width: 8px; height: 8px; border-radius: 50%; }
+.ap-text { min-width: 0; }
+.ap-line { display: flex; align-items: baseline; gap: 8px; }
+.ap-name { font-weight: 600; }
+.ap-model { color: var(--dim); font-size: 12px; }
+.ap-desc { color: var(--dim); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+.ap-run {
+  height: 26px;
+  padding: 0 12px;
+  border: 1px solid var(--line);
+  border-radius: 13px;
+  background: transparent;
+  color: var(--vscode-foreground);
+  font: inherit;
+  font-size: 12px;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 100ms ease, border-color 100ms ease;
+}
+.ap-run:hover:not(:disabled) { background: #d97757; border-color: #d97757; color: #fff; }
+.ap-run:focus-visible { outline: 1px solid var(--vscode-focusBorder); outline-offset: 1px; }
+.ap-run:disabled { cursor: default; color: var(--dim); border-style: dashed; }
+.ap-run[data-running="pending"] { opacity: 0.6; }
+
+.ap-empty { margin: 0; color: var(--dim); font-size: 12px; }

package/mods/agents-panel/view/view.ts

@@ -0,0 +1,126 @@
+// packages/g3n-mods/mods/agents-panel/view/view.ts
+import type { AgentView, AgentsViewData } from '../types'
+
+/** What the viewer hands a view: a way to send the mod an action and to open a link. */
+type ViewApi = { act: (name: string, arg?: unknown) => void; openLink: (href: string) => void }
+
+const AGENTS_DIR = '.claude/agents'
+
+/** Makes an element with a class, and text when given. */
+function el<K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  node.className = className
+  if (text !== undefined) node.textContent = text
+  return node
+}
+
+/** Sets an element's text only when it changed. */
+function setText(node: Element, text: string): void {
+  if (node.textContent !== text) node.textContent = text
+}
+
+/**
+ * @brief Mounts the agents panel: the agents of the project and the user with a run button each. Rows are kept by
+ * name across updates, so a running spinner keeps turning.
+ *
+ * @param root - The shadow root the viewer gives this view.
+ * @param api - Sends `run` to the mod.
+ * @returns The instance the viewer hands each update to.
+ */
+export function mount(root: ShadowRoot, api: ViewApi): { update: (data: unknown) => void } {
+  const frame = el('div', 'ap')
+  const head = el('header', 'ap-head')
+  const title = el('span', 'ap-title')
+  title.append(el('span', 'ap-mark', '◆'), el('span', '', 'Agents'), el('span', 'ap-sub', 'in this project'))
+  const busy = el('span', 'ap-busy')
+  head.append(title, busy)
+
+  const sections = el('div', 'ap-sections')
+  const empty = el('p', 'ap-empty', `No agents in ${AGENTS_DIR} or ~/${AGENTS_DIR}. Add one with /agents.`)
+  frame.append(head, sections)
+  root.append(frame)
+
+  const rows = new Map<string, HTMLElement>()
+
+  /** Builds an agent's row once: dot, name, model, description, and its run button. */
+  const makeRow = (name: string): HTMLElement => {
+    const row = el('div', 'ap-row')
+    const dot = el('span', 'ap-dot')
+    const text = el('div', 'ap-text')
+    const line = el('div', 'ap-line')
+    line.append(el('span', 'ap-name', name), el('span', 'ap-model'))
+    text.append(line, el('div', 'ap-desc'))
+    const run = el('button', 'ap-run')
+    run.type = 'button'
+    run.addEventListener('click', () => {
+      if (run.dataset.running === 'true') return
+      run.dataset.running = 'pending'
+      api.act('run', { name })
+    })
+    row.append(dot, text, run)
+    return row
+  }
+
+  /** Brings an agent's row up to date. */
+  const fill = (row: HTMLElement, agent: AgentView): void => {
+    const [dot, text, run] = Array.from(row.children) as HTMLElement[]
+    if (dot === undefined || text === undefined || run === undefined) return
+    dot.style.background = agent.color
+    const model = text.querySelector('.ap-model')
+    if (model !== null) setText(model, agent.model)
+    const desc = text.querySelector('.ap-desc')
+    if (desc !== null) setText(desc, agent.description)
+    row.title = agent.description
+    const isRunning = agent.runningFor !== undefined
+    run.dataset.running = String(isRunning)
+    if (run instanceof HTMLButtonElement) run.disabled = isRunning
+    setText(run, isRunning ? `running · ${agent.runningFor}s` : '▶ Run')
+  }
+
+  return {
+    update: (data: unknown) => {
+      const view = data as AgentsViewData | null
+      const agents = view?.agents ?? []
+      const running = agents.filter(agent => agent.runningFor !== undefined).length
+      setText(busy, running > 0 ? `${running} running` : '')
+      busy.classList.toggle('is-on', running > 0)
+
+      if (agents.length === 0) {
+        if (sections.firstChild !== empty) sections.replaceChildren(empty)
+        return
+      }
+      const groups: HTMLElement[] = []
+      for (const scope of ['project', 'user'] as const) {
+        const members = agents.filter(agent => agent.scope === scope)
+        if (members.length === 0) continue
+        let group = sections.querySelector<HTMLElement>(`.ap-group[data-scope="${scope}"]`)
+        if (group === null) {
+          group = el('section', 'ap-group')
+          group.dataset.scope = scope
+          const label = el('div', 'ap-label')
+          label.append(el('span', 'ap-scope', scope === 'project' ? 'Project' : 'User'), el('span', 'ap-path'))
+          group.append(label, el('div', 'ap-list'))
+        }
+        const path = group.querySelector('.ap-path')
+        if (path !== null) setText(path, `${scope === 'project' ? AGENTS_DIR : `~/${AGENTS_DIR}`} · ${members.length}`)
+        const list = group.querySelector('.ap-list') as HTMLElement
+        members.forEach((agent, index) => {
+          const key = `${scope}:${agent.name}`
+          let row = rows.get(key)
+          if (row === undefined) {
+            row = makeRow(agent.name)
+            rows.set(key, row)
+          }
+          fill(row, agent)
+          if (list.children[index] !== row) list.insertBefore(row, list.children[index] ?? null)
+        })
+        while (list.children.length > members.length) list.lastElementChild?.remove()
+        groups.push(group)
+      }
+      groups.forEach((group, index) => {
+        if (sections.children[index] !== group) sections.insertBefore(group, sections.children[index] ?? null)
+      })
+      while (sections.children.length > groups.length) sections.lastElementChild?.remove()
+    },
+  }
+}