SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 20:57 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 22:00

Справочник по модам

Полный справочник по модам Claude Code: структура модуля хуков, события, методы API модов, точки отрисовки, элементы по интерфейсам, ограничения и настройки.

Здесь можно найти любое событие, которое может обрабатывать мод, любой метод API модов, который он может вызвать, и любую точку отрисовки, в которой он может рисовать, для CLI Claude Code и приложения Desktop по состоянию на v2.1.287. Для каждой записи указаны имя и однострочное описание, а также ссылка на раздел руководства с пояснениями, если такой раздел есть.

Файлы

Мод — это каталог плагина со следующими файлами:

Файл Обязателен Содержимое
.claude-plugin/plugin.json Да Манифест плагина. Моды не добавляют обязательных полей.
hooks/hooks.json Да modules: массив с одним путём к модулю хуков относительно этого файла, например "modules": ["./register.js"]. Может также содержать хуки настроек в поле hooks.
Модуль хуков, например hooks/register.js Да Точка входа мода. Экспортирует register(on, options). Имеет расширение .js, .mjs, .cjs, .jsx, .ts, .mts, .cts или .tsx. Является ES-модулем.
types/index.d.ts, указанный в поле types манифеста Когда мод использует $.state или добавляет пространство имён в API модов Объявляет значения PluginState и любое пространство имён, которое добавляет мод
Файлы, имена которых заканчиваются на .test.ts или .test.tsx Нет Тесты, которые запускает claude plugin test

register получает on и options. options содержит значения полей userConfig, объявленных в манифесте, с подставленными значениями по умолчанию.

Функция хука

Мод регистрирует каждый из своих хуков, то есть обработчиков событий, вызывая on внутри register. on принимает имя события, необязательный matcher, то есть фильтр по полям события, и сам хук, например on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on возвращает регистрацию с одним методом, .catch(handler), который задаёт обработчик ошибок хука.

Аргумент Что это
$ API модов: все методы из раздела Методы API модов. Записывайте каждый вызов полностью, пространство имён и затем метод, например $.fs.read('notes.md').
e Входные данные события в виде глубоко замороженных простых данных. Чтобы изменить их, передайте копию в next.
next(e) Следующий обработчик, как в middleware. Запускает хуки, идущие после этого, а затем поведение Claude Code. Разрешается в результат события.
next.signal AbortSignal, который прерывается, когда событие отменено
next.origin { plugin, tier } того, кто инициировал событие. Сам Claude Code — это { plugin: 'engine', tier: 'core' }. tier мода — это его группа приоритета в порядке запуска модов: prepend, user, append или builtin.
next.budget Ограничение времени хука в миллисекундах: next.budget.ms — всё ограничение, а next.budget.remainingMs — оставшееся на данный момент время
next.to(e, tier) Переходит к более позднему уровню: append, builtin или core. next.to(e, 'append') пропускает моды, установленные пользователем. Вызвать его может только мод из prependPlugins или appendPlugins.
next.error, next.called Только в обработчике .catch. next.error.kind — это throw или timeout, next.error.message — текст ошибки, а next.called равно true, если упавший хук вызвал next.

События

События сгруппированы по тому, к чему они относятся; для каждого указано, когда оно срабатывает и что может вернуть хук на него. Хуки на turn.step и process.spawn — асинхронные генераторы, остальные хуки — асинхронные функции.

В последнем столбце каждой таблицы используется сокращённая запись. next(e) передаёт событие дальше без изменений. next({ ...e, text }) передаёт дальше копию с изменённым указанным полем, например next({ ...e, text: e.text.trim() }). Объект отвечает на событие без вызова next, а слово вроде reason обозначает строку, которую вы пишете, например { deny: 'Use the file tools.' }.

Инструменты

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

Событие Срабатывает, когда Хук может вернуть
tool.call Инструмент вот-вот запустится next(e), { deny: reason } или { result }
tool.check Claude Code решает, может ли вызов инструмента выполниться, после хуков tool.call и PreToolUse. next(e) разрешается в решение, к которому пришли правила, режим разрешений и эти хуки. { decision }, то есть allow, ask или deny
tool.describe Один раз для каждого инструмента, когда его описание впервые отправляется Claude { description }

