Criar um mod

• Peça ao Claude para escrever: descreva o que você quer em uma sessão do Claude Code
• Escreva você mesmo: siga o tutorial para aprender como o código de um mod funciona. Você não precisa de Node.js, um bundler ou uma etapa de compilação, porque o Claude Code carrega arquivos .js e .ts diretamente.

​

Peça ao Claude para um mod

​

Use o mod em outras sessões

• Em uma sessão que você inicia: em seu shell, execute claude --plugin-dir ~/mods/git-branch
• Para outras pessoas: adicione-o a um marketplace para que possam instalá-lo

​

Sessões onde um mod que Claude escreve não pode ser carregado

• Ninguém está lá para aprovar: a sessão não pode mostrar um prompt, como em uma execução claude -p ou modo dontAsk
• O workspace não é confiável: você não aceitou o prompt de confiança para o diretório
• Mods estão parados: você iniciou com --safe-mode ou --bare, você definiu disableAllHooks, ou as configurações gerenciadas da sua organização bloqueiam

​

Escreva um mod você mesmo

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

• plugin.json: o manifest do plugin
• hooks.json: aponta para seu arquivo de código
• register.js: seu código, chamado de hooks module

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 + '…' } })
  })

​

Como o mod de exemplo funciona

• A API de mods, chamada $: cada método que um mod pode chamar para alcançar fora de si mesmo, em namespaces como $.ui e $.command
• O evento, chamado e: a entrada do evento como dados simples, como o nome e argumentos de uma chamada de ferramenta
• O próximo manipulador, chamado next: uma função que passa o evento para os outros mods e depois para o comportamento próprio do Claude Code, e retorna o resultado

• Observar: o hook session.start registra o comando, e o hook tool.call conta a chamada e pede um redesenho. Ambos retornam next(e), então a sessão inicia e a ferramenta é executada como usual.
• Responder: o hook command.run retorna seu próprio resultado e nunca chama next. O segundo argumento a on, { command: 'tally' }, é um filtro, chamado de matcher, então o hook é executado apenas para /tally.
• Reescrever: o hook ui.render chama next com uma cópia de e cujo suffix contém a contagem, então o Claude Code desenha seu spinner usual com seu texto após a palavra

​

Continue trabalhando em um mod

​

Altere um mod com Claude

claude --plugin-dir ./first-mod

​

Obtenha definições de tipo para sua versão

​

Verifique o que o Claude Code lê do seu mod

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

• Soletra cada chamada da API de mods completamente: $, o namespace, depois o método, como em $.store.get('notes'). Você pode passar $ para uma função declarada no nível superior do mesmo arquivo, e para uma função sua chamada loadNotes, a linha calls: então lê $.store.get (via loadNotes). Passar $ para um método, uma função definida dentro do hook, ou uma função que você importa de outro de seus arquivos falha na validação. As funções read e update que $.state usa são as importações que podem levá-lo. Não atribua $ ou um de seus namespaces a uma variável, desestruture-o, ou indexe-o com um nome computado. const ui = $.ui falha com $.ui is used as a value.
• Escreva o nome do evento em cada chamada on como um literal de string, como 'tool.call'. Uma variável, ou um loop sobre uma lista de nomes, falha com the event name passed to on() is not a string literal.
• Dentro de register, não declare uma segunda variável ou parâmetro chamado on. A validação falha com "on" is declared again (shadowed).
• Importe apenas de arquivos dentro do diretório do plugin, por caminho relativo. A única importação nua permitida é claude-code, para tipos e alguns auxiliares.
• Use declarações import no topo do arquivo, como em import { name } from './file.js'. Um import() dinâmico falha com a dynamic import(); a hooks module imports its own files with an import declaration.
• Escreva cada arquivo como um módulo ES, com import e não require. A referência lista as extensões de arquivo que o Claude Code carrega.

​

Teste o mod

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]

​

Compartilhe seu mod

​

Próximos passos

• Desenhe na interface: abra um painel, desenhe acima do prompt, e adicione botões e campos de texto
• Reaja a eventos: conecte chamadas de ferramentas, prompts e rodadas
• Use a API de mods: adicione comandos e ferramentas, chame um modelo, e execute trabalho em um temporizador
• Teste um mod: stub do que o Claude Code responderia, e teste temporizadores e desenhos
• Solucione problemas de um mod: as razões pelas quais um mod não faz nada, e o log de depuração
• Leia a fonte de mods integrados: plugins completos, cada um com seu hooks module e testes