Вкладки — это две кнопки в ряду. Мод отслеживает, какая из них активна, и рисует содержимое этой вкладки под рядом.

1. Создание плагина

Мод — это плагин с манифестом, hooks.json, который указывает на ваш код, и файл кода. Создание мода объясняет каждый из них. Создайте каталог с именем hello-tabs с каталогами .claude-plugin и hooks внутри него, затем сохраните первые два файла.

Сохраните манифест как hello-tabs/.claude-plugin/plugin.json:

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

Назовите точку входа в hello-tabs/hooks/hooks.json:

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

2. Написание кода

В этом списке указано, что делает каждый хук, в том порядке, в котором они появляются в коде:

• Добавляет команду /hello-tabs и загружает счет, сохраненный предыдущей сессией
• Открывает панель при запуске этой команды
• Рисует содержимое панели: ряд вкладок и тело открытой вкладки

Две переменные уровня модуля, tab и count, содержат состояние панели.

Сохраните это как hello-tabs/hooks/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,
      ],
    })
  })
}

Каждый хук также делает что-то, что код не делает явным:

• session.start также читает сохраненный счет из $.store, хранилища ключ-значение, которое сохраняется между сессиями.
• command.run только сообщает Claude Code, что панель существует. Открытие панели ничего не рисует само по себе: Claude Code затем вызывает ui.render, чтобы спросить, что в ней находится.
• ui.render возвращает дерево элементов, Box, который содержит другие боксы, текст и кнопки, и создает его заново из tab и count каждый раз, когда он запускается.

Нажатие кнопки запускает ее обратный вызов onPress, который изменяет переменную и вызывает redraw. Claude Code затем запускает хук ui.render снова, и хук создает новое дерево из новых значений. Каждое интерактивное рисование использует этот цикл рендеринга: обратный вызов изменяет состояние, и хук рисует снова из нового состояния.

3. Открытие панели

В вашей оболочке запустите Claude Code с помощью claude --plugin-dir ./hello-tabs. В промпте Claude Code запустите /hello-tabs. Панель открывается с 1: One и 2: Two в верхней части. Нажмите 2, затем нажмите a, горячую клавишу для Add one, несколько раз. Счет растет.

4. Проверка того, что счет был сохранен

Нажмите Esc, чтобы закрыть панель, затем выйдите из сессии. В вашей оболочке запустите Claude Code снова с той же командой claude --plugin-dir ./hello-tabs, и в промпте Claude Code запустите /hello-tabs. Счет находится там, где вы его оставили.

Чтобы очистить счет, попросите мод вызвать $.store.delete('count'). Сохранение состояния охватывает, как долго длится каждый вид значения.

Выбор места для рисования

Хук ui.render запускается для каждого сайта рендеринга, если вы не сузите его до того, в котором хотите рисовать. Чтобы выбрать сайт рендеринга, передайте фильтр, называемый matcher, в качестве второго аргумента для on. { component: 'Pane' } запускает хук только для панелей. В хуке e.component называет сайт, e.surface говорит, какое приложение рисует, а e.props содержит собственные данные сайта. Для панели e.requestId — это id, с которым вы ее открыли.

Панель и полоса пусты, пока мод их не заполнит. Выберите вкладку, чтобы увидеть, что представляет собой каждая из них и как в ней рисовать:

Pane

Панель — это боковая панель рядом с транскриптом в широком полноэкранном терминале или обрамленная область над промптом в противном случае. При открытии нескольких панелей каждая получает вкладку, которая показывает ее название.

Панель появляется, когда ваш мод вызывает $.ui.open с id, который вы выбираете, как в $.ui.open({ id: 'hello-tabs' }). Открытие панели в нужное время охватывает другие поля и случаи, когда панель ждет более широкого терминала.

Чтобы рисовать в вашей панели, отфильтруйте по { component: 'Pane' } и проверьте, что e.requestId — это ваш id.

Band above the prompt

