Mit einem Mod in der Oberfläche zeichnen

​

Einen Bereich mit Tabs erstellen

{
  "name": "hello-tabs",
  "version": "0.1.0",
  "description": "Opens a pane with two tabs and a counter",
  "author": { "name": "Your Name" }
}

{
  "modules": ["./register.js"]
}

// The pane's id, used to open the pane and to recognize it when drawing
const PANE = 'hello-tabs'

// What the pane shows: which tab is open, and the counter's value
let tab = 'one'
let count = 0

export function register(on) {
  // Runs before your first prompt, and again after a reload
  on('session.start', async ($, e, next) => {
    await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })
    // Load the count an earlier session saved, if there is one
    const saved = await $.store.get('count')
    if (typeof saved === 'number') count = saved
    return next(e)
  })

  // Runs when you type /hello-tabs
  on('command.run', { command: 'hello-tabs' }, async ($) => {
    // Open the pane, give it the keyboard, and let Esc close it
    await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })
    // Print nothing in the transcript
    return {}
  })

  // Runs each time Claude Code draws a pane
  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
    // Leave other mods' panes alone
    if (e.requestId !== PANE) return next(e)
    // Get the elements this app can draw
    const { Box, Text, Button } = $.ui.resolve(e)
    // Ask Claude Code to run this hook again
    const redraw = () => $.ui.invalidate('ui.render')

    // One tab: a button that switches to its tab when pressed
    const tabButton = (name, label, hotkey) =>
      Button({
        key: 'tab-' + name,
        label,
        hotkey,
        plain: true,
        // Dim the tab that isn't open
        dimColor: tab !== name,
        onPress: () => {
          tab = name
          redraw()
        },
      })

    // What goes under the tabs, depending on which one is open
    const body =
      tab === 'one'
        ? [Text({ children: ['This is the first tab.'] })]
        : [
            Box({
              flexDirection: 'row',
              columnGap: 2,
              children: [
                Button({
                  key: 'more',
                  label: 'Add one',
                  hotkey: 'a',
                  onPress: async () => {
                    count += 1
                    redraw()
                    // Save the count so it's there after a restart
                    await $.store.set('count', count)
                  },
                }),
                Text({ children: ['Count: ' + count] }),
              ],
            }),
          ]

    // The whole pane: the row of tabs, a blank line, then the body
    return Box({
      flexDirection: 'column',
      children: [
        Box({
          flexDirection: 'row',
          columnGap: 3,
          children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],
        }),
        Text({ children: [' '] }),
        ...body,
      ],
    })
  })
}

​

Wählen Sie, wo gezeichnet wird

​

Ändern, was Claude Code bereits zeichnet

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  // Keep Claude Code's spinner, and change the text after its word
  return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Thinking · tool calls: 2…

on('ui.render', { component: 'Spinner' }, async ($, e) => {
  const { Text } = $.ui.resolve(e)
  // No call to next, so this line is drawn in the spinner's place
  return Text({ children: ['Claude has made ' + calls + ' tool calls'] })
})

Claude has made 2 tool calls

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  // Nothing to show yet, so pass the event on unchanged
  if (calls === 0) return next(e)
  return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Thinking…

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  const { Box, Text } = $.ui.resolve(e)
  const theirs = await next(e)
  return Box({ flexDirection: 'column', children: [theirs, Text({ children: ['under the spinner'] })] })
})

​

Ein Pane zum richtigen Zeitpunkt öffnen

await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

await $.ui.close({ id: 'hello-tabs' })

const pane = { id: 'hello-tabs', title: 'Hello tabs' }
await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

​

Toasts hinter einem Dialog zurückhalten

​

Wenn ein Pane auf ein breiteres Terminal wartet

• Durch eine Aktion des Benutzers geöffnet, etwa einen ausgeführten Befehl oder eine gedrückte Schaltfläche: Das Pane erscheint bei jeder Breite
• Durch Ihren Mod von sich aus geöffnet, etwa über einen Timer oder einen turn.start-Hook: Das Pane erscheint nur in einem Terminal mit mindestens 144 Spalten Breite. Nachdem der Benutzer dieses Pane einmal selbst geöffnet hat, reichen 110 Spalten aus.

​

In der VS Code-Erweiterung zeichnen

