Создание мода

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

​

Попросите Claude написать мод

​

Используйте мод в других сеансах

• В сеансе, который вы запускаете: в вашей оболочке выполните claude --plugin-dir ~/mods/git-branch
• Для других людей: добавьте его на маркетплейс, чтобы они могли его установить

​

Сеансы, где мод, написанный Claude, не может загрузиться

• Никого нет, чтобы одобрить: сеанс не может показать вам приглашение, как в запуске claude -p или в режиме dontAsk
• Рабочая область не доверена: вы не приняли приглашение доверия для каталога
• Моды остановлены: вы запустили с --safe-mode или --bare, вы установили disableAllHooks, или управляемые параметры вашей организации это блокируют

​

Напишите мод сами

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json: манифест плагина
• hooks.json: указывает на ваш файл кода
• register.js: ваш код, называемый модулем hooks

mkdir -p first-mod/.claude-plugin first-mod/hooks

New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
  "author": { "name": "Your Name" }
}

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

// The count, shared by the hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs when the session starts, before your first prompt
  on('session.start', async ($, e, next) => {
    // Add the /tally command
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    // Let the session start as usual
    return next(e)
  })

  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs when you type /tally, and only then, because of the matcher
  on('command.run', { command: 'tally' }, async () => {
    // The text to print in the transcript
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

claude --plugin-dir ./first-mod

claude -p "/tally" --plugin-dir ./first-mod

first-mod: Claude has made 0 tool calls since this mod loaded

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })
  })

​

Как работает пример мода

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

• Observe: hook session.start регистрирует команду, и hook tool.call подсчитывает вызов и просит перерисовку. Оба возвращают next(e), поэтому сеанс запускается и инструмент работает как обычно.
• Answer: hook command.run возвращает свой собственный результат и никогда не вызывает next. Второй аргумент on, { command: 'tally' }, — это фильтр, называемый matcher, поэтому hook запускается только для /tally.
• Rewrite: hook ui.render вызывает next с копией e, чей suffix содержит счётчик, поэтому Claude Code рисует свой обычный спиннер с вашим текстом после слова

​

Продолжайте работать над модом

​

Измените мод с помощью Claude

claude --plugin-dir ./first-mod

​

Получите определения типов для вашей версии

​

Проверьте, что Claude Code читает из вашего мода

claude plugin validate ./first-mod

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

✔ Validation passed

• Напишите каждый вызов API модов полностью: $, пространство имён, затем метод, как в $.store.get('notes'). Вы можете передать $ функции, объявленной на верхнем уровне того же файла, и для функции вашей с именем loadNotes строка calls: затем читает $.store.get (via loadNotes). Передача $ методу, функции, определённой внутри hook, или функции, которую вы импортируете из другого из ваших файлов, не проходит валидацию. Функции read и update, которые использует $.state, — это импорты, которые могут её принять. Не присваивайте $ или одно из его пространств имён переменной, не деструктурируйте его и не индексируйте его с вычисленным именем. const ui = $.ui не проходит с $.ui is used as a value.
• Напишите имя события в каждом вызове on как строковый литерал, например 'tool.call'. Переменная или цикл по списку имён не проходит с the event name passed to on() is not a string literal.
• Внутри register не объявляйте вторую переменную или параметр с именем on. Валидация не проходит с "on" is declared again (shadowed).
• Импортируйте только из файлов внутри каталога плагина, по относительному пути. Единственный разрешённый голый импорт — это claude-code, для типов и нескольких помощников.
• Используйте объявления import в верхней части файла, как в import { name } from './file.js'. Динамический import() не проходит с a dynamic import(); a hooks module imports its own files with an import declaration.
• Напишите каждый файл как модуль ES, с import, а не require. Справочник перечисляет расширения файлов, которые загружает Claude Code.

​

Протестируйте мод

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Answer each tool call in Claude Code's place, so no tool runs
  on('tool.call', () => ({ result: 'ok' }))

  // Raise two tool calls, which the mod's tool.call hook counts
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // Run /tally and check the text its hook returns
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

claude plugin test

tests/first-mod.test.ts:
(pass) /tally reports the tool calls the mod has seen [22.87ms]

 1 pass
 0 fail
Ran 1 test across 1 file. [0.19s]

​

Поделитесь своим модом

​

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

• Рисуйте в интерфейсе: откройте панель, рисуйте над приглашением и добавляйте кнопки и текстовые поля
• Реагируйте на события: hook вызовы инструментов, приглашения и ходы
• Используйте API модов: добавляйте команды и инструменты, вызывайте модель и запускайте работу по таймеру
• Протестируйте мод: заглушка того, что Claude Code ответит, и тестирование таймеров и рисунков
• Устраняйте неполадки мода: причины, по которым мод ничего не делает, и журнал отладки
• Прочитайте исходный код встроенных модов: полные плагины, каждый со своим модулем hooks и тестами