Полоса — это полоса прямо над полем ввода промпта. Она присутствует всегда, и все моды используют ее совместно.

Ваш хук возвращает дерево, чтобы показать что-то в полосе, или next(e), чтобы ничего не показывать. Дерево заменяет то, что моды после вашего рисуют там. Чтобы сохранить их вывод, поместите результат await next(e) среди дочерних элементов Box в вашем дереве.

Чтобы рисовать в полосе, отфильтруйте по { component: 'AbovePrompt' }.

Изменение того, что уже рисует Claude Code

Claude Code рисует большую часть своего интерфейса сам: сообщения, строки вызовов инструментов, спиннер и многое другое. Каждая из этих частей также является сайтом рендеринга, поэтому мод может изменить ее стиль или заменить ее. Чтобы изменить одну из них, отфильтруйте ваш хук ui.render по ее имени из этой таблицы:

Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage и точки отрисовки вызовов инструментов работают в терминале, приложении Desktop и расширении VS Code. Таблица точек отрисовки указывает, где вызывается каждая из остальных.

На сайте, который Claude Code уже рисует, ваш хук может изменить деталь, заменить рисование или оставить его в покое. Выберите вкладку, чтобы увидеть каждый из вариантов, применяемый к спиннеру. Примеры читают переменную calls, которую подсчитывает другой хук, как в учебном моде.

Change a detail

Чтобы сохранить рисование Claude Code и изменить одну его часть, передайте next копию события с измененными props. Этот хук изменяет текст после слова спиннера:

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…

Replace the drawing

Чтобы нарисовать что-то свое на месте сайта, верните дерево и не вызывайте next. Этот хук рисует одну строку текста там, где был бы спиннер:

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 работает, показывается ваша строка, а спиннер Claude Code не показывается:

Claude has made 2 tool calls

Leave it alone

Чтобы оставить сайт таким, каким его рисует Claude Code, верните next(e). Хук часто делает это для одних событий и не делает для других. Этот хук оставляет спиннер в покое, пока нечего считать:

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…

На этих сайтах next(e) возвращает ссылку на рисование Claude Code, { type: 'engine', ref }, если только мод, который запускается после вашего, не вернул собственное дерево. Чтобы изменить то, что находится в этом рисовании, передайте next копию события с другими props, как это сделано на вкладке Change a detail. Вы можете вернуть ссылку как есть или поместить ее в Box рядом с собственными элементами:

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'] })] })
})

Пока Claude работает, спиннер анимируется как прежде, а под ним появляется under the spinner.

Запрос разрешения не является сайтом рендеринга, поэтому мод не может изменить то, что он показывает. Диалог вопроса, AskUserQuestion, является таким сайтом, поэтому мод может его изменить. Дерево для диалога должно содержать ссылку ровно один раз, а ваши элементы — над ней. В противном случае Claude Code рисует собственный диалог.

Открытие панели в нужное время

Панель появляется только тогда, когда ваш мод ее открывает. То, как и когда вы ее открываете, определяет, получает ли она фокус клавиатуры, сколько места она запрашивает и появляется ли она вообще в узком терминале.

Чтобы открыть панель, вызовите $.ui.open с id, который вы выбираете. id — это имя панели: ваш хук ui.render проверяет его, и вы передаете его снова, чтобы закрыть панель.

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

Чтобы закрыть панель, вызовите $.ui.close с id, с которым вы ее открыли:

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

Помимо id, $.ui.open принимает эти необязательные поля:

Расширение VS Code игнорирует rows и columns и определяет размер панели само.

focus, closeOnEscape и holdToasts являются необязательными и принимают только true. Чтобы не задавать одно из них, опустите его. Передача false выбрасывает ошибку, такую как ui.open: focus is true or left out. Чтобы установить одно из них условно, добавляйте поле только тогда, когда условие выполняется. Этот вызов запрашивает фокус клавиатуры, только когда items не пусто:

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

