Automatizar fluxos de trabalho com hooks

​

Configure seu primeiro hook

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

notify-send 'Claude Code' 'Claude Code needs your attention'

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

​

O que você pode automatizar

• Receba notificações quando Claude precisa de entrada
• Formatar código automaticamente após edições
• Bloquear edições em arquivos protegidos
• Re-injetar contexto após compactação
• Auditar mudanças de configuração

​

Receba notificações quando Claude precisa de entrada

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

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

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formatar código automaticamente após edições

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Bloquear edições em arquivos protegidos

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Re-injetar contexto após compactação

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Auditar mudanças de configuração

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Como hooks funcionam

• "type": "http": POST de dados de evento para uma URL. Consulte HTTP hooks.
• "type": "prompt": avaliação LLM de turno único. Consulte Hooks baseados em prompt.
• "type": "agent": verificação multi-turno com acesso a ferramentas. Consulte Hooks baseados em agente.

​

Ler entrada e retornar saída

​

Entrada do hook

{
  "session_id": "abc123",          // ID único para esta sessão
  "cwd": "/Users/sarah/myproject", // diretório de trabalho quando o evento disparou
  "hook_event_name": "PreToolUse", // qual evento acionou este hook
  "tool_name": "Bash",             // a ferramenta que Claude está prestes a usar
  "tool_input": {                  // os argumentos que Claude passou para a ferramenta
    "command": "npm test"          // para Bash, este é o comando shell
  }
}

​

Saída do hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr se torna feedback do Claude
  exit 2 # exit 2 = bloquear a ação
fi

exit 0  # exit 0 = deixar prosseguir

• Exit 0: a ação prossegue. Para hooks UserPromptSubmit e SessionStart, qualquer coisa que você escrever para stdout é adicionada ao contexto do Claude.
• Exit 2: a ação é bloqueada. Escreva um motivo para stderr, e Claude o recebe como feedback para que possa se ajustar.
• Qualquer outro código de saída: a ação prossegue. Stderr é registrado mas não mostrado ao Claude. Alterne o modo verboso com Ctrl+O para ver essas mensagens na transcrição.

​

Saída JSON estruturada

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": prosseguir sem mostrar um prompt de permissão
• "deny": cancelar a chamada de ferramenta e enviar o motivo ao Claude
• "ask": mostrar o prompt de permissão ao usuário normalmente

​

Filtrar hooks com matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Configurar local do hook

​

Hooks baseados em prompt

• "ok": true: a ação prossegue
• "ok": false: a ação é bloqueada. O "reason" do modelo é alimentado de volta ao Claude para que ele possa se ajustar.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks baseados em agente

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitações e solução de problemas

​

Limitações

• Hooks de comando se comunicam apenas através de stdout, stderr e códigos de saída. Eles não podem disparar comandos ou chamadas de ferramenta diretamente. HTTP hooks se comunicam através do corpo da resposta em vez disso.
• O timeout do hook é 10 minutos por padrão, configurável por hook com o campo timeout (em segundos).
• Hooks PostToolUse não podem desfazer ações já que a ferramenta já foi executada.
• Hooks PermissionRequest não disparam em modo não-interativo (-p). Use hooks PreToolUse para decisões de permissão automatizadas.
• Hooks Stop disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário.

​

Hook não dispara

• Execute /hooks e confirme que o hook aparece sob o evento correto
• Verifique que o padrão do matcher corresponde ao nome da ferramenta exatamente (matchers são sensíveis a maiúsculas)
• Verifique que você está acionando o tipo de evento correto (por exemplo, PreToolUse dispara antes da execução da ferramenta, PostToolUse dispara depois)
• Se usar hooks PermissionRequest em modo não-interativo (-p), mude para PreToolUse em vez disso

​

Erro de hook na saída

• Seu script saiu com um código não-zero inesperadamente. Teste-o manualmente canalizando JSON de amostra:
  Reportar código incorreto

  Copiar

  Perguntar à IA

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Verifique o código de saída
  
• Se você vir “command not found”, use caminhos absolutos ou $CLAUDE_PROJECT_DIR para referenciar scripts
• Se você vir “jq: command not found”, instale jq ou use Python/Node.js para análise JSON
• Se o script não está executando em tudo, torne-o executável: chmod +x ./my-hook.sh

​

/hooks mostra nenhum hook configurado

• Reinicie sua sessão ou abra /hooks para recarregar. Hooks adicionados através do menu /hooks entram em vigor imediatamente, mas edições manuais de arquivo exigem um recarregamento.
• Verifique que seu JSON é válido (vírgulas finais e comentários não são permitidos)
• Confirme que o arquivo de configuração está no local correto: .claude/settings.json para hooks de projeto, ~/.claude/settings.json para hooks globais

​

Stop hook executa para sempre

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Permitir que Claude pare
fi
# ... resto da lógica do seu hook

​

Validação JSON falhou

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# Em ~/.zshrc ou ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Técnicas de debug

​

Saiba mais

• Referência de Hooks: esquemas de eventos completos, formato de saída JSON, hooks assíncronos e hooks de ferramentas MCP
• Considerações de segurança: revise antes de implantar hooks em ambientes compartilhados ou de produção
• Exemplo de validador de comando Bash: implementação de referência completa