Существующие hooks Claude Code также работают на событиях в виде команды оболочки, HTTP-запроса или подсказки, которые вы настраиваете в файле параметров. Обработчики мода — это функции, которые работают внутри Claude Code. Claude Code вызывает оба типа hooks: на этих страницах «hook» означает обработчик мода, а тип из файла параметров — это «settings hook».
Что может делать мод
Settings hooks, skills, строки состояния и серверы MCP работают вне Claude Code: каждый из них запускает скрипт или предоставляет Claude текст или инструменты. Мод работает внутри Claude Code, поэтому он может делать то, что они не могут:- Нарисовать интерфейс, который вы можете использовать: панель рядом с транскриптом или полоса над подсказкой с вкладками, кнопками и текстовыми полями. См. Рисование в интерфейсе.
- Перерисовать собственный интерфейс Claude Code: заменить или переоформить части, которые рисует сам Claude Code, такие как строка вызова инструмента, спиннер или диалог, в котором Claude задает вопросы. См. Изменение того, что уже рисует Claude Code.
- Вмешаться в вызов инструмента или запрос: например, удержать вызов инструмента, пока вы задаете пользователю вопрос, ответить без запуска инструмента или отправить один запрос другой модели. См. Охрана или изменение вызова инструмента и Следование за ходом.
- Запустить собственный код на команде:
/command, который запускает вашу функцию сразу же, без хода Claude, даже если Claude работает. См. Добавление команды или инструмента. - Обмен данными между hooks: hooks мода совместно используют переменные в его файле, поэтому то, что записывает один hook, может показать другой. Например, один hook может считать вызовы инструментов, а другой показывает счетчик рядом со спиннером, или один может читать использование токенов каждого запроса, а другой отображает его на графике в панели. См. Реакция на события.
claude -p и облачных сессиях. Если хук настроек, скилл или MCP-сервер уже делает то, что вам нужно, сравните их перед написанием мода. Для управления модами для организации см. Управление модами для вашей организации.
Получение мода
Чтобы начать работу с модом:- Используйте уже имеющийся: некоторые собственные функции Claude Code являются модами, например
/diff. См. Моды, встроенные в Claude Code. - Создайте свой: опишите, что вам нужно, в сессии Claude Code, и Claude напишет мод. См. Попросите Claude создать мод. Чтобы узнать, как устроен код мода, напишите его самостоятельно.
- Установите готовый: см. Установка или обновление мода или попробуйте пример мода
Установка или обновление мода
Мод устанавливается как плагин из маркетплейса. Укажите имя плагина,@ и имя маркетплейса. Эти примеры устанавливают плагин с именем token-chart из маркетплейса с именем your-org:
- В сессии Claude Code выполните
/plugin install token-chart@your-org. - В оболочке выполните
claude plugin install token-chart@your-org.
/reload-plugins в этой сессии, чтобы загрузить его. В противном случае он загрузится при следующем запуске Claude Code.
Попробуйте пример мода
Anthropic публикует примеры модов в каталогеclaude-code/mods репозитория claude-code-playground. Каждый из них — это полноценный плагин, а в его README описано, как он был создан. Репозиторий предоставляет их как есть, без поддержки.
token-weather: отображает прогноз вашего контекстного окна над промптомblast-radius: перехватывает рискованную shell-команду, напримерrm -rfили принудительный push, до её выполнения и показывает, что она изменит, с кнопками для продолжения или отменыreplay-theater: добавляет команду/replay, которая пошагово показывает правки файлов, внесённые Claude за последний ход
--plugin-dir. Чтобы убедиться, что мод загрузился, проверьте, какие моды загрузила сессия.
Чтобы сохранить мод, добавьте каталог claude-code/mods вашего клона в качестве маркетплейса, а затем установите мод из claude-code-playground-mods. Маркетплейс указывает на ваш клон, поэтому мод перестанет загружаться, если вы переместите или удалите клон.
Решите, доверять ли моду
Мод — это код, который работает с вашими разрешениями внутри Claude Code. Устанавливайте моды только от авторов и маркетплейсов, которым вы доверяете.Что может достичь мод
Мод работает с вашими разрешениями, поэтому перед установкой знайте, к чему у него есть доступ. После загрузки мод может:- Действовать на вашей машине от вашего имени: читать и писать файлы в любом месте, где может ваша учетная запись пользователя, запускать программы и делать сетевые запросы
- Читать ваши секреты: переменные окружения и файлы настроек, включая API-ключ, который вы храните в любом из них
- Видеть вашу сессию: каждый промпт, который вы отправляете, и каждый вызов инструмента, который делает Claude
- Изменять вашу сессию: переписывать промпт или вызов инструмента, отправлять промпт так, как если бы вы его набрали, или отправлять сообщение в другую из ваших сессий
- Действовать без вашего разрешения: одобрить вызов инструмента перед тем, как вас спросят
- Потратить вашу квоту: вызвать модель в рамках вашего плана или с вашим API-ключом
deny или ask или ваши хуки PreToolUse, если этому не препятствует встроенный страж. Когда встроенный страж загружен, по умолчанию пользовательский мод не может этого сделать. В локальной сессии терминала наличие cc-plugin-sec-default на вкладке Installed в /plugin означает, что страж загружен.
Мод может переоформить большую часть интерфейса Claude Code, но не запрос разрешения. Он не может изменить то, что вам показывает запрос.
Перечислите, что делает мод перед установкой
Перед установкой мода вы можете перечислить, какие события он обрабатывает и что он просит Claude Code делать, например читать файл или делать сетевой запрос, без его запуска. Сначала получите файлы плагина, например клонировав его репозиторий. Затем в вашей оболочке запуститеclaude plugin validate в каталоге плагина:
hooks: и calls: в выводе перечисляют события, которые обрабатывает мод, и что он просит Claude Code делать. Просмотр того, что может делать мод показывает вывод и какие вызовы искать.
Включение или отключение модов
Моды включены по умолчанию. В терминале используйте Claude Code v2.1.287 или позже. Приложение Desktop включает собственную копию Claude Code, и моды работают в нём начиная с v2.1.286. Проверьте версию там, где вы используете моды:- Терминал: в вашей оболочке запустите
claude --version. Если ваша версия старше, обновите Claude Code. - Приложение Desktop: в локальной сессии на вкладке Code введите
/statusи посмотрите строку Claude Code, в которой показана версия, например2.1.286. Если ваша версия старше, обновите приложение Desktop.
- Один мод: отключите или удалите его плагин со вкладки Installed в
/plugin - Каждый установленный мод, для одной сессии: запустите Claude Code с
--safe-mode, что также отключает ваши другие настройки - Каждый мод, который вы установили, в каждой сессии: задайте
"disableAllHooks": trueв~/.claude/settings.json. Ваши хуки из настроек и пользовательская строка состояния также остановятся. То, чем управляет ваша организация, продолжает работать.
disableAllHooks и параметр вашей организации allowManagedModsOnly останавливают мод, но оставляют остальную часть его плагина на месте: плагин остаётся установленным, а его скиллы, команды, агенты и MCP-серверы загружаются. Другие настройки и флаги действуют шире. В разделах disableAllHooks и Что работает при allowManagedHooksOnly перечислено, как каждый из них влияет на плагин и его хуки из настроек.
Чтобы узнать, могут ли моды загружаться для вас, см. Проверка, могут ли загружаться моды.
Если вы задали
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS во время раннего доступа, удалите эту переменную. Claude Code v2.1.287 и позже игнорирует её, поэтому значение 0 не отключает моды.Посмотрите, какие моды загрузила сессия
Чтобы увидеть, какие моды загрузила сессия терминала, запустите/plugin в промпте Claude Code. Тусклая строка под вкладками показывает количество и имена, например 1 mod active · first-mod. Если мод, который вы установили, не указан там, см. Узнайте, почему мод ничего не делает.
Как работает мод
Мод — это плагин, чей код регистрирует обработчики событий, называемые хуками. Claude Code запускает хук при возникновении его события, например когда Claude вызывает инструмент или когда рисуется спиннер. Небольшой мод состоит из трех файлов:plugin.json: манифест плагинаhooks.json: указывает на ваш файл кодаregister.js: ваш код, называемый модулем хуков. Он сообщает Claude Code, на каких событиях запускать ваши функции.
register.js. Он подсчитывает вызовы инструментов, которые делает Claude, и показывает счётчик рядом со спиннером, пока Claude работает, например Thinking · tool calls: 3….
hooks/register.js
calls в верхней части:
- Хук
tool.callзапускается каждый раз, когда Claude собирается использовать инструмент. Он добавляет единицу кcalls, просит Claude Code перерисовать интерфейс и позволяет инструменту работать как обычно. - Хук
ui.renderзапускается каждый раз, когда Claude Code рисует спиннер. Он сохраняет собственный спиннер Claude Code и добавляет счетчик после слова.
Thinking · tool calls: 1…, затем 2…, затем 3….
Что хук может делать с событием
Claude Code запускает ваш хук перед тем, как отреагировать на событие, поэтому хук решает, что произойдет дальше. Он может:- Наблюдать: отметить, что происходит, и позволить событию продолжиться без изменений, как делает хук
tool.callв примере - Переписать: изменить событие перед его продолжением, как делает хук
ui.render, когда добавляет счетчик к спиннеру - Ответить: обработать событие самостоятельно, чтобы обычное поведение не запускалось, например отказать в выполнении команды
Где работают моды
Хуки мода работают в каждом типе сессии, которая загружает плагин, независимо от того, какой провайдер обслуживает модель, включая Amazon Bedrock, Agent Platform от Google Cloud и Microsoft Foundry. С рисованием все ограниченнее: то, что рисует мод, отображается в терминале, приложении Desktop и расширении VS Code. В этой таблице перечислены все места, где вы можете запустить Claude Code:
Мод, который рисует, может проверить, в каком приложении он работает, и там, где ничего не рисуется, перейти на строку в транскрипте или текстовый ответ команды.
Управление модами для вашей организации
Администраторы решают, работают ли моды и какие из них, через управляемые параметры. Управление модами для вашей организации охватывает, что происходит по умолчанию, как просмотреть мод и как применить политику с помощью собственного мода.Сравнение модов, хуков настроек, скиллов и серверов MCP
Моды, хуки настроек, скиллы и серверы MCP перекрываются. Эта таблица показывает, что это такое и когда выбрать каждый.
Каждый из остальных имеет свою собственную страницу: Хуки, Скиллы и MCP. Плагин может содержать их все, поэтому мод может поставляться в одном плагине со скиллом и сервером MCP.
Моды, встроенные в Claude Code
Некоторые собственные функции Claude Code — это моды. Чтобы увидеть те, которые есть в вашей сессии, запустите/plugin в промпте Claude Code и перейдите на вкладку Installed, где они перечислены в разделе Built-in. Вы не можете обновлять или удалять встроенный мод. Строка mods active не включает встроенные моды.
В этой таблице перечислены некоторые записи Built-in по имени, которое показывает /plugin:
Для плагина Built-in, которого нет в таблице, откройте его сведения в
/plugin, чтобы прочитать, что он делает, или отключить его.
Настройки и флаги, которые останавливают установленные моды, такие как disableAllHooks, --bare и --safe-mode, не останавливают встроенные моды.
Прочитайте исходный код встроенных модов
Исходный код некоторых из этих модов общедоступен в каталогеmods репозитория Claude Code. Каждый из них — это полноценный плагин с модулем хуков и тестами:
diff: панель/diffс кнопками, привязанными к действиям клавиатуры, и прокруткой, которую мод обрабатывает самagents-md: загружаетAGENTS.mdкак инструкции проекта с опциейuserConfigsec-default: защита, описанная в разделе Знайте, что происходит по умолчанию, образец мода, который применяет политикуtelemetry: добавляет методы, которые могут вызывать другие моды, и поставляет их типы
Следующие шаги
- Создание мода: создайте один, который считает вызовы инструментов, показывает счетчик рядом со спиннером и добавляет команду, и узнайте цикл редактирования и перезагрузки
- Рисование в интерфейсе: панели, полоса над промптом, кнопки, текстовые поля и состояние
- Реакция на события: вызовы инструментов, промпты, ходы и порядок, в котором работают моды
- Использование API модов: команды, инструменты, вызовы моделей, таймеры и файлы
- Тестирование мода: автоматизированные тесты, которые работают без сессии
- Устранение неполадок мода: причины, по которым мод ничего не делает, и лог отладки
- Управление модами для вашей организации: значения по умолчанию, управляемые настройки, просмотр мода и моды политики
- Справочник модов: события, методы, элементы и ограничения