Промпты и то, что читает Claude

События промптов охватывают текст, который вводит пользователь, и текст, который Claude Code отправляет Claude сам, например системный промпт и напоминания:

Событие Срабатывает, когда Хук может вернуть
prompt.submit Промпт отправлен next({ ...e, text }), next({ ...e, context }) или { drop: reason }
prompt.fill, prompt.suggest Текст вот-вот попадёт в поле промпта как черновик или как приглушённая подсказка next(e) с изменённым текстом
prompt.edit Пользователь редактирует поле промпта next(e)
prompt.compose Claude Code формирует системный промпт { sections } — список { id, text, scope } в порядке отправки
prompt.section Один раз для каждого именованного раздела системного промпта. e.name — это id раздела в prompt.compose. { text } или { text: null }, чтобы пропустить раздел
prompt.context Один раз для каждого диалога, для контекста, отправляемого с первым сообщением { blocks }
prompt.attachment Claude Code добавляет собственное сообщение для Claude, например напоминание. e.type указывает вид, а для видов, объявленных в типах, e.detail содержит факты, на основе которых написан текст. { text } или { text: null }, чтобы пропустить его
skill.prompt Текст скилла раскрывается для Claude { text }
attribution.text Claude Code составляет текст атрибуции для коммита или pull request { text }

Команды и конфигурация

События команд и конфигурации срабатывают, когда команда запускается или попадает в список, а также когда строка /config показывается или изменяется:

Событие Срабатывает, когда Хук может вернуть
command.run Команда вот-вот запустится { text }, {} или next(e)
command.describe Один раз для каждой команды, для списка команд { description, argumentHint, isHidden }
config.set Строка /config вот-вот изменится next({ ...e, value }) или { deny: reason }
config.describe Один раз для каждой строки /config { label, description, isHidden }

Ходы

События ходов отслеживают один ответ от начала до конца, включая каждый запрос к модели в его рамках:

Событие Срабатывает, когда Хук может вернуть
turn.start Начинается ход next(e)
turn.step Один запрос вот-вот отправится модели yield* next(e) или next({ ...e, model }), next({ ...e, effort })
turn.complete Ход завершился next(e) или { text }, чтобы показать строку под ответом

Сессия

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

Событие Срабатывает, когда Хук может вернуть
session.start Один раз для каждого загруженного мода, перед первым промптом, и снова после перезагрузки этого мода. Не срабатывает после /clear, /resume или /branch. next(e)
session.end Сессия завершается или выполняется /clear, /resume либо /branch. e.reason — это clear, resume, logout, prompt_input_exit или other. /branch сообщает resume. next(e)
session.compact Диалог вот-вот будет сжат { skip: reason }
session.receive, session.send Сообщение приходит от другого агента или сессии либо вот-вот будет отправлено им. См. Отправка и получение сообщений между сессиями. { consumed: reason } для receive, { isDelivered: false, reason } для send
session.append Один раз для каждой строки, которую сохраняет диалог, например промпта, блока ответа, результата инструмента или уведомления, перед её сохранением next({ ...e, message }), чтобы переписать content строки
session.attach, session.detach Другое приложение подключается к сессии или отключается от неё next(e)
session.measure После каждого хода, а также когда меняется процент использования лимита тарифа next(e)

Субагенты

События субагентов срабатывают, когда тип субагента предлагается Claude и когда субагент вот-вот запустится:

Событие Срабатывает, когда Хук может вернуть
agent.offer Тип субагента предлагается Claude { isOffered: false }, чтобы скрыть его
agent.spawn Субагент вот-вот запустится { model } или { deny: reason }

Интерфейс

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