Чтобы позволить команде открыть панель, пока Claude работает, добавьте immediate: true при регистрации команды. Без этого команда, введенная во время хода, ждет конца хода.

Удержание всплывающих уведомлений за диалогом

Передайте holdToasts: true в $.ui.open, когда панель — это диалог, на который пользователь отвечает и который затем покидает, чтобы всплывающие уведомления не появлялись, пока он принимает решение. В терминале удержание длится, пока показывается именно эта панель, а всплывающее уведомление, вызванное в это время, ждет окончания удержания.

Claude Code удерживает всплывающие уведомления других модов и собственные кратковременные уведомления, а также те, которые ваш мод вызывает с помощью $.ui.toast. Не задавайте это поле для панели, которая остается открытой, чтобы пользователь продолжал их видеть.

Когда панель ждет более широкого терминала

Панель, которую ваш мод открывает без запроса, не появляется в узком терминале, поэтому она не может захватить маленький экран. Появится ли она, зависит от того, что ее открыло:

• Открыто чем-то, что сделал пользователь, например командой, которую он запустил, или кнопкой, которую он нажал, — панель появляется при любой ширине
• Открыто вашим модом, действующим самостоятельно, например из таймера или хука turn.start, — панель появляется только в терминале шириной не менее 144 столбцов. После того как пользователь сам открыл эту панель хотя бы раз, достаточно 110 столбцов.

Когда панель появляется, $.ui.open разрешается в { isPlaced: true }. Когда панель ждет, isPlaced имеет значение false, а reason — это строка, объясняющая причину. Ожидающая панель появляется, когда пользователь ее открывает или расширяет терминал. Чтобы сообщить, что что-то доступно, не открывая панель, вызовите $.ui.toast('Your message'), который показывает всплывающее уведомление.

Рисование в расширении VS Code

В расширении VS Code то, что рисует мод, появляется на панели чата в расширении версии 2.1.299 или новее. Сессии, которая не получает флаги функций, например сессии в Amazon Bedrock, требуется версия 2.1.304 или новее. В хуке ui.render для панели чата e.surface имеет значение vscode. Чтобы проверить, какие точки отрисовки и элементы рисует панель чата и какие пропсы она игнорирует, см. таблицы точек отрисовки и элементов.

Чтобы мод работал на панели чата так же, как в терминале, учитывайте следующие различия:

• Панели: на панели чата шириной 800 пикселей или больше панели закрепляются рядом с диалогом, e.props.placement имеет значение 'dock', а e.viewport.isFullscreen — true. На более узкой панели чата панели рисуются над полем промпта, placement имеет значение 'inline', а панель показывает 12 строк, прежде чем начать прокрутку.
• Всплывающие уведомления и строки состояния: они располагаются в одном стеке прямо над полем промпта вместе с панелями, когда панель чата узкая, по одной строке состояния на мод. Стек скрывается, пока показывается запрос разрешения или диалоговое окно.
• Метки: панель чата обрамляет то, что мод рисует или переписывает, и помечает это именем плагина, например From the token-chart plugin или Edited by the token-chart plugin.
• Клавиатура: у кнопок нет горячих клавиш, поэтому пользователь нажимает кнопку мышью или нажимает Enter, когда она получила фокус.
• Фокус клавиатуры: панель чата выполняет запрос панели focus: true только тогда, когда панель чата находится в фокусе, Claude бездействует и не ожидает ответа на вопрос, а поле промпта пусто.
• Диалоговое окно вопроса: в AskUserQuestion панель чата сохраняет собственную карточку вопроса и рисует ваши элементы над ней. Пропсы, которые вы передаете в next, не изменяют карточку.
• Предложения промпта: $.prompt.suggest разрешается с isShown: false и ничего не показывает, потому что панель чата оставляет бледный текст предложения в поле промпта для собственных предложений Claude.
• Ограничения текста: панель чата обрезает строку состояния до 200 символов или двух строк, а всплывающее уведомление — до 500 символов.

Создание дерева из элементов

