Do que é feito um mod
Os três arquivos de um mod do Claude Code, a função register e seus hooks, e o menor mod que mostra algo na tela.
O que faz
Um mod é um plugin do Claude Code feito de hooks de função: TypeScript que roda dentro do Claude Code e muda o que ele mostra ou como ele se comporta. Ao final deste guia, você vai saber de quais arquivos um mod precisa e o que a função register faz, e terá um mod que mostra um toast quando uma sessão começa e mantém uma contagem de chamadas de ferramentas na sua linha de status.
A API de mods está em acesso antecipado e muda entre versões. Tudo aqui foi verificado com o Claude Code 2.1.325 e seu arquivo de declarações, claude-code.d.ts. Quando a sua versão for mais nova, esse arquivo é a referência.
Como funciona por dentro
Um mod é uma pasta com três arquivos que você escreve à mão:
| Arquivo | O que contém |
|---|---|
.claude-plugin/plugin.json |
O manifesto: name, version, description e, opcionalmente, license, repository e types. |
hooks/hooks.json |
Uma linha que nomeia o módulo de hooks: { "modules": ["./register.tsx"] }. O caminho é relativo a hooks.json. |
hooks/register.tsx |
O módulo de hooks. Ele exporta register. |
O módulo de hooks é um módulo ES com extensão .ts, .tsx, .js ou outro sufixo de script. Ele roda em um ambiente próprio, sem DOM e sem Node. Tudo o que está fora do módulo (a tela, os arquivos, a rede, o relógio) é acessado pelo objeto $ que todo hook recebe. Outros arquivos do plugin são importados com declarações import comuns; um módulo que usa import() dinâmico não carrega.
register(on, options) é chamada quando o módulo carrega. on(event, matcher?, hook) adiciona um hook a um evento. options contém os valores dos campos userConfig que o manifesto declarar.
Todo hook tem a forma ($, e, next):
$é a interface do motor: exibição, armazenamento, estado, relógio, rede, processos, arquivos, sessão, modelo, ferramentas, comandos e o restante.eé a entrada do evento como um valor simples. Paratool.call, é a chamada da ferramenta, com o tipo restrito por ferramenta.next(e)passa o evento adiante para os outros plugins e depois para o comportamento do próprio Claude Code, e resolve com o resultado do evento.
Um hook que retorna sem chamar next responde ele mesmo ao evento. Um hook que chama next({ ...e, ... }) muda o que o restante da cadeia vê, dentro do que esse evento permite. A maioria dos hooks que só observam termina com return next(e).
O arquivo opcional types/index.d.ts é o contrato de tipos do mod. Ele declara a forma dos valores que o mod guarda em $.state (e, para um mod que adiciona um substantivo a $, esse substantivo). O plugin.json o nomeia em "types", e claude plugin validate confere as leituras e escritas de estado do mod com base nele.
Passo a passo
1. O manifesto
Crie uma pasta chamada greeter e escreva .claude-plugin/plugin.json:
{
"name": "greeter",
"version": "0.1.0",
"description": "Says hello when a session starts and counts tool calls"
}
O name é como o Claude Code, seu log de depuração e as suas chaves de estado se referem ao mod.
2. O arquivo de hooks
Escreva hooks/hooks.json:
{ "modules": ["./register.tsx"] }
3. Um hook que mostra algo
Escreva hooks/register.tsx com um hook em session.start:
import type { Register } from 'claude-code'
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
$.ui.toast('Hello from greeter')
return next(e)
})
}
Register vem do módulo claude-code. A importação é só de tipos: em tempo de execução, ela é vazia. $.ui.toast(text) mostra uma pequena caixa sob o nome do plugin por alguns segundos (4000 ms por padrão). Em seguida, o hook chama next(e) para que a sessão comece normalmente.
4. Uma linha de status que conta chamadas de ferramentas
Adicione um segundo hook. tool.call roda a cada chamada de ferramenta, e $.ui.status(text) fixa uma linha para este plugin sob o prompt até que a próxima chamada a substitua:
import type { Register } from 'claude-code'
export const register: Register = (on) => {
let count = 0
on('session.start', async ($, e, next) => {
$.ui.toast('Hello from greeter')
return next(e)
})
on('tool.call', async ($, e, next) => {
count += 1
$.ui.status(`greeter: ${count} tool calls`)
return next(e)
})
}
Isso funciona, mas count é uma variável do módulo. Salvar o arquivo recarrega o módulo em um ambiente novo, então a contagem recomeça do zero.
5. Um contrato de tipos e um estado que sobrevive a uma recarga
$.state guarda valores nomeados para a sessão, e eles sobrevivem a uma recarga a quente do módulo. Declare o valor em types/index.d.ts:
declare module 'claude-code' {
interface PluginState {
greeter: { calls: number }
}
}
Nomeie o arquivo no manifesto:
{
"name": "greeter",
"version": "0.1.0",
"description": "Says hello when a session starts and counts tool calls",
"types": "./types/index.d.ts"
}
Depois, use os auxiliares de estado atom e update de claude-code:
import { atom, update } from 'claude-code'
import type { Register } from 'claude-code'
const calls = atom({ plugin: 'greeter', key: 'calls' } as const, 0)
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
$.ui.toast('Hello from greeter')
return next(e)
})
on('tool.call', async ($, e, next) => {
const count = await update($, calls, (n) => n + 1)
$.ui.status(`greeter: ${count} tool calls`)
return next(e)
})
}
plugin e key precisam ser literais de string, de acordo com o contrato. update lê o valor, aplica a função e grava o resultado, tentando de novo se outra escrita chegar antes, e resolve com o novo valor.
O mod finalizado:
greeter/
.claude-plugin/plugin.json
hooks/hooks.json
hooks/register.tsx
types/index.d.ts
O guia “Instalar, recarregar, validar e testar” mostra como carregá-lo em uma sessão.
Erros comuns e como testar
- Esquecer o
next. Um hook que nunca chamanext(e)responde sozinho ao evento. Emsession.startoutool.call, isso muda mais do que você pretendia. Retornenext(e), a menos que responder seja o objetivo. - Registrar o mesmo hook duas vezes. Um registro repetido lança um erro, e um laço que executa um
on(...)duas vezes passa pelo validate, mas é recusado ao carregar. - Usar APIs do Node ou do DOM. Não existe
require, nem módulofs, nemwindow. Use$.fs,$.http,$.processe o restante de$. - Um hook que lança um erro. Ele é ignorado e a cadeia continua sem ele. Rode com
claude --debugdurante o desenvolvimento: o log de depuração diz por que um hook foi ignorado.
Rode claude plugin validate na pasta cedo e com frequência. Ele lê o manifesto, o contrato e o módulo de hooks da mesma forma que o Claude Code vai ler. Para o greeter finalizado, ele informa, entre outras linhas:
❯ types ./types/index.d.ts declares state: greeter.calls
❯ ./register.tsx hooks: session.start, tool.call
❯ ./register.tsx gating hook without .catch: tool.call
❯ ./register.tsx calls: $.state.get, $.state.set, $.ui.status, $.ui.toast
A linha gating hook without .catch é um fato, não uma falha: tool.call é um evento cuja resposta pode recusar o que foi pedido, e um hook ali que falha é ignorado. Só um hook que protege (um que pode recusar uma chamada) precisa de um tratador .catch.
Para ir além
O narsil-pet segue a mesma estrutura. Seu .claude-plugin/plugin.json define "license": "GPL-3.0-or-later", repository e "types": "./types/index.d.ts". Seu hooks/hooks.json é a mesma linha única mostrada acima. Seu hooks/register.tsx exporta register e registra um hook por evento, começando por session.start, que registra o comando /narsil, restaura as preferências a partir de $.store e inicia seus temporizadores antes de retornar next(e). Seu types/index.d.ts exporta os tipos do mod (Mood, Pet, Prefs e outros) e declara cada chave de $.state em PluginState['narsil-pet'].
Para ir além: como o mod real faz
Estes arquivos fazem parte dos mods originais, publicados sob a GPL v3. O código citado nesta página vem deles e mantém essa licença.
Este guia ajudou?
Todos os guias são gratuitos. Se este poupou seu tempo, você pode me pagar um café.
Me pague um café