Моды Claude Code: что это такое и мод, который мы встраиваем в каждого агента

1 октября 2026 года вышел Claude Code 2.1.287 с однострочной записью в changelog: «Added Claude Mods». Через четыре дня AgentsRoom начал загружать один из наших модов в агентов Claude, которых он запускает.

В этой статье разберём, что такое мод, что он умеет из того, что было недоступно старым точкам расширения, как его написать, загрузить и протестировать, и чему мы научились, встроив мод в каждого агента Claude, которого запускает AgentsRoom. Факты о Claude Code взяты из его документации и changelog, прочитанных 9 ноября 2026 года при установленном Claude Code 2.1.318.

Коротко. Мод представляет собой плагин Claude Code с модулем хуков (hooks module): файлом JavaScript или TypeScript, функции которого Claude Code вызывает изнутри собственного процесса, когда происходит событие. Функция может пропустить событие дальше, изменить его или ответить на него вместо Claude Code. Так мод рисует панель, добавляет команду или останавливает shell-команду до её запуска.

Что такое мод

У Claude Code уже были плагины: папка с манифестом в .claude-plugin/plugin.json, которая упаковывает навыки, субагентов, хуки настроек и MCP-серверы, чтобы они устанавливались одним целым. Мод стал ещё одной вещью, которую может содержать плагин. Когда hooks/hooks.json плагина указывает файл с кодом в ключе modules, Claude Code загружает этот файл и вызывает экспортируемую им функцию register. Тогда плагин и называют модом.

Внутри register каждый вызов on(event, hook) привязывает функцию к событию: tool.call перед запуском инструмента, prompt.submit, когда ты отправляешь промпт, session.start, command.run для слэш-команды, ui.render, когда Claude Code рисует часть своего экрана, и другие. Каждый хук получает три вещи:

• $, API модов: всё, что мод может делать за пределами собственного кода, например $.ui, $.command, $.fs, $.process или $.http.
• e, событие в виде простых данных: для вызова инструмента это имя инструмента и его аргументы.
• next, функцию, которая передаёт событие другим модам, а затем собственному поведению Claude Code, и возвращает результат.

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

Документация тоже называет эти функции хуками. Это не те хуки, которые ты пишешь в settings.json: их Claude Code теперь называет settings hooks, то есть хуками настроек.

Мод, хук настроек, навык или MCP-сервер

Эти четыре способа пересекаются, и мод среди них самый тяжёлый. Выбирай самый лёгкий, который справится с задачей.

Плагин может содержать все четыре, так что мод можно поставлять рядом с навыком и MCP-сервером, с которыми он работает.

Три файла мода

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json содержит обычный манифест плагина: имя, версию, описание. hooks.json указывает на код, { "modules": ["./register.ts"] }, один путь относительно этого файла. register.ts и есть модуль хуков. Claude Code загружает .js и .ts напрямую, без бандлера и без шага сборки, а единственный разрешённый «голый» импорт (bare import) это claude-code, для типов и нескольких вспомогательных функций.

Мод, который мы поставляем: кто изменил этот файл?

AgentsRoom запускает несколько агентов-кодеров в одном репозитории и показывает на своей вкладке «Изменения», какой агент изменил какой файл, чтобы ты мог проверить и закоммитить работу каждого агента отдельно. С файлами, записанными инструментами Edit и Write в Claude, всё было просто: Claude Code сообщает о них через хук настроек. С файлами, записанными shell-командой, нет. sed -i, heredoc, codemod или rm никогда не проходят через файловый инструмент.

До модов мы угадывали. AgentsRoom читал транскрипт сессии агента, чтобы узнать, когда началась и закончилась каждая команда Bash, а затем сопоставлял время изменения файла с этими окнами. Это работало в большинстве случаев и ломалось тремя способами, которые мы могли назвать:

• у удалённого файла нет времени изменения, поэтому удаление никогда не приписывалось агенту;
• команда только для чтения, например grep, открывала окно, в течение которого агент мог записать что угодно;
• всё зависело от формата транскрипта, который Claude Code волен менять.

