@g3nomaly/g3n-mods 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,76 @@
+# @g3nomaly/g3n-mods
+
+The g3n mods for Claude Code. A mod adds a pane, a status line, a slash command or a hook to Claude Code.
+
+This package holds the mods themselves. You don't install it directly. The installer, [`@g3nomaly/mods`](https://www.npmjs.com/package/@g3nomaly/mods), knows it as the built-in `g3n-mods` source and copies mods out of it into your project.
+
+## How to install
+
+Run these from the root of your project:
+
+```sh
+bunx @g3nomaly/mods init                # creates .claude/mods.json and sets up VS Code
+bunx @g3nomaly/mods add context-bar     # installs one mod
+bunx @g3nomaly/mods add g3n-mods        # installs every mod in this package
+```
+
+Then open the project in VS Code and trust the workspace. New sessions load the mods, and `/reload-plugins` loads them into a session that is already open. Updating, removing and installing for every project with `--user` are covered in the [`@g3nomaly/mods` README](https://www.npmjs.com/package/@g3nomaly/mods).
+
+## The mods
+
+| Mod | What it does | Command |
+|---|---|---|
+| `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` | Each subagent as a crab with a hat: effort tier, model, steps, context, tokens, cost and time | `/crabs` |
+| `delete-guard` | Denies `rm -rf` and other permanent deletes and tells Claude which trash command to use instead | `/delete-guard on \| off` |
+| `focus-mode` | A timed focus block with a countdown, a progress bar and an end button. 25 minutes unless you pass a number | `/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` |
+| `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`, `custom-crab-agents` and `tool-timeline`, the command opens the pane and running it again closes it.
+
+Three mods take settings, declared under `userConfig` in their `.claude-plugin/plugin.json`:
+
+- `focus-mode`: `minutes`, the default block length (25).
+- `hide-personal-data`: `names`, extra names to always mask, separated by commas.
+- `you-should-know`: `minChars`, the shortest reply that gets a card (1500), and `model`, the model that picks the key point (`haiku`).
+
+## Requirements
+
+- [Bun](https://bun.sh), to run the installer
+- Claude Code for VS Code (`anthropic.claude-code`) 2.1.296 or newer. The mods are typed against that release.
+
+The mods also load in the terminal, but they are built for the VS Code extension.
+
+## Making your own mod
+
+Each mod here is a plugin folder under `mods/`, and `.claude-plugin/marketplace.json` lists them:
+
+```
+mods/<name>/
+├── .claude-plugin/plugin.json   # name, version, description
+├── hooks/hooks.json             # { "modules": ["./register.tsx"] }
+├── hooks/register.tsx           # exports `register`
+└── types/index.d.ts
+```
+
+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
+
+Run `bun install` at the repository root first, then these from `packages/g3n-mods`:
+
+```sh
+bun run build       # rewrites .claude-plugin/marketplace.json from each mod's plugin.json
+bun run typecheck
+bun run validate    # runs `claude plugin validate` on every mod
+bun run types       # copies the mod API types into types/claude-code.d.ts
+```
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license). See `LICENSE`.

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

@@ -157,6 +157,7 @@ export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'agents-panel', description: 'Show or hide the agents panel' })
     await loadAgents($)
+    void $.ui.open({ id: PANE, title: TITLE })
     $.clock.every(1000, () => void pollRunning($))
     return next(e)
   })

package/mods/custom-crab-agents/hooks/register.tsx

@@ -340,6 +340,7 @@ export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'crabs', description: 'Show or hide the subagent crabs' })
     await readWindow($)
+    void $.ui.open({ id: PANE, title: TITLE })
     $.clock.every(1000, () => void tick($))
     return next(e)
   })

package/mods/focus-mode/hooks/register.tsx

@@ -122,6 +122,7 @@ export const register: Register = (on, options) => {
       description: `Start a focus block (${defaultMinutes} min by default), or end the running one`,
       argumentHint: '[minutes] | end',
     })
+    void $.ui.open({ id: PANE, title: TITLE })
     $.clock.every(1000, () => void tick($))
     return next(e)
   })

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

@@ -187,6 +187,7 @@ export const register: Register = on => {
     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)
