Quick answer
opencode hooks: what to know first
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
This page deliberately separates `opencode hooks` from the site's broader OpenCode Plugins guide. The plugins page explains when packaged extensions are worth installing. This page focuses on lifecycle behavior: event choice, scope, placement, examples, failure modes, testing, rollback, and how hooks interact with tools, skills, commands, MCP, and GitHub automation.
Related site guides: OpenCode Plugins, OpenCode Skills, OpenCode MCP, OpenCode session storage.
1. Quando usar hooks
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Se a necessidade não depende do momento exato, mantenha a solução em skill, command, permissão ou MCP. Um hook precisa ter condição clara e resultado visível.
2. Onde os hooks ficam
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Regras do repositório devem ficar perto do projeto para revisão da equipe. Preferências pessoais ficam no global, e pacotes npm exigem revisão de fonte e versão.
3. Escolher o evento
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Escreva primeiro a frase do evento: antes de executar, depois da ferramenta ou depois da alteração de arquivo. Se misturar ações, divida o hook.
4. Exemplos seguros e riscos
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Exemplos seguros avisam, normalizam ou registram pouco. Evite commits, pushes, segredos, rede remota e edições silenciosas dentro de hooks.
5. Testar em repositório descartável
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
O teste deve usar repositório pequeno, comando inofensivo, revisão da saída e caminho claro para desativar o plugin.
6. Diagnóstico por camadas
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
Para diagnosticar, desative uma camada por vez e repita a mesma tarefa. Assim você separa ciclo de vida, instruções, MCP e provider.
7. Separar de GitHub e CI
Use hooks apenas quando o timing importa. Eles servem para proteções pequenas antes ou depois de ferramentas, não para substituir skills, commands, MCP, permissões ou CI.
GitHub e CI devem ficar em workflows explícitos. Hooks locais apenas apoiam guardrails durante a sessão.
OpenCode hooks FAQ
O que são hooks OpenCode?
Callbacks de ciclo de vida retornados por plugins.
São iguais a plugins?
Não. O plugin carrega e retorna hooks.
Onde colocar?
No projeto para regras do repositório; globalmente para preferências pessoais.
Substituem permissões?
Não. Permissões controlam políticas amplas.
Como testar?
Em um repositório descartável com tarefa pequena e rollback claro.
Sources
Official OpenCode documentation and current SERP evidence were checked on 2026-07-23. Plugin APIs and event names can change, so verify exact code against the current docs before shipping a hook.