Мод убирает угадывание. Наш мод agentsroom-changes подписывается на tool.call для двух shell-инструментов. Прямо перед запуском команды он делает снимок репозитория (git status плюс размер и время изменения каждого изменённого пути). Сразу после запуска он делает второй. Пути, которые различаются, и есть то, что изменила команда, включая удаления, и мод отправляет их в десктопное приложение AgentsRoom через локальный HTTP-эндпоинт. Вызов, который сам Claude Code помечает как только для чтения, ничего себе не приписывает.

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

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

Десктопное приложение копирует мод в свою папку и запускает каждого агента Claude командой claude --plugin-dir <that folder>, но только если установлен Claude Code 2.1.287 или новее. Мы выпустили его в AgentsRoom 1.201.0 5 октября 2026 года.

Чему мы научились, выпустив его

Мод никогда не должен стоить пользователю вызова инструмента. Наш хук стоит перед каждой shell-командой, которую запускает Claude. Если он выбросит исключение или начнёт ждать сеть, работа Claude остановится. Каждый шаг защищён, каждая отправка в десктопное приложение уходит без ожидания ответа, а единственное ожидание, которое мы допускаем, это два снимка git status, каждый не дольше 15 секунд. Потерянная отправка стоит одной атрибуции, но никогда не самой команды.

Ничего не делай, когда тебя не звали. Мод читает переменную окружения, которую AgentsRoom задаёт своим агентам. Если её нет, например потому что кто-то скопировал папку в собственную конфигурацию, каждый хук сразу переходит к next(e).

За папкой, загруженной через --plugin-dir, следят. Claude Code перезагружает мод, когда в этой папке меняется файл, а при перезагрузке register выполняется снова. Это определило то, как мы его устанавливаем: десктопное приложение записывает файл мода, только если его содержимое изменилось, потому что слепая перезапись при каждом запуске агента перезагружала бы мод во всех уже открытых консолях Claude.

Закладывай, что API будет меняться. События и методы могут меняться от релиза к релизу, и документация сама об этом предупреждает. Когда мод загружен из --plugin-dir, Claude Code записывает объявления типов работающей версии в .claude-plugin/types/; проверку типов мы делаем по ним, а не по веб-странице. А если какая-то сборка перестанет загружать наш мод, ничего не сломается: мод так и не сообщит о готовности, и AgentsRoom вернётся к старому методу через транскрипт.

Напиши свой

Есть два пути.

Попроси Claude. В интерактивной сессии Claude Code опиши нужный мод («показывай текущую ветку git над промптом»). Claude использует встроенный навык plugin-authoring, пишет мод в папку для этой сессии, а Claude Code один раз спрашивает, включать ли моды, которые пишет Claude. Ответь «да», и мод загрузится в конце хода, а затем будет перезагружаться после каждого хода, который его меняет.

Напиши три файла сам, затем:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate выводит строку hooks: с событиями, которые обрабатывает твой модуль, и строку calls: с каждым методом API модов, который он вызывает. Если события, которое ты собирался обрабатывать, там нет, Claude Code этот хук тоже не вызовет. У статического анализа свои правила: пиши каждый вызов полностью ($.ui.toast(...), никогда const ui = $.ui), передавай имена событий строковыми литералами и импортируй только собственные файлы по относительному пути.

Чтобы поделиться модом, обращайся с ним как с плагином, которым он и является: отправь папку или добавь её в маркетплейс (репозиторий с .claude-plugin/marketplace.json), чтобы мод устанавливали командой /plugin install <name>@<marketplace>.

Моды, которые можно почитать уже сегодня

• Встроенные в Claude Code: /plugin, вкладка Installed, раздел Built-in. Среди них панель /diff и загрузчик, который читает AGENTS.md как инструкции проекта; их исходный код вместе с тестами Anthropic публикует в папке mods репозитория anthropics/claude-code. Тоже встроенный и выключенный, пока ты его не включишь: You should know, побочный агент, который отмечает то, что ты или Claude могли упустить.
• Примеры от Anthropic в репозитории claude-code-playground: прогноз заполнения контекстного окна, нарисованный над промптом, защита, которая задерживает рискованную shell-команду и показывает, что она изменит, и команда /replay, которая пошагово проходит по правкам последнего хода.
• Наш, описанный выше: мод совсем без интерфейса, с единственным хуком tool.call. Хорошая форма для копирования, если тебе нужны данные, а не панель.