+    void $.ui.open({ id: PANE, title: TITLE })
     $.clock.every(1000, () => void tick($))
     return next(e)
   })

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

@@ -28,6 +28,15 @@ const TOOL_COLORS: ReadonlyArray<[RegExp, string]> = [
   [/^(Agent|Task)$/, '#f09bb5'],
 ]
 
+/** Background of a row's hover card. */
+const CARD = '#1b1f27'
+
+/** Idle time between calls, in milliseconds, kept on the bars' axis; longer idle stretches shrink to this. */
+const IDLE_MS = 200
+
+/** Most characters of a call's input the hover card keeps. */
+const DETAIL_MAX = 2000
+
 /** 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
 
@@ -59,6 +68,47 @@ export function labelOf(input: Record<string, unknown>): string {
   return first?.replace(/\s+/g, ' ').trim() ?? ''
 }
 
+/**
+ * @brief Finds a call's whole input text for the row's hover card: the full command, path, pattern or first text field.
+ *
+ * @param input - Arguments of the tool call.
+ * @returns The text with its line breaks, cut at `DETAIL_MAX` characters.
+ */
+export function detailOf(input: Record<string, unknown>): string {
+  const field = LABEL_FIELDS.find(name => typeof input[name] === 'string' && input[name] !== '')
+  const value = field === undefined ? Object.values(input).find((one): one is string => typeof one === 'string') : (input[field] as string)
+  const text = value?.trim() ?? ''
+  return text.length > DETAIL_MAX ? `${text.slice(0, DETAIL_MAX - 1)}…` : text
+}
+
+/** Where a call sits on the bars' axis, in milliseconds from the first shown call's start. */
+type Span = { from: number; to: number }
+
+/**
+ * @brief Places calls on one time axis, shrinking idle stretches between them to `IDLE_MS`, so the bars read as a waterfall.
+ *
+ * @param list - Calls in start order.
+ * @param now - Current time, the end of calls still running.
+ * @returns Each call's span, in `list` order, and the axis length (at least 1).
+ */
+export function placeCalls(list: readonly TimelineCall[], now: number): { spans: Span[]; length: number } {
+  const origin = list[0]?.startedAt ?? now
+  let busyUntil = origin
+  let shift = 0
+  let length = 1
+  const spans = list.map(call => {
+    const end = Math.max(call.startedAt, call.endedAt ?? now)
+    const idle = call.startedAt - busyUntil
+    if (idle > IDLE_MS) shift += idle - IDLE_MS
+    busyUntil = Math.max(busyUntil, end)
+    const from = call.startedAt - origin - shift
+    const to = end - origin - shift
+    length = Math.max(length, to)
+    return { from, to }
+  })
+  return { spans, length }
+}
+
 /**
  * @brief Joins the text of a tool result's content, which is a string or a list of text blocks.
  *
@@ -146,16 +196,16 @@ function replacementOf(list: readonly TimelineCall[], index: number): TimelineCa
 }
 
 /**
- * @brief Builds the SVG of a track with a bar filled to `fill` pixels.
+ * @brief Builds the SVG of a track with a bar from `x` that is `fill` pixels long.
  *
  * @param width - Width of the track in pixels.
- * @param fill - Filled length in pixels, clamped to the width.
+ * @param x - Start of the bar in pixels.
+ * @param fill - Length of the bar in pixels.
  * @param color - Fill color.
  * @returns The SVG markup.
  */