То, что возвращает хук ui.render, — это дерево элементов: описание того, что рисовать, состоящее из боксов, текста и элементов управления, вложенных друг в друга. Вы описываете рисование, и Claude Code рисует его в том приложении, которое открыто у пользователя: в терминале, приложении Desktop или расширении VS Code.

Чтобы получить элементы, вызовите $.ui.resolve(e) в вашем хуке, как в const { Box, Text, Button } = $.ui.resolve(e). Каждый элемент — это функция. Вы передаете ей свойства, и вы помещаете элементы и строки, которые идут внутри него, в children.

Выберите вкладку, чтобы увидеть каждый из самых распространенных элементов и то, как терминал его рисует:

Text

Text рисует строку с необязательным стилем, таким как bold и color:

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

This is the first tab.

Box

Box расставляет то, что находится внутри него, в ряд или столбец. Этот помещает кнопку и строку текста рядом, два столбца отдельно:

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

[ Add one ]  Count: 0

Button

Button — это элемент управления, который пользователь может нажать. Он запускает ваш обратный вызов onPress. С plain: true он не имеет скобок и показывает его горячую клавишу:

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

Input — это текстовое поле. Он запускает ваш обратный вызов onSubmit с текстом, когда пользователь нажимает Enter:

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

Добавьте rows, чтобы поле могло вмещать несколько строк. Enter по-прежнему отправляет текст, а обратная косая черта перед Enter начинает новую строку, как и Shift+Enter там, где терминал это поддерживает. В галерее показано поле с rows.

В галерее интерфейсов есть примеры и снимки экрана большинства элементов. Эта таблица перечисляет каждый элемент:

Если ваш модуль — это файл .tsx или .jsx, вы можете написать дерево как JSX. Сначала деструктурируйте элементы из $.ui.resolve(e).

Если ваш рисунок не отображается, проверьте его дерево на наличие пропа, который элемент не принимает, или дочернего элемента там, где его быть не должно. Хук, который возвращает такое дерево, завершается сбоем, а строка hook skipped называет ваш мод и правило, которое нарушило дерево. Для Text в панели с пропом bogusProp эта строка выглядит так:

my-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Text prop "bogusProp" is not allowed)

Link в приложении Desktop и VS Code

В приложении Desktop и расширении VS Code Link отображается как обычный текст, если его href не соответствует следующим требованиям:

• Схема и хост: URL https: или URL http://localhost, например http://localhost:3000
• Без @: записывайте @ в пути или запросе как %40
• Написание: то, что возвращает new URL(href).href, за исключением отсутствующего / после хоста. Это исключает хост в верхнем регистре, пробел и :443 в URL https:.

В терминале эти требования не действуют.

Когда Client завершается сбоем

В терминале, когда файл, который запускает Client, завершается сбоем, тусклая строка, например my-mod: Client client/spinner.js: boom, занимает место Client, а остальная часть вашего рисунка по-прежнему отображается.

Если ваш мод обрабатывает ui.fault, Claude Code затем рисует сайт заново.

Рисование сетки цветных ячеек

Для тепловой карты, спарклайна или игровой доски в терминале нарисуйте один Raster, а не Box для каждой ячейки. Raster принимает key, его размер в columns и rows, и cells — строку base64, которая упаковывает каждую ячейку. Каждая ячейка — это три числа: кодовая точка символа, его цвет и цвет фона. Цвет — это 24-битное значение RGB в шестнадцатеричной записи, например 0xc62828 для красного. Значение 0x01000000, на единицу выше этого диапазона, означает цвет терминала по умолчанию.

Приложения, кроме терминала, не имеют Raster, поэтому проверьте e.surface и нарисуйте текст там. Это тело панели рисует тепловую карту три на два:

// 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) })],
  })
})

В терминале панель показывает сетку:

Массив rows — это часть, которую вы бы изменили, и cellsOf превращает его в упакованную строку. Хук рисует только в панели, чей id — это heat, поэтому откройте один с $.ui.open({ id: 'heat' }) из команды, как пример hello-tabs открывает свою панель.