Событие Срабатывает, когда
ui.render Точка отрисовки вот-вот будет нарисована
ui.resolve Загружаются моды, один раз для каждого приложения, точки отрисовки и мода. Результат — таблица элементов, которую читает $.ui.resolve(e).
ui.press, ui.input, ui.select Используется Button, Input или Select, нарисованный модом
ui.focus, ui.scroll Вот-вот изменится элемент управления в фокусе или позиция прокрутки панели или полосы
ui.close Панель вот-вот закроется. e.id — это панель, а e.origin.kind — plugin, person или unload.
ui.message Элемент Client отправляет данные своему моду

Другие моды

Эти события позволяют моду воздействовать на другие моды при их загрузке: отклонить мод или изменить получаемый им API модов:

Событие Срабатывает, когда Хук может вернуть
plugin.register Модуль хуков вот-вот загрузится. e.uses перечисляет его события, вызовы API модов, переменные окружения и состояние в том виде, в каком их выводит claude plugin validate. Каждый вызов записан без префикса $., например fs.read. { refuse: reason }
engine.create Для этого мода строится API модов Изменённый API модов, чтобы добавить пространство имён или скрыть его

Телеметрия

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

Событие Срабатывает, когда Хук может вернуть
telemetry.log, telemetry.mark Запись телеметрии вот-вот будет записана в лог или отмечено одно использование функции. В устанавливаемом моде задайте хуку телеметрии фильтр { to: 'collector' }, например on('telemetry.log', { to: 'collector' }, hook). Без фильтра мод не проходит claude plugin validate. * не соответствует этим событиям. next(e) или { deny: reason }

События хуков настроек

Каждое событие хука настроек — это событие с именем classic.<Event>, например classic.Stop или classic.PostToolUse. e — это JSON, который хук получает через stdin.

Вызовы API модов

Каждый метод API модов также является событием, названным по его пространству имён и методу, например fs.read, model.complete или ui.open. Хук на такое событие перехватывает вызовы от модов, которые выполняются после него, и может вернуть next(e), { deny: reason } или { value }.

Методы API модов

API модов — это аргумент $, который получает каждый хук. Его методы сгруппированы по пространствам имён, например $.ui. В этой таблице методы каждого пространства имён перечислены по имени, поэтому open в строке $.ui — это вызов $.ui.open(...). В руководствах показано использование распространённых методов, а в типах для вашей сборки каждый метод документирован с примером.

Пространство имён Методы
$.plugin name, root: имя и каталог этого плагина
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude читает текст из submit({ text }) после предложения, называющего ваш мод отправителем. submit({ text, asUser: true }) отправляет текст как собственные слова пользователя, без этого предложения.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() возвращает { startedAt, context, rateLimits, cost }: context содержит tokens, window и percent, а rateLimits — это список { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write не атомарен: он заменяет содержимое файла на месте, поэтому другой процесс может прочитать частично записанный файл. Храните данные, которые изменяют несколько сессий, в $.store.
$.store get, set, delete, keys. Хранилище «ключ–значение», общее для всех сессий на машине. См. Сохранение из нескольких сессий.
$.state Реактивное состояние: get, set, со вспомогательными функциями atom, read, update, derive и memberOf, импортируемыми из claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) подключает MCP-сервер, указанный в манифесте вашего собственного плагина.
$.audio play, speak
$.telemetry log, mark. Запись отправляется, только если вызов делает Claude Code или встроенный мод.

Точки отрисовки

Точка отрисовки — это точка расширения в интерфейсе Claude Code. Каждая строка — это значение e.component в хуке ui.render с полями e.props и приложениями, которые её отрисовывают. e.surface — это terminal или desktop. В разделе Изменение того, что уже рисует Claude Code показано, что хук может делать в точке отрисовки, с примером для каждого варианта.

