Automatizar fluxos de trabalho com hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Configure seu primeiro hook

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"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
• Recarregar ambiente quando diretório ou arquivos mudam
• Aprovar automaticamente prompts de permissão específicos

​

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\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

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

​

Recarregar ambiente quando diretório ou arquivos mudam

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Aprovar automaticamente prompts de permissão específicos

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Como hooks funcionam

• "type": "http": POST dados de evento para uma URL. Consulte HTTP hooks.
• "type": "mcp_tool": chamar uma ferramenta em um servidor MCP já conectado. Consulte MCP tool hooks.
• "type": "prompt": avaliação LLM de turno único. Consulte Prompt-based hooks.
• "type": "agent": verificação multi-turno com acesso a ferramentas. Agent hooks são experimentais e podem mudar. Consulte Agent-based hooks.

​

Combinar resultados de múltiplos hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

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, UserPromptExpansion 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. Alguns eventos não podem ser bloqueados: para SessionStart, Setup, Notification e outros, exit 2 mostra stderr ao usuário e a execução continua. Consulte comportamento do código de saída 2 por evento para a lista completa.
• Qualquer outro código de saída: a ação prossegue. A transcrição mostra um aviso <hook name> hook error seguido pela primeira linha de stderr; o stderr completo vai para o log de debug.

​

Saída JSON estruturada

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

• "allow": pular o prompt de permissão interativo. Regras de negação e pedido, incluindo listas de negação gerenciadas por empresa, ainda se aplicam
• "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"
          }
        ]
      }
    ]
  }
}

​

Filtrar por nome de ferramenta e argumentos com o campo if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Configurar local do hook

​

Hooks baseados em prompt

• "ok": true: a ação prossegue
• "ok": false: o que acontece depende do evento:
  • Stop e SubagentStop: o reason é alimentado de volta ao Claude para que ele continue trabalhando
  • PreToolUse: a chamada de ferramenta é negada e o reason é retornado ao Claude como o erro da ferramenta, para que ele possa se ajustar e continuar
  • PostToolUse, PostToolBatch, UserPromptSubmit e UserPromptExpansion: o turno termina e o reason aparece no chat como uma linha de aviso

{
  "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. Texto retornado via additionalContext é injetado como um lembrete do sistema que Claude lê como texto simples. HTTP hooks se comunicam através do corpo da resposta em vez disso.
• Os timeouts do hook variam por tipo. Substitua por hook com o campo timeout em segundos.
  • command, http, mcp_tool: 10 minutos. UserPromptSubmit reduz estes para 30 segundos.
  • prompt: 30 segundos.
  • agent: 60 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. Erros de API disparam StopFailure em vez disso.
• Quando múltiplos hooks PreToolUse retornam updatedInput para reescrever argumentos de uma ferramenta, o último a terminar vence. Como hooks executam em paralelo, a ordem é não-determinística. Evite ter mais de um hook modificando a entrada da mesma ferramenta.

​

Hooks e modos de permissão

​

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:
  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. Para evitar quoting de shell completamente, adicione "args": [] para mudar para forma exec, que gera o script diretamente sem um shell
• 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

• Edições de arquivo são normalmente capturadas automaticamente. Se não tiverem aparecido após alguns segundos, o observador de arquivo pode ter perdido a mudança: reinicie sua sessão para forçar 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