Каждый символ должен быть шириной в одну ячейку. Чтобы анимировать Raster, который уже на экране, вызовите $.ui.blit с id панели как requestId, key Raster, тем же размером и новыми ячейками. Для этого примера это $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Он перерисовывает только этот элемент без повторного запуска вашего хука ui.render.

Ответ на нажатия и ввод

Когда пользователь нажимает кнопку, вводит текст в поле или выбирает из списка, который нарисовал ваш мод, Claude Code вызывает обратный вызов этого элемента управления, который выполняется в вашем модуле. Каждый элемент управления принимает свои собственные обратные вызовы:

• Button: принимает onPress(e), где e.surface — это приложение, из которого пришло нажатие
• Input: принимает onSubmit(value) и onInput(value)
• Select: принимает onSelect(value) с его выборами в options, список по крайней мере одного выбора с уникальными значениями, такой как [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Каким элементам управления нужен key

Дайте каждому Input и Select проп key, например key: 'size'. Button может обойтись без key, если у него есть проп label или единственный строковый дочерний элемент. Тогда его ключом служит значение label или эта строка.

Тесты и другие моды определяют элемент управления по его ключу:

• Тесты: тест нажимает или вводит текст в элемент управления по его ключу.
• Другие моды: Claude Code запускает ui.press, ui.input или ui.select с ключом элемента управления в e.element до того, как выполнить обратный вызов этого элемента управления. Хук другого мода для этого события видит, что пользователь ввел в ваш Input, и может изменить этот текст или не дать вашему обратному вызову выполниться. API модов не дает этому моду метода для нажатия ваших кнопок.

Если сообщение говорит needs a key или is drawn twice, найдите причину по этому сообщению.

Фокус клавиатуры и горячие клавиши

Ваш мод никогда не читает клавиатуру сам. Пользователь нажимает клавишу, Claude Code решает, для какого из ваших элементов управления она предназначена, и запускается обратный вызов этого элемента управления. Кроме горячей клавиши цифры на полосе или привязки action, это происходит только пока ваша панель или полоса имеет фокус клавиатуры. Остальное время клавиши идут в промпт.

В расширении VS Code у кнопок нет горячих клавиш: пользователь щелкает по кнопке или нажимает на ней Enter и вводит текст в поля.

Как панель получает фокус клавиатуры

Панель получает фокус клавиатуры, когда:

• Ваш мод открывает ее с focus: true из команды или нажатия
• Пользователь нажимает Ctrl+X, затем Tab
• Пользователь щелкает по ней, для чего в терминале нужен полноэкранный рендеринг

Claude Code предоставляет focus: true только пока промпт пуст и ничто другое не имеет фокус клавиатуры. Панель, которая открывается, пока пользователь печатает, не берет его нажатия клавиш.

Что делает каждая клавиша

Эта таблица перечисляет, что делает клавиша, пока ваша панель или полоса имеет фокус клавиатуры:

Мод не может привязать Tab или клавиши со стрелками к чему-либо еще, поэтому игра управляется с помощью w, a, s и d.

Установка горячей клавиши и первого фокуса

• hotkey: чтобы позволить пользователю нажать Button одной клавишей, дайте ему hotkey одной цифры или одной строчной буквы, как в hotkey: 'a'
• autoFocus: чтобы выбрать, какой элемент управления имеет фокус при открытии панели, добавьте autoFocus: true к нему. В расширении VS Code autoFocus ничего не делает: элемент управления рисуется так, как если бы вы его не указали, и вам не нужно ничего менять. Проп принимает только true, поэтому не указывайте его для остальных элементов управления.

То, как горячая клавиша показывается, зависит от кнопки и приложения:

В терминале назовите клавишу в метке кнопки в скобках или используйте plain: true, чтобы пользователь мог видеть, что нажать. Справка элементов имеет другие правила Button: action, горячие клавиши цифр на полосе и две кнопки на одной горячей клавише.

Когда пользователь сворачивает полосу

В терминале, пока мод рисует в полосе, пользователь может свернуть полосу до одной строки, чтобы она не мешала:

• Щелкнуть [-]: пока полоса развернута, Claude Code рисует эту отметку у правого края ее первой строки. В полноэкранном рендеринге пользователь щелкает по ней, чтобы свернуть полосу.
• Нажать Ctrl+X, затем Ctrl+A: это работает независимо от того, где находится фокус клавиатуры — в промпте, в полосе или в панели. Пользователь может привязать к этому другие клавиши через действие abovePrompt:toggle.

Свернутая полоса скрывает все, что моды рисуют в ней, и вместо этого показывает одну тусклую строку, в которой названы клавиши для ее разворачивания в соответствии с привязками пользователя:

▸ plugin panel hidden · ctrl+x ctrl+a or click to show

Те же клавиши, а в полноэкранном рендеринге — щелчок по этой строке, снова разворачивают полосу. До этого ничто не нажимает кнопки в ней: ни горячая клавиша, ни цифра, введенная в пустой промпт, ни сочетание клавиш для action кнопки. Если полоса имеет фокус клавиатуры в момент, когда пользователь ее сворачивает, фокус возвращается в промпт, а Ctrl+X, затем Tab пропускает полосу, пока она свернута.

Полоса остается свернутой, пока пользователь ее не развернет, даже после /clear, и снова разворачивается при следующем запуске Claude Code. Ваш мод не может развернуть ее или узнать, что она свернута: хук ui.render продолжает выполняться, и ничто в e.props об этом не сообщает. Не делайте полосу единственным местом, где ваш мод показывает то, на что пользователь должен ответить.

Получение введенного текста и рисование строки для каждого элемента

Многие панели — это текстовое поле со списком под ним. Пример в этом разделе — панель заметок: вы вводите заметку и нажимаете Enter, чтобы добавить ее, и каждая заметка имеет кнопку x, которая удаляет ее. С двумя добавленными заметками терминал рисует панель таким образом:

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

✕ на верхней границе — это собственная отметка Claude Code для закрытия панели.

Пример использует следующие техники:

• Получение введенного текста: Input вызывает onSubmit(value) с текстом поля, когда пользователь нажимает Enter, и onInput(value) при каждом изменении
• Рисование списка: отобразите ваши данные в одну строку каждый, и дайте каждой кнопке строки свой собственный 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',
        // The text the field starts with
        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] }),
          ],
        }),
      ),
    ],
  })
})