• Panes: In einem Panel mit mindestens 800 Pixeln Breite werden Panes neben der Konversation angedockt, e.props.placement ist 'dock' und e.viewport.isFullscreen ist true. In einem schmaleren Panel werden Panes über dem Prompt-Eingabefeld gezeichnet, placement ist 'inline', und ein Pane zeigt 12 Zeilen an, bevor es scrollt.
• Toasts und Statuszeilen: Diese befinden sich in einem gemeinsamen Stapel direkt über dem Prompt-Eingabefeld, bei schmalem Panel zusammen mit den Panes, mit einer Statuszeile pro Mod. Der Stapel wird ausgeblendet, solange eine Berechtigungsanfrage oder ein Dialog angezeigt wird.
• Beschriftungen: Das Panel umrahmt, was ein Mod zeichnet oder umschreibt, und beschriftet es mit dem Namen des Plugins, etwa From the token-chart plugin oder Edited by the token-chart plugin.
• Tastatur: Schaltflächen haben keine Tastenkürzel, daher klickt der Benutzer auf eine Schaltfläche oder drückt Enter, sobald sie den Fokus hat.
• Tastaturfokus: Das Panel gewährt die Anfrage focus: true eines Panes nur, wenn das Panel den Fokus hat, Claude untätig ist und keine Frage wartet und das Prompt-Eingabefeld leer ist.
• Der Fragedialog: Bei AskUserQuestion behält das Panel seine eigene Fragekarte und zeichnet Ihre Elemente darüber. Props, die Sie an next übergeben, ändern die Karte nicht.
• Prompt-Vorschläge: $.prompt.suggest wird mit isShown: false aufgelöst und zeigt nichts an, da das Panel den abgeblendeten Vorschlagstext des Prompt-Eingabefelds für Claudes eigene Vorschläge reserviert.
• Textlimits: Das Panel kürzt eine Statuszeile nach 200 Zeichen oder zwei Zeilen und einen Toast nach 500 Zeichen.

​

Einen Baum aus Elementen erstellen

Text({ children: ['This is the first tab.'] })

This is the first tab.

Box({
  flexDirection: 'row',
  columnGap: 2,
  children: [
    Button({ key: 'more', label: 'Add one', onPress: addOne }),
    Text({ children: ['Count: 0'] }),
  ],
})

[ Add one ]  Count: 0

Button({ key: 'more', label: 'Add one', onPress: addOne })
Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

[ Add one ]
1: One

Input({
  key: 'new-note',
  label: 'Note',
  placeholder: 'Type a note and press Enter',
  value: '',
  submitLabel: 'add',
  onSubmit: addNote,
})

Note: Type a note and press Enter

​

Link in der Desktop-App und in VS Code

• Schema und Host: eine https:-URL oder eine http://localhost-URL wie http://localhost:3000
• Kein @: Schreiben Sie ein @ im Pfad oder in der Query als %40
• Schreibweise: das, was new URL(href).href zurückgibt, abgesehen von einem fehlenden / nach dem Host. Das schließt einen Host in Großbuchstaben, ein Leerzeichen und :443 bei einer https:-URL aus.

​

Wenn ein Client fehlschlägt

​

Ein Raster aus farbigen Zellen zeichnen

// The value that means "use the terminal's default color"
const DEFAULT_COLOR = 0x01000000

// Pack rows of [character, color] pairs into the one string a Raster takes
// One cell is three numbers: the character's code point, its color, and its background
function cellsOf(rows) {
  const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])
  return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()
}

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Draw only in the pane opened with the id 'heat'
  if (e.requestId !== 'heat') return next(e)
  const { Box, Text, Raster } = $.ui.resolve(e)
  // Two rows of three cells, each a block character and its color
  const rows = [
    [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
    [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
  ]
  if (e.surface !== 'terminal') {
    return Text({ children: ['The heat map needs the terminal.'] })
  }
  return Box({
    flexDirection: 'column',
    children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],
  })
})

​

Auf Tastendrücke und Eingaben reagieren