Точка e.props e.requestId Отрисовывается в
Pane title, isFocused, bodyColumns, placement, scroll, view id панели Terminal, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Один экземпляр Terminal, Desktop
UserMessage text, origin, isExpanded и task или from в зависимости от источника id сообщения Terminal, Desktop
AssistantMessage Текст ответа id сообщения Terminal, Desktop
ToolUse, ToolResult, ToolGroup Имя, входные данные и результат инструмента id вызова инструмента Terminal, Desktop
CommandOutput command, text id сообщения Terminal, Desktop
AskUserQuestion Вопрос и варианты id вызова инструмента Terminal, Desktop
ToolProgress kind id вызова инструмента Terminal
Spinner word, message, suffix, mode id агента Terminal, Desktop
TurnDuration word, durationMs id сообщения Terminal
InfoNotice text, command id сообщения Terminal
SessionMode modes Один экземпляр Terminal, Desktop
PromptHint isDraft, isWorking, hint Один экземпляр Terminal, Desktop

e.viewport содержит columns, rows и isFullscreen. Он отсутствует, пока приложение не измерило своё окно. Его rows — это высота всего окна, а не вашей панели.

Чтобы подогнать дерево под точку отрисовки, читайте в хуке следующие пропсы:

  • Ширина Pane или полосы: рисуйте по e.props.bodyColumns
  • Высота Pane рядом с транскриптом: когда e.props.placement равно 'dock', e.props.scroll.bodyRows — это число строк панели
  • Высота Pane над промптом: когда e.props.placement равно 'inline', панель растёт вместе с вашим деревом до предела, а bodyRows учитывает только строки, показанные сейчас. Поле rows в $.ui.open запрашивает другой предел.

Дерево, которое выше панели, прокручивается целиком.

Элементы

Элементы — это строительные блоки дерева, которое возвращает хук ui.render, и вы получаете их из $.ui.resolve(e). В разделе Построение дерева из элементов показаны распространённые элементы и то, как их рисует терминал, а в галерее интерфейса есть снимки экрана большинства из них. Галочка означает, что приложение умеет рисовать элемент.

Элемент Основные пропсы Terminal Desktop
Box key, flex-раскладка, gap, padding, margin, width, height, borderStyle, backgroundColor, position, hover ✓ ✓
Text color, backgroundColor, bold, italic, underline, dimColor, inverse, wrap ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action ✓ ✓
Link href, label ✓ ✓
Code Код, до 10 000 символов ✓ ✓
Markdown text до 10 000 символов, key, dimColor, onLinkPress, pressableLinks ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓
Svg SVG-документ, до 131 072 символов ✓
Client module, key ✓ ✓
Raster key, columns до 512, rows до 256, cells. См. Рисование сетки цветных ячеек. ✓
Image Байты PNG или RGBA до 2 МиБ либо путь к файлу ✓

Дополнительные правила для Button: action указывает одно из собственных действий сочетаний клавиш Claude Code, и сочетание, назначенное пользователем для этого действия, нажимает кнопку, если это аккорд или клавиша с модификатором. Цифровой hotkey на кнопке в полосе также срабатывает, когда пользователь вводит только эту цифру в пустой промпт и делает паузу. Если две кнопки в одной отрисовке указывают один и тот же hotkey, он достаётся более поздней. autoFocus на любом элементе управления принимает только true, поэтому, чтобы отключить его, опустите этот проп.

Ограничения

Хуки и вызовы API модов выполняются с ограничениями по времени и размеру. Claude Code пропускает хук, превысивший ограничение по времени, и отклоняет вызов, превысивший ограничение по размеру.

Ограничение Значение
Собственное время выполнения хука для одного события, без учёта времени внутри next или вызова API модов, кроме $.clock.sleep 10 секунд
Время выполнения обработчика .catch 1 секунда
Все хуки session.end вместе 1,5 секунды
Таймаут $.process.run 30 секунд по умолчанию, не более 10 минут
maxTokens для $.model.complete 1024 по умолчанию, до 64 000 или предела вывода модели
$.fs.read и $.fs.write 4 МиБ на один файл
Один строковый дочерний элемент Text 10 000 символов
$.store 4 МиБ JSON в сумме
$.session.messages() Последние 4 096 записей
Перерисовки $.ui.invalidate('ui.render') Ограничены 10 в секунду или 30 в терминале для видимой панели, развёрнутой полосы и строки подсказки под промптом. Более частые вызовы объединяются.
$.ui.toast Показывается 4 секунды, если не передать { timeoutMs }
Панель, открытая без запроса пользователя Размещается начиная со 144 столбцов терминала, со 110 — после того как пользователь однажды её открыл
Имена команд, инструментов, типов субагентов и панелей Буквы, цифры, _ и -, до 64 символов
Один тест claude plugin test 5 секунд, если тест не задаёт timeoutMs