Чтобы попробовать панель:

• Добавить заметку: введите строку и нажмите Enter. Строка появляется как новая строка, и поле очищается.
• Удалить заметку: нажимайте Tab, пока кнопка x заметки не получит фокус, затем нажмите Enter. x — это метка кнопки, а не горячая клавиша, поэтому ввод буквы не нажимает ее.

Каждое изменение следует тому же циклу рендеринга, что и hello-tabs: обратный вызов изменяет notes, вызывает redraw и сохраняет список в $.store. Если ваш хук снова рисует панель, пока пользователь вводит заметку, поле сохраняет его текст, пока хук каждый раз передает одно и то же value. Чтобы заменить его текст своим, передайте другое value.

Пример сохраняет заметки и не загружает их. Чтобы вернуть их в следующей сессии, прочитайте их в хуке session.start, как hello-tabs читает count.

Следующие свойства составляют строку поля, Note: Type a note and press Enter ⏎ add:

Отправка Input не запускает ход, если ваш обратный вызов не вызывает $.prompt.submit.

Перерисовка сайта

Рисование — это снимок: оно показывает то, что ваш хук ui.render вернул в последний раз, когда хук запустился. Чтобы показать что-то новое, хук должен запуститься снова. Claude Code запускает его снова для некоторых изменений, и ваш мод просит остальное.

Когда Claude Code перерисовывает без запроса