• Button: nimmt onPress(e) entgegen, wobei e.surface die App ist, aus der der Tastendruck kam
• Input: nimmt onSubmit(value) und onInput(value) entgegen
• Select: nimmt onSelect(value) entgegen, mit seinen Auswahlmöglichkeiten in options, einer Liste mit mindestens einer Auswahl mit eindeutigen Werten, etwa [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

​

Tastaturfokus und Hotkeys

​

Wie ein Bereich den Tastaturfokus erhält

• Ihr Mod ihn mit focus: true aus einem Befehl oder einem Tastendruck heraus öffnet
• Der Benutzer Ctrl+X und dann Tab drückt
• Der Benutzer darauf klickt

​

Was jede Taste bewirkt

​

Einen Hotkey und den ersten Fokus festlegen

• hotkey: Damit der Benutzer einen Button mit einer Taste drücken kann, geben Sie ihm einen hotkey aus einer Ziffer oder einem Kleinbuchstaben, wie in hotkey: 'a'
• autoFocus: Um festzulegen, welches Steuerelement beim Öffnen des Bereichs den Fokus hat, fügen Sie ihm autoFocus: true hinzu. In der VS Code-Erweiterung bewirkt autoFocus nichts: Das Steuerelement wird so gezeichnet, als hätten Sie die Prop weggelassen, und Sie müssen nichts ändern. Die Prop akzeptiert nur true, lassen Sie sie also bei den anderen Steuerelementen weg.

​

Texteingaben entgegennehmen und für jedes Element eine Zeile zeichnen

╭────────────────────────────────────────────────────────✕─╮
│ Note: Type a note and press Enter ⏎ add                  │
│ x buy milk │
│ x call bob │
╰──────────────────────────────────────────────────────────╯

• Texteingaben entgegennehmen: Ein Input ruft onSubmit(value) mit dem Text des Felds auf, wenn der Benutzer Enter drückt, und onInput(value) bei jeder Änderung
• Eine Liste zeichnen: Ordnen Sie Ihren Daten jeweils eine Zeile zu und geben Sie der Schaltfläche jeder Zeile einen eigenen key

// The list the pane draws
let notes = []

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Draw only in the pane opened with the id 'notes'
  if (e.requestId !== 'notes') return next(e)
  const { Box, Text, Button, Input } = $.ui.resolve(e)
  const redraw = () => $.ui.invalidate('ui.render')

  return Box({
    flexDirection: 'column',
    children: [
      Input({
        key: 'new-note',
        label: 'Note',
        placeholder: 'Type a note and press Enter',
        // Draw the field empty each time, which clears it after a submit
        value: '',
        submitLabel: 'add',
        autoFocus: true,
        // Runs when you press Enter in the field
        onSubmit: async (value) => {
          // Ignore an empty line
          if (!value.trim()) return
          notes = [...notes, value.trim()]
          redraw()
          await $.store.set('notes', notes)
        },
      }),
      // One row for each note: a delete button, then the note's text
      ...notes.map((note, i) =>
        Box({
          flexDirection: 'row',
          columnGap: 1,
          children: [
            Button({
              // A key of its own, so each row's button can be told apart
              key: 'delete-' + i,
              label: 'x',
              plain: true,
              onPress: async () => {
                notes = notes.filter((_, j) => j !== i)
                redraw()
                await $.store.set('notes', notes)
              },
            }),
            Text({ children: [note] }),
          ],
        }),
      ),
    ],
  })
})

• Eine Notiz hinzufügen: Tippen Sie eine Zeile und drücken Sie Enter. Die Zeile erscheint als neue Zeile in der Liste, und das Feld wird geleert.
• Eine Notiz löschen: Drücken Sie Tab, bis die x-Schaltfläche der Notiz den Fokus hat, und drücken Sie dann Enter. Das x ist die Beschriftung der Schaltfläche und kein Hotkey, daher wird sie durch Tippen des Buchstabens nicht gedrückt.

​

Einen Bereich neu zeichnen

​

Wann Claude Code ohne Aufforderung neu zeichnet

​

Neu zeichnen, wenn sich Ihre Daten ändern

let count = 0

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  if (e.requestId !== 'counter') return next(e)
  const { Box, Text, Button } = $.ui.resolve(e)
  return Box({
    flexDirection: 'row',
    columnGap: 2,
    children: [
      Button({
        key: 'more',
        label: 'Add one',
        onPress: () => {
          count += 1
          // The data changed, so ask Claude Code to draw the pane again
          $.ui.invalidate('ui.render')
        },
      }),
      Text({ children: ['Count: ' + count] }),
    ],
  })
})

​

Zeitgesteuert neu zeichnen

on('session.start', async ($, e, next) => {
  // Every 1000 milliseconds, ask Claude Code to draw your sites again
  $.clock.every(1000, () => $.ui.invalidate('ui.render'))
  return next(e)
})

