Моди 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.