Você escreve três arquivos:

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

1. Crie o diretório do plugin

Crie os dois diretórios que contêm os arquivos:

[tab] Bash ou Zsh

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

[tab] PowerShell

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

2. Escreva o manifest

Um mod é um plugin, e um mod precisa de um manifest. O manifest deste mod não tem campos especiais. Salve isto como first-mod/.claude-plugin/plugin.json:

{
  "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" }
}

3. Diga ao Claude Code onde seu código está

Quando o Claude Code carrega um plugin, ele lê o hooks/hooks.json do plugin. A chave modules naquele arquivo dá o caminho para seu código, e tê-la é o que torna o plugin um mod. Liste um caminho, relativo a hooks.json. Aqui ele aponta para register.js, que você escreve no próximo passo.

Salve isto como first-mod/hooks/hooks.json:

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

4. Escreva o código

Este arquivo é o código do mod, chamado de hooks module. Quando o mod é carregado, o Claude Code chama a função register que o arquivo exporta e passa a ela uma função chamada on. Cada chamada a on registra um manipulador de evento, chamado de hook, para o evento que ele nomeia.

Salve isto como first-mod/hooks/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 + '…' } })
  })
}

O arquivo mantém uma contagem em calls e registra quatro hooks:

• session.start é executado quando a sessão inicia, antes do seu primeiro prompt, e novamente cada vez que o mod recarrega. Ele adiciona o comando /tally ao Claude Code.
• tool.call é executado cada vez que Claude está prestes a usar uma ferramenta. Ele adiciona um a calls e pede ao Claude Code para desenhar a interface novamente.
• command.run é executado quando você digita /tally. Ele retorna o texto a ser impresso.
• ui.render é executado cada vez que o Claude Code desenha o spinner. Ele adiciona a contagem após a palavra do spinner.

Como o mod de exemplo funciona explica os três argumentos que cada hook recebe e o que cada um retorna.

5. Carregue o mod

Inicie o Claude Code com a flag --plugin-dir, que carrega um diretório de plugin para uma sessão sem instalá-lo:

claude --plugin-dir ./first-mod

6. Experimente o mod

Peça ao Claude para fazer algo que leve algumas chamadas de ferramentas, como list the files here and read the README. Enquanto Claude trabalha, a palavra do spinner é seguida por uma contagem que sobe, como em Thinking · tool calls: 2…. Quando Claude termina, digite /tally e pressione Enter. A transcrição mostra first-mod: Claude has made 2 tool calls since this mod loaded, com sua própria contagem. O Claude Code coloca o nome do plugin na frente do texto do comando.

Para verificar o comando sem uma sessão interativa, execute-o em modo não interativo:

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

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

Se /tally não estiver na lista de comandos, o módulo não foi carregado. Consulte Descubra por que um mod não faz nada.

7. Altere o código enquanto a sessão é executada

Deixe a sessão aberta. Em register.js, altere ' · tool calls: ' para ' · tools used: ' no hook ui.render e salve. A linha destacada é a que muda:

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

Uma linha na transcrição diz que first-mod recarregou e lista seus hooks, e o próximo spinner usa o novo texto, como em Thinking · tools used: 1….

Como o mod de exemplo funciona

Cada função que você passa a on é um hook, que é um manipulador de evento. O Claude Code passa a cada hook os mesmos três argumentos:

• 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

Os hooks em first-mod lidam com seus eventos destas maneiras:

• 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

O Claude Code observa um diretório carregado com --plugin-dir e hot-recarrega o hooks module quando um arquivo nele muda. Cada recarga executa register novamente, então calls volta a 0 e /tally começa a contar novamente. Para manter um valor entre recargas, consulte Manter estado.

Continue trabalhando em um mod

Uma vez que um mod é carregado, você pode fazer Claude alterá-lo, verificar seu código contra as definições de tipo para sua versão, listar os eventos e chamadas que o Claude Code encontra nele, e testá-lo.

Altere um mod com Claude

Para alterar um mod que você já tem, inicie a sessão com --plugin-dir apontado para o diretório do mod, para que o que Claude escreve seja carregado na mesma sessão:

claude --plugin-dir ./first-mod

Depois peça pela mudança, por exemplo add a /tally-reset command to this mod that sets the tally back to zero. Claude edita o hooks module, executa claude plugin validate, e corrige o que ele relata. Um diretório que você carrega com --plugin-dir é um caminho protegido, então nos modos default e acceptEdits você é solicitado a aprovar cada edição de Claude ao mod. A tabela de caminhos protegidos dá o resultado para os outros modos de permissão.