​

Wie oft ein Bereich neu gezeichnet werden kann

​

Zustand speichern

​

Einen Wert in $.state speichern

​

Die Werte deklarieren

declare module 'claude-code' {
  interface PluginState {
    'hello-tabs': {
      tab: 'one' | 'two'
      count: number
    }
  }
}

​

Im Manifest auf die Deklaration verweisen

{
  "name": "hello-tabs",
  "version": "0.1.0",
  "description": "Opens a pane with two tabs and a counter",
  "author": { "name": "Your Name" },
  "types": "./types/index.d.ts"
}

​

Einen Wert definieren, lesen und schreiben

import { atom, read, update } from 'claude-code'

// At the top of the module: name the value and give its default
const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

// In the ui.render hook: read the value to draw it
const n = await read($, count)

// In a Button: write a new value from the old one
onPress: () => update($, count, (value) => value + 1)

• Schreiben Sie plugin und key als String-Literale: claude plugin validate liest sie aus Ihrem Quellcode
• Speichern Sie das Ergebnis jedes atom-Aufrufs in einer const: Wenn Sie count mit let deklarieren, schlägt die Validierung mit takes a source the scan can read fehl
• Deklarieren Sie jeden Wert in der Typdeklarationsdatei: Andernfalls schlägt die Validierung mit hello-tabs.count is not declared fehl
• Schreiben Sie aus einem Callback oder dem Hook eines anderen Events: Ein ui.render-Hook kann Zustand lesen, aber nicht schreiben, schreiben Sie also aus onPress, onSubmit oder einem Hook für ein anderes Event

​

hello-tabs auf $.state umstellen

• Am Anfang des Moduls: Fügen Sie die import-Zeile hinzu und ersetzen Sie let count = 0 durch die atom-Zeile
• Im ui.render-Hook: Fügen Sie die read-Zeile vor tabButton hinzu und zeichnen Sie 'Count: ' + n im Text
• In der Schaltfläche Add one: Ersetzen Sie onPress durch die Variante aus Aus mehr als einer Sitzung speichern, die den Zähler sowohl speichert als auch schreibt
• Im session.start-Hook: Ersetzen Sie die beiden Zeilen, die saved lesen, durch den loadCount-Aufruf aus Einen gespeicherten Wert nach /clear erneut laden

​

Einen gespeicherten Wert nach /clear erneut laden

// Copy the saved count from $.store into $.state, or 0 if nothing is saved
async function loadCount($) {
  const saved = Number((await $.store.get('count')) ?? 0)
  await update($, count, () => saved)
}

// Runs before your first prompt, and again after a reload
on('session.start', async ($, e, next) => {
  await loadCount($)
  return next(e)
})

// Runs again after /clear, /resume, and /branch, which reports fork
on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {
  await loadCount($)
  return next(e)
})

​

Aus mehr als einer Sitzung speichern

• Geben Sie jedem Element einen eigenen Schlüssel: Ein set ändert nur seinen eigenen Schlüssel, sodass Sitzungen, die unterschiedliche Schlüssel schreiben, sich nicht gegenseitig überschreiben
• Lesen Sie direkt vor dem Schreiben erneut: Rufen Sie für einen Wert, den mehrere Sitzungen ändern, den Schlüssel im Callback mit get ab und bilden Sie den neuen Wert daraus, nicht aus einer Kopie, die Sie bei session.start geladen haben. Der Schreibvorgang einer anderen Sitzung geht trotzdem verloren, wenn er zwischen Ihrem get und Ihrem set stattfindet.

onPress: async () => {
  // Read what the store holds now, which another session may have changed
  const saved = Number((await $.store.get('count')) ?? 0)
  // Save the new count, then show it
  await $.store.set('count', saved + 1)
  await update($, count, () => saved + 1)
}

​

Nächste Schritte

• Auf Ereignisse reagieren: Versorgen Sie Ihre Zeichnung mit Daten aus Tool-Aufrufen und Turns
• Die Mods-API verwenden: Versorgen Sie Ihre Zeichnung mit Daten aus Timern und Modellaufrufen
• Eine Zeichnung testen: Betätigen Sie Ihre Schaltflächen aus einem Test heraus, auf mehr als einer Oberfläche
• Render-Stellen und Elemente: die Props jeder Render-Stelle und die Props jedes Elements