-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>`
+function barSvg(width: number, x: number, fill: number, color: string): string {
+  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 x="${x.toFixed(1)}" width="${fill.toFixed(1)}" height="8" rx="2" fill="${color}"/></svg>`
 }
 
 /**
@@ -182,12 +232,15 @@ export const register: Register = on => {
 
   on('tool.call', async ($, e, next) => {
     const startedAt = await $.clock.now()
-    const label = labelOf(e as unknown as Record<string, unknown>)
+    const input = e as unknown as Record<string, unknown>
+    const label = labelOf(input)
+    const detail = detailOf(input)
     await patchCall($, e.tool_use_id, call => ({
       ...call,
       id: e.tool_use_id,
       tool: e.tool,
       label,
+      detail,
       status: 'running',
       startedAt,
       agentId: e.agentId,
@@ -209,7 +262,7 @@ export const register: Register = on => {
         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 })
+        await patchCall($, id, call => call ?? { id, tool, label: labelOf(input), detail: detailOf(input), status: 'queued', startedAt: now, agentId: e.agentId })
       }
     }
     if (e.door === 'tool-result') {
@@ -236,27 +289,32 @@ export const register: Register = on => {
     const shown = list.slice(-room)
     /** Length of a call so far, or up to its end when it has one. */
     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 axis = placeCalls(shown, now)
     const barCells = Math.max(8, Math.floor(e.props.bodyColumns * 0.3))
     const labelCells = Math.max(12, e.props.bodyColumns - barCells - 12)
 
-    /** Draws the bar showing a call's share of the longest call's time. */
-    const bar = (call: TimelineCall) => {
+    /** Draws a call's bar on the shared axis: where it started and how long it ran, idle time between calls shrunk. */
+    const bar = (call: TimelineCall, span: Span) => {
       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)
+      const start = span.from / axis.length
+      const share = call.status === 'denied' ? 0.03 : Math.max(0.02, (span.to - span.from) / axis.length)
       if (e.surface === 'terminal') {
         const filled = Math.max(1, Math.round(share * barCells))
+        const before = Math.min(barCells - filled, Math.round(start * barCells))
         return (
           <Text>
+            <Text color={TRACK}>{'▬'.repeat(before)}</Text>
             <Text color={color}>{'▬'.repeat(filled)}</Text>
-            <Text color={TRACK}>{'▬'.repeat(barCells - filled)}</Text>
+            <Text color={TRACK}>{'▬'.repeat(barCells - before - 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 fill = Math.max(3, share * width)
+      const x = Math.min(width - fill, start * width)
+      return <Svg source={barSvg(width, x, fill, color)} alt={`${call.tool} ${seconds(durationOf(call))}`} width={width} height={8} />
     }
 
     /** Renders a call's status at the end of its row: its time, `denied`, `queued` or a mark for an error. */
@@ -270,32 +328,37 @@ export const register: Register = on => {
       }
     }
 
-    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>
-          )}
+    // One line per call; the keyed row reveals a card with the call's whole input while the pointer is on it.
+    const rows = shown.map((call, index) => (
+      <Box key={call.id} flexDirection="row" columnGap={1}>
+        <Text bold color={CARD} 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, axis.spans[index] ?? { from: 0, to: 0 })}
+        <Box width={8} justifyContent="flex-end">{outcome(call)}</Box>
+        <Box position="absolute" top={1} left={4} right={0} display="none" hover={{ display: 'flex' }} backgroundColor={CARD} borderStyle="round" borderColor={DIM} paddingX={1}>
+          <Text wrap="wrap">{call.tool} <Text dimColor>{call.detail ?? call.label}</Text></Text>
         </Box>
-      )
+      </Box>
+    ))
+
+    // Denied calls get their callout under the list, so every call keeps to its one line.
+    const callouts = shown.flatMap((call, index) => {
+      if (call.status !== 'denied') return []
+      const replacement = replacementOf(shown, index)
+      return [
+        <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>,
+      ]
     })
 
     return (
@@ -305,6 +368,7 @@ export const register: Register = on => {
           <Text dimColor>{list.length} call{list.length === 1 ? '' : 's'} · {seconds(total)}</Text>
         </Box>
         {rows}
+        {callouts.length > 0 && <Box flexDirection="column" marginTop={1}>{callouts}</Box>}
       </Box>
     )
   })

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

@@ -9,6 +9,8 @@ export type TimelineCall = {
   tool: string
   /** Short form of the call's input, e.g. `rm -rf dist` or `package.json` */
   label: string
+  /** The call's whole input text for the row's hover card, e.g. the full command or path */
+  detail?: string
   status: CallStatus
   startedAt: number
   endedAt?: number

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-mods",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The g3n Claude Code mods: panes, status lines, commands and hooks, installed with @g3nomaly/mods.",
   "type": "module",
   "files": [