Os hooks do Claude Code são comandos shell definidos pelo usuário que executam em vários pontos do ciclo de vida do Claude Code. Os hooks fornecem controle determinístico sobre o comportamento do Claude Code, garantindo que certas ações sempre aconteçam em vez de depender do LLM para escolher executá-las.

Para documentação de referência sobre hooks, veja Referência de hooks.

Exemplos de casos de uso para hooks incluem:

  • Notificações: Personalize como você é notificado quando o Claude Code está aguardando sua entrada ou permissão para executar algo.
  • Formatação automática: Execute prettier em arquivos .ts, gofmt em arquivos .go, etc. após cada edição de arquivo.
  • Logging: Rastreie e conte todos os comandos executados para conformidade ou depuração.
  • Feedback: Forneça feedback automatizado quando o Claude Code produz código que não segue as convenções da sua base de código.
  • Permissões personalizadas: Bloqueie modificações em arquivos de produção ou diretórios sensíveis.

Ao codificar essas regras como hooks em vez de instruções de prompt, você transforma sugestões em código de nível de aplicação que executa toda vez que é esperado que execute.

Você deve considerar as implicações de segurança dos hooks ao adicioná-los, porque os hooks executam automaticamente durante o loop do agente com as credenciais do seu ambiente atual. Por exemplo, código malicioso de hooks pode exfiltrar seus dados. Sempre revise sua implementação de hooks antes de registrá-los.

Para práticas completas de segurança, veja Considerações de Segurança na documentação de referência de hooks.

​
Visão Geral dos Eventos de Hook

O Claude Code fornece vários eventos de hook que executam em diferentes pontos do fluxo de trabalho:

  • PreToolUse: Executa antes das chamadas de ferramenta (pode bloqueá-las)
  • PostToolUse: Executa após as chamadas de ferramenta serem concluídas
  • Notification: Executa quando o Claude Code envia notificações
  • Stop: Executa quando o Claude Code termina de responder
  • SubagentStop: Executa quando as tarefas do subagente são concluídas

Cada evento recebe dados diferentes e pode controlar o comportamento do Claude de maneiras diferentes.

​
Início Rápido

Neste início rápido, você adicionará um hook que registra os comandos shell que o Claude Code executa.

​
Pré-requisitos

Instale jq para processamento JSON na linha de comando.

​
Passo 1: Abrir configuração de hooks

Execute o comando slash /hooks e selecione o evento de hook PreToolUse.

Os hooks PreToolUse executam antes das chamadas de ferramenta e podem bloqueá-las enquanto fornecem feedback ao Claude sobre o que fazer diferente.

​
Passo 2: Adicionar um matcher

Selecione + Add new matcher… para executar seu hook apenas em chamadas de ferramenta Bash.

Digite Bash para o matcher.

Use uma string vazia "" para corresponder a todas as ferramentas. O caractere * não é um matcher válido por si só.

​
Passo 3: Adicionar o hook

Selecione + Add new hook… e digite este comando:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
Passo 4: Salvar sua configuração

Para localização de armazenamento, selecione User settings já que você está registrando no seu diretório home. Este hook então se aplicará a todos os projetos, não apenas ao seu projeto atual.

Então pressione Esc até retornar ao REPL. Seu hook agora está registrado!

​
Passo 5: Verificar seu hook

Execute /hooks novamente ou verifique ~/.claude/settings.json para ver sua configuração:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
Passo 6: Testar seu hook

Peça ao Claude para executar um comando simples como ls e verifique seu arquivo de log:

cat ~/.claude/bash-command-log.txt

Você deve ver entradas como:

ls - Lists files and directories

​
Mais Exemplos

Para um exemplo de implementação completo, veja o exemplo de validador de comando bash em nossa base de código pública.

​
Hook de Formatação de Código

Formate automaticamente arquivos TypeScript após edição:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$(.tool_input.file_path)' | grep -q '\\.ts$'; then npx prettier --write '$(.tool_input.file_path)'; fi"
          }
        ]
      }
    ]
  }
}

​
Hook de Notificação Personalizada

Receba notificações na área de trabalho quando o Claude precisar de entrada:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

​
Hook de Proteção de Arquivo

Bloqueie edições em arquivos sensíveis:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​
Saiba mais

  • Para documentação de referência sobre hooks, veja Referência de hooks.
  • Para práticas abrangentes de segurança e diretrizes de segurança, veja Considerações de Segurança na documentação de referência de hooks.
  • Para passos de solução de problemas e técnicas de depuração, veja Depuração na documentação de referência de hooks.