Настройки и переменные окружения

Ниже перечислены настройки и переменные окружения, влияющие на моды. В столбце «Где» указано, из какого файла настроек или окружения читается каждая из них:

Имя Где Что делает
CLAUDE_CODE_PLUGIN_DIRS Окружение или env в ~/.claude/settings.json Каталоги плагинов для загрузки так же, как это делает --plugin-dir, — для приложений, которым нельзя передать флаг. Абсолютные пути, разделённые :, или ; в Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Окружение 1 заставляет долго работающую неинтерактивную сессию перезагружать моды из --plugin-dir при сохранении
prependPlugins, appendPlugins Управляемые настройки. Пользовательские настройки — только на машине без управляемых настроек и для пользователя, не вошедшего с тарифом Team или Enterprise. Списки id плагинов, например acme-guard@acme-tools. Моды из prependPlugins выполняются перед каждым модом, установленным пользователем, а моды из appendPlugins — после, в указанном порядке. См. Порядок запуска модов.
allowManagedModsOnly Управляемые настройки, как опция встроенного стража Загружаются только моды, которые считаются модами вашей организации, и моды, встроенные в Claude Code. Хуки настроек пользователей продолжают работать.
allowModsToOverrideDenyRules Управляемые настройки, как опция встроенного стража Позволяет моду, установленному пользователем, одобрить вызов инструмента, который отклоняет правило deny
allowManagedHooksOnly Управляемые настройки Блокирует хуки и установленные моды, не принадлежащие вашей организации. См. что продолжает работать.
disableAllHooks Любой файл настроек В управляемых настройках не выполняется ни один мод или хук из установленного плагина. В ваших собственных настройках то, чем управляет ваша организация, продолжает работать. См. disableAllHooks.
disableSideloadFlags Управляемые настройки Отклоняет --plugin-dir и --plugin-url при запуске
pluginConfigs Пользовательские или управляемые настройки Содержит значения userConfig для мода с ключом по id плагина, например acme-guard@acme-tools, или по его имени и @inline, например first-mod@inline, для мода, загруженного с --plugin-dir

sec-default@builtin — это страж, встроенный в Claude Code, который отображается как cc-plugin-sec-default в /plugin и в отладочном логе. Он загружается перед каждым модом, установленным человеком, на машине с управляемыми настройками или для пользователя, вошедшего с тарифом Team или Enterprise. Если задан управляемый prependPlugins, страж загружается, только если этот список его называет, на указанной позиции. Его исходный код находится в каталоге mods/sec-default репозитория Claude Code.

Команды

Эти команды и флаги загружают, проверяют и тестируют мод. Команды claude выполняются в вашей оболочке, а команды / — в промпте Claude Code. В таблице <directory> обозначает путь, который вы вводите, например claude plugin validate ./first-mod. Квадратные скобки обозначают необязательный аргумент.

Команда Что делает
/plugin Показывает под своими вкладками строку вида 1 mod active · first-mod, когда загружен мод, не являющийся встроенным
claude plugin validate <directory> Читает манифест и модуль хуков плагина и сообщает об ошибках, обрабатываемых событиях и вызовах API модов. --strict считает предупреждения ошибками, а --json выводит машиночитаемый отчёт.
claude plugin test [directory] Запускает все файлы в каталоге (или в текущем каталоге, если он не указан), имена которых заканчиваются на .test.ts или .test.tsx. Завершается с кодом 1, если тест не проходит.
claude --plugin-dir <directory> Загружает каталог плагина на одну сессию и перезагружает его модуль хуков при сохранении. Повторите флаг, чтобы загрузить несколько.
/reload-plugins Перезагружает плагины при запуске