Claude Code запускает ваш хук ui.render снова, когда пропсы сайта изменяются или ширина терминала изменяется. Когда Client в сайте завершается сбоем и ваш мод обрабатывает ui.fault, Claude Code запускает хук ещё раз после того, как ваши хуки ui.fault вернут результат, чтобы ваш хук ui.render мог исключить этот Client. Он не запускает хук на таймере и не может сказать, когда переменная в вашем модуле изменяется.

Перерисовка при изменении ваших данных

Чтобы ваши сайты были нарисованы снова после изменения ваших собственных данных, вызовите $.ui.invalidate('ui.render'). Эта панель считает нажатия. Обратный вызов кнопки изменяет count, затем просит перерисовку:

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] }),
    ],
  })
})

Каждое нажатие поднимает число в панели. Пример hello-tabs оборачивает тот же вызов в свою функцию redraw.

Значение, которое вы сохраняете в $.state, не нуждается в вызове, потому что написание значения перерисовывает сайты, которые его читают.

Перерисовка на таймере

Чтобы сохранить часы, обратный отсчет или значение извне сессии в актуальном состоянии, перерисовывайте по расписанию. Запустите таймер в хуке session.start модуля. Если модуль уже имеет один, как hello-tabs, добавьте строку $.clock.every к нему:

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)
})

Claude Code теперь запускает ваш хук ui.render один раз в секунду. Таймер останавливается при перезагрузке модуля, и новая копия модуля запускает свой собственный.

Как часто сайт может перерисовываться

Claude Code ограничивает частоту перерисовок сайта, поэтому ваш мод может вызывать $.ui.invalidate так часто, как изменяются его данные. О том, как часто может перерисовываться каждый сайт, см. таблицу лимитов.

Вызовы, которые приходят быстрее, чем лимит, объединяются в одну перерисовку. Эта перерисовка запускает ваш хук один раз, и хук читает ваши данные такими, какие они есть в этот момент, поэтому показывается последнее значение и значения между ними не показываются. Анимация не может работать быстрее, чем лимит.

Сохранение состояния

От того, где мод хранит значение, зависит, как долго оно существует: пока модуль не перезагрузится, пока сессия не закончится или от одной сессии к другой. Выбирайте по тому, как долго значение должно существовать:

$.store.get(key) разрешается в значение или undefined, а $.store.set(key, value) принимает любое значение JSON.

Сохранение значения в $.state

$.state хранит значения на протяжении сессии и выполняет перерисовку за вас. Это реактивное состояние: хук ui.render, который читает значение, подписывается на него, поэтому Claude Code перерисовывает это место каждый раз, когда вы записываете значение, и вам не нужно вызывать $.ui.invalidate. Значение в $.state также переживает перезагрузку модуля, чего переменная не делает.

Чтобы настроить его, объявите ваши значения, укажите в манифесте путь к объявлению, затем определите и используйте каждое значение. Примеры перемещают count из hello-tabs в $.state.

Объявление значений

Объявите значения в файле объявления типов. Внешний ключ — это имя вашего плагина, а каждая запись под ним — это значение и его тип. Сохраните это как hello-tabs/types/index.d.ts:

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

Указание манифеста на объявление

Чтобы claude plugin validate мог проверить ваш код по этому файлу, добавьте в манифест поле types с его путем:

{
  "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"
}

Определение, чтение и запись значения

В вашем модуле определите каждое значение со значением по умолчанию, прочитайте его при отрисовке и запишите его из обратного вызова. atom задает имя значения и его значение по умолчанию, read возвращает его, а update записывает его. Эти три помощника вызывают $.state.get и $.state.set за вас:

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)

Поскольку хук ui.render прочитал count, Claude Code запускает хук снова каждый раз, когда кнопка записывает его.

К коду применяются следующие правила:

• Пишите plugin и key как строковые литералы: claude plugin validate читает их из вашего исходного кода
• Храните результат каждого вызова atom в const: если вы объявите count с помощью let, валидация завершится ошибкой takes a source the scan can read
• Объявите каждое значение в файле объявления типов: в противном случае валидация завершится ошибкой hello-tabs.count is not declared
• Записывайте из обратного вызова или хука другого события: хук ui.render может читать состояние, но не может записывать его, поэтому записывайте из onPress, onSubmit или хука для другого события

Изменение hello-tabs для использования $.state

Чтобы переместить count в hello-tabs в $.state, измените каждую строку, которая его использует:

• В верхней части модуля: добавьте строку import и замените let count = 0 на строку atom
• В хуке ui.render: добавьте строку read перед tabButton и отрисуйте 'Count: ' + n в Text
• В кнопке Add one: замените onPress на вариант из раздела Сохранение из более чем одной сессии, который сохраняет счетчик, а также записывает его
• В хуке session.start: замените две строки, которые читают saved, на вызов loadCount из раздела Повторная загрузка сохраненного значения после /clear

Оставьте redraw для кнопок вкладок, потому что tab по-прежнему является переменной.

Повторная загрузка сохраненного значения после /clear

Если ваш мод копирует сохраненное значение из $.store в $.state при session.start, он должен скопировать его снова после /clear, /resume или /branch. Эти команды сбрасывают каждое значение $.state к значению по умолчанию, а session.start повторно не срабатывает. classic.SessionStart же срабатывает после каждой из них, с e.source, установленным в clear, resume или fork, поэтому скопируйте значение снова в хуке на это событие. В противном случае ваша отрисовка покажет значение по умолчанию, а обратный вызов, который сохраняет значение $.state, запишет значение по умолчанию поверх того, что вы сохранили.

Этот код загружает count из обоих хуков. Он основан на версии hello-tabs с $.state, где count — это атом, а update импортирован. Поместите loadCount выше register и добавьте вызов loadCount в уже имеющийся у вас хук session.start. classic.SessionStart также срабатывает при запуске и после сжатия контекста, которое не сбрасывает $.state, поэтому фильтр по source ограничивает хук тремя сбросами:

// 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)
})

С обоими хуками панель показывает после /clear сохраненный счетчик, а не 0, и следующее нажатие Add one прибавляет к сохраненному счетчику.

loadCount записывает сохраненное значение поверх того, что находится в $.state, а session.start срабатывает снова каждый раз, когда модуль перезагружается. Чтобы хранилище не отставало, сохраняйте при каждом изменении, как это делает кнопка Add one.

Чтобы проверить перезагрузку без сессии, протестируйте отрисовку после /clear.

Сохранение из более чем одной сессии

Все сессии на вашем компьютере, которые запускают ваш мод, используют одно общее $.store. get, за которым следует set, не является атомарной операцией. Когда две сессии каждая читают значение, изменяют его и записывают обратно, возникает гонка, и вторая запись заменяет первую.

Чтобы сделать это менее вероятным:

• Дайте каждому элементу собственный ключ: set изменяет только свой ключ, поэтому сессии, которые записывают разные ключи, не перезаписывают друг друга
• Читайте повторно прямо перед записью: для значения, которое изменяют несколько сессий, выполните get для ключа в обратном вызове и сформируйте новое значение на его основе, а не на основе копии, загруженной при session.start. Запись другой сессии все равно будет потеряна, если она произойдет между вашими get и set.

Эта кнопка прибавляет единицу к тому, что сейчас содержится в хранилище, затем обновляет отрисовку:

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)
}

Если вторая сессия нажала свою кнопку три раза с момента запуска этой сессии, это нажатие покажет и сохранит счетчик, который включает эти три нажатия.

Следующие шаги

• Реагирование на события: питайте ваше рисование из вызовов инструментов и ходов
• Использование API модов: питайте ваше рисование из таймеров и вызовов модели
• Тестирование рисования: нажимайте ваши кнопки из теста, на более чем одной поверхности
• Сайты рендеринга и элементы: свойства каждого сайта и свойства каждого элемента