Os arquivos que Claude salva durante sua rodada recarregam quando a rodada termina, então você pode tentar /tally-reset assim que Claude terminar.

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

Quando o Claude Code carrega um mod de --plugin-dir em uma sessão interativa, ou um mod que Claude escreveu para você, ele escreve arquivos de declaração TypeScript no diretório .claude-plugin/types/ do mod. Eles descrevem os eventos exatos, métodos da API de mods e elementos na versão do Claude Code que você está executando, então seu editor pode autocompletar e verificar tipos em seus hooks. O diretório contém estes arquivos:

Se seu mod não tem seu próprio tsconfig.json, o Claude Code adiciona um na raiz do mod que estende o gerado, então seu editor e tsc -p ./first-mod verificam tipos do mod sem mais configuração.

Os eventos e métodos podem mudar entre releases, então confie nesses arquivos sobre qualquer página, inclusive esta, quando discordarem.

claude-code/index.d.ts é a referência mais completa para sua compilação, com um comentário e um exemplo para cada método da API de mods. Para procurar algo, pesquise o arquivo por seu nome, como 'tool.call'.

Verifique o que o Claude Code lê do seu mod

Para ver seu mod da maneira que o Claude Code o vê, sem executar seu código ou iniciar uma sessão, use claude plugin validate. Ele verifica o manifest e executa a mesma análise estática no código-fonte do hooks module que o Claude Code executa quando carrega um mod. Em seu shell, execute-o no diretório do mod:

claude plugin validate ./first-mod

Para first-mod, a saída inclui estas linhas.

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

✔ Validation passed

Verifique a linha hooks: para ver os eventos que seu módulo conecta, cada um com seu filtro entre chaves, e calls: para ver cada método da API de mods que ele chama. Se seu módulo lê ou define variáveis de ambiente, procure também as linhas env reads: e env writes:, e state reads: e state writes: se ele usa $.state. Você também vê uma linha para cada hook que pode recusar uma ação, como gating hook without .catch: tool.call, que informa se esse hook tem um handler .catch.

Se um evento que você pretendia tratar está faltando nas linhas hooks:, o Claude Code também não chamará esse hook. A causa usual é um nome de evento digitado incorretamente, que o comando relata como um erro como "tool.calls" is not an event.

Siga estas regras para que a análise estática possa encontrar cada hook e chamada:

• Escreva cada chamada da API de mods por completo: $, 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

Você pode escrever testes automatizados para um mod e executá-los de seu shell com claude plugin test, sem sessão, sign-in ou rede. Um teste dispara os eventos que seus hooks tratam e verifica o que os hooks fizeram.

Este teste dispara duas chamadas de ferramenta, executa /tally, e verifica que a resposta conta ambas. Salve-o como first-mod/tests/first-mod.test.ts:

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

  // Fire 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')
})

Em seu shell, execute os testes do diretório first-mod:

claude plugin test

A saída nomeia cada teste e se passou, com tempos que variam de execução para execução:

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]

Teste um mod cobre stubbing de uma chamada de modelo ou da loja, e testes de temporizadores e desenhos.

Compartilhe seu mod

Um mod é um plugin, então você o versiona no manifest e as pessoas o instalam e atualizam com os comandos /plugin. A forma de compartilhá-lo depende de para quem ele é:

• Algumas pessoas: envie a elas o diretório do plugin ou um .zip dele. Consulte Compartilhe um plugin sem um marketplace
• Sua equipe: liste-o no seu próprio marketplace, como um repositório privado com um diretório para cada plugin. Para adicionar esse marketplace para todos que trabalham em um repositório, registre-o nas configurações do repositório
• Toda a sua organização: um administrador pode instalar os mods da sua organização por meio de configurações gerenciadas
• Qualquer pessoa: torne público o repositório do seu marketplace ou envie o plugin para o diretório da Anthropic

Antes de fazer isso, verifique o name do plugin: claude plugin validate falha em um nome que parece um dos próprios da Anthropic, como um que começa com claude-. Os eventos e métodos podem mudar entre releases, então seu README é o lugar para dizer qual versão do Claude Code você testou.

Continue desenvolvendo contra o diretório com --plugin-dir, não contra uma cópia instalada. O Claude Code armazena em cache um plugin instalado por versão, então suas edições não chegam à cópia instalada até que você aumente a versão e instale novamente.

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