Прежде чем ставить чужой мод

Мод не изолирован в песочнице. Он работает с твоими правами: может читать и записывать твои файлы, читать переменные окружения и настройки (включая API-ключи), запускать программы, делать сетевые запросы, видеть каждый промпт и каждый вызов инструмента и одобрять вызов инструмента до того, как спросят тебя. Если ты включил песочницу Claude Code, она покрывает команды Bash, которые запускает Claude, но не процессы, которые запускает мод.

Поэтому читай, прежде чем ставить. Склонируй мод и запусти claude plugin validate на его папке: строки hooks: и calls: покажут, что он слушает и до чего дотягивается, ничего не запуская. Моду, который только рисует полосу над промптом, незачем вызывать $.http или $.process. Чтобы остановить все установленные тобой моды, запусти одну сессию с --safe-mode или задай "disableAllHooks": true в ~/.claude/settings.json.

Где работают моды

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

В AgentsRoom

Тебе ничего не нужно устанавливать: начиная с Claude Code 2.1.287 каждый агент Claude стартует с этим модом, а вкладка «Изменения» показывает файлы, которые каждая его shell-команда создала, изменила или удалила, рядом с агентом, который это сделал. Со старым Claude Code AgentsRoom по-прежнему сопоставляет записи из shell по транскрипту, как и раньше.

Та же идея работает в других CLI, где это возможно: oh-my-pi получает расширение с тем же контрактом, а остальные CLI сопоставляют записи из shell так же, как раньше. Если хочешь глубже разобраться в том, что Claude Code открывает на каждом шаге, наш гайд по хукам Claude Code описывает хуки настроек, рядом с которыми работает мод.

Частые вопросы

Что такое мод в Claude Code?

Мод представляет собой плагин Claude Code, который содержит модуль хуков (hooks module): файл JavaScript или TypeScript, функции которого Claude Code вызывает изнутри собственного процесса, когда что-то происходит, например вызов инструмента, отправка промпта или отрисовка части экрана. Каждая функция может пропустить событие дальше, изменить его или обработать сама. Именно это позволяет моду рисовать панель, добавлять команду или задерживать рискованную shell-команду.

Какая версия Claude Code нужна для модов?

Claude Code 2.1.287 или новее в терминале: эта версия вышла 1 октября 2026 года, и в её changelog записано «Added Claude Mods». Вкладка Code приложения Claude Desktop поддерживает моды начиная с 2.1.286. В расширении VS Code хуки работают, а для того, что рисует мод, нужно расширение 2.1.299 или новее. Чтобы проверить версию, выполни claude --version.

Чем мод отличается от хука Claude Code?

Хук в settings.json запускает shell-команду, HTTP-запрос или промпт при срабатывании события, вне Claude Code. Хуки мода представляют собой функции, которые работают внутри Claude Code. Они умеют то, чего не может хук настроек: рисовать в интерфейсе, добавлять слэш-команду, которая выполняется без хода Claude, переписывать вызов инструмента или отвечать на него, не запуская инструмент, и делить состояние между хуками.

Безопасно ли устанавливать моды Claude Code?

Мод не изолирован в песочнице. Он работает с твоими правами, может читать твои файлы и переменные окружения, запускать программы, делать сетевые запросы и одобрять вызов инструмента. Устанавливай моды только от авторов, которым доверяешь, и сначала запусти claude plugin validate на папке мода: команда перечислит события, на которые подписан мод, и вызовы, которые он делает, не запуская его.

Где найти примеры модов Claude Code?

Anthropic публикует исходный код некоторых встроенных модов, например панели /diff и загрузчика AGENTS.md, в папке mods репозитория anthropics/claude-code, а примеры модов выкладывает в репозитории anthropics/claude-code-playground. Мод AgentsRoom, описанный в этой статье, служит примером четвёртого вида: мод без интерфейса, только с хуком tool.call.

Можно ли отключить моды?

Да. Отключи отдельный мод на вкладке Installed в /plugin, запусти одну сессию с --safe-mode или задай disableAllHooks значение true в ~/.claude/settings.json, чтобы остановить все установленные тобой моды вместе с хуками настроек. --safe-mode и disableAllHooks не трогают встроенные моды: их отключают по одному в /plugin.