Modulo 3.6: Depuracao e logging de hooks

📝 Log para arquivo em append

A primeira linha de qualquer hook seu deve ser um log. Unica linha resolve 90% dos 'nao disparou'.

📐 Padrao de log

#!/usr/bin/env bash
# Hook com log de disparo

LOG="$HOME/.claude/hook.log"
INPUT=$(cat)

echo "$(date '+%Y-%m-%d %H:%M:%S') [$(basename $0)] fired" >> "$LOG"
echo "  input: $(echo $INPUT | tr -d '\n' | head -c 200)" >> "$LOG"

# ... resto do hook

💡 Rotacao simples

Uma vez por mes, mv hook.log hook.log.$(date +%Y-%m). Evita arquivo gigante.

🔍 tail -f no log

Com o log em lugar, terminal dedicado para tail vira seu monitor.

📐 Setup de monitoramento

# Terminal 1: seu Claude Code rodando

# Terminal 2: monitor de hooks
tail -f ~/.claude/hook.log

# Cada disparo aparece instantaneo:
# 2026-04-23 10:15:32 [session_start.sh] fired
#   input: {"cwd":"/home/user/proj",...}
# 2026-04-23 10:16:45 [user_prompt.sh] fired
#   input: {"user_message":"Como deploy?",...}

💡 Filtrar por hook

tail -f hook.log | grep session_start para isolar um hook especifico.

🚨 stderr para mensagens

stderr do hook aparece no Claude. Use para debug inline, sem trocar de janela.

💬 Mensagens inline

Como usar:

•echo 'debug info' >&2 na bash.
•sys.stderr.write('info\n') em Python.
•Claude exibe como aviso na sessao, nao afeta a logica.
•Uso: notificar 'hook disparou', 'API cai, usando fallback', 'memoria injetada: 400 tokens'.

🧪 Teste isolado: mock input

Reproduza exatamente o que Claude Code manda. Em 5 segundos voce sabe se o hook funciona.

📐 Mock input files

# Mocks organizados por evento
mkdir -p ~/.memory/test-mocks

# session_start.json
cat > ~/.memory/test-mocks/session_start.json < ~/.memory/test-mocks/user_prompt.json <

💡 Versione os mocks

Adicione ao git. Outros no time rodam os mesmos testes. Base para regression.

📊 Metricas: quantas vezes disparou

Contador simples revela padroes inesperados. Exemplo: PreCompact disparando mais do que voce achava.

📐 Contador simples

#!/usr/bin/env bash
# Hook que conta disparos

COUNTER="$HOME/.memory/counters/$(basename $0).count"
mkdir -p $(dirname $COUNTER)

# Incrementa atomico
(flock 9; echo $(($(cat $COUNTER 2>/dev/null || echo 0) + 1)) > $COUNTER) 9<>$COUNTER.lock

# Resto do hook...

# Ver metricas
# $ ls -1 ~/.memory/counters/
#   session_start.sh.count: 42
#   pre_compact.sh.count: 7
#   user_prompt.sh.count: 128

📊 O que medir

Disparos por dia: alinha com volume de uso
Taxa de PreCompact: indica quanto suas sessoes crescem
Ratio user_prompt / session_start: mensagens por sessao
Falhas (exit >0): hooks quebrando silenciosamente

🩹 Os 10 bugs mais comuns

Checklist direto. Percorra quando seu hook nao disparar ou disparar errado.

📐 Runbook

1. Script nao executavel     → chmod +x
2. Shebang errado            → #!/usr/bin/env bash no topo
3. Path relativo             → usar $CLAUDE_PROJECT_DIR ou ~
4. JSON invalido no output   → validar com jq
5. Permissao nao concedida   → settings 'permissions.allow'
6. Nome de evento errado     → case-sensitive (SessionStart)
7. Matcher nao bate          → '' para sempre, ou regex especifico
8. Timeout estourado         → usar nohup+& para trabalho pesado
9. stderr poluido            → so avisos uteis, nao prints de debug
10. Concurrency em arquivo   → flock ou atomic write

💡 Quando travar

Abra 3 terminais: 1) Claude Code, 2) tail -f hook.log, 3) echo input | hook.sh. Uma fonte de informacao em cada. Debug vai rapido.

📝 Resumo do Modulo

✓

Log em append — uma linha resolve 90% dos 'por que nao disparou?'.

✓

tail -f no log — feedback de 1 segundo.

✓

stderr aparece no Claude — use para debug inline.

✓

10 bugs comuns — checklist economiza horas.

Proximo:

Trilha 4 — Os 3 hooks criticos

← Modulo anterior Trilha 4 →