Notificações do Claude Code em um servidor remoto via SSH

01Por que comandos de notificação locais não fazem nada via SSH

Um hook é um comando que o Claude Code executa na máquina onde o próprio Claude Code está rodando. Em um servidor acessado via SSH, essa máquina é o servidor. Lá, o notify-send precisa de um daemon de notificações de desktop, que, como aponta o guia de hooks da Anthropic, servidores headless e sessões SSH não têm. O osascript e os toasts do PowerShell nem existem lá.

Então a pergunta não é "qual comando de notificação", e sim "como um sinal sai do servidor e chega até mim". Há três formas:

02Caminho 1: notificações pelo seu terminal SSH

A notificação nativa do Claude Code é uma escape sequence escrita no terminal. O guia de terminal da Anthropic diz que ela chega à sua máquina local via SSH, então uma sessão remota ainda consegue te avisar. Ghostty e Kitty a repassam para a central de notificações do seu desktop sem nenhuma configuração. O iTerm2 também, depois que você ativa: em Settings > Profiles > Terminal, marque Notification Center Alerts e, em Filter Alerts, ative Send escape sequence-generated alerts.

Se o seu terminal não é nenhum desses, ou você quer um texto próprio, um hook pode retornar uma escape sequence para o Claude Code escrever. Hooks não têm terminal próprio, então você a retorna em um campo terminalSequence. Salve isto no servidor como ~/.claude/hooks/notify-ssh.sh:

#!/bin/bash
body=$(jq -r '.message // "Claude Code needs your attention"')
# OSC 9 for iTerm2, WezTerm and ConEmu; use '\033]777;notify;%s;%s\007' for Ghostty
seq=$(printf '\033]9;%s\007' "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Depois adicione ao ~/.claude/settings.json no servidor:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify-ssh.sh" }
        ]
      }
    ]
  }
}

Rode chmod +x ~/.claude/hooks/notify-ssh.sh e instale o jq no servidor. A referência da Anthropic lista as sequências aceitas: OSC 9 (iTerm2, ConEmu, Windows Terminal, WezTerm), OSC 99 (Kitty), OSC 777 (urxvt, Ghostty, Warp) e um bell simples. O Claude Code só escreve a sequência em uma sessão interativa, enquanto a interface dele está na tela.

As limitações são inerentes. Se a conexão SSH cair, o notebook entrar em suspensão ou você fechar a aba, nada chega. Se você roda o Claude Code no tmux, adicione set -g allow-passthrough on ao ~/.tmux.conf no servidor; o guia do tmux cobre isso e as sessões desanexadas.

03Caminho 2: um push a partir do servidor

Um push não depende do seu terminal, então é a escolha certa para tarefas longas. O hook faz uma requisição HTTPS a partir do servidor, e um serviço a entrega no seu celular ou chat. O guia do ntfy e o guia de Telegram, Slack e Discord trazem hooks prontos. Eles avisam que algo aconteceu, mas não conseguem aprovar um comando nem responder a uma pergunta, então o Claude continua esperando você se reconectar.

04Caminho 3: Claude Code Notifier no servidor

O Claude Code Notifier é uma ferramenta independente (feita pela TouchTap, não pela Anthropic). Sua ferramenta de linha de comando gratuita, o ccn, roda em Mac, Windows e Linux, então você a instala no servidor, onde o Claude Code roda:

curl -fsSL https://claudecodenotifier.com/install.sh | sh

Ele adiciona suas entradas de hook ao ~/.claude/settings.json do servidor, mantém o restante e faz um backup. As notificações de desktop do ccn aparecem na máquina onde o ccn roda, o que, em um servidor headless, não serve para nada. O caminho útil é o celular: as notificações no celular passam pelo servidor de relay criptografado da TouchTap, e não pela sua conexão SSH, então funcionam a partir de qualquer máquina onde o ccn rode, desde que ela tenha acesso à internet.

Pareamento via SSH

O pareamento não precisa de navegador no servidor. Você pode rodar ccn pair na sua sessão SSH; ele exibe no terminal um QR code para você escanear com a câmera do celular e um link válido por 24 horas. Ou abra o app no celular, vá em Computers > Add a computer e rode a linha exibida, que instala e pareia de uma vez:

curl -fsSL https://claudecodenotifier.com/install.sh | sh -s 482913

(O código de seis dígitos é só um exemplo; use o que o seu app mostrar.) Um celular pode ter vários computadores, então um notebook e um servidor podem enviar notificações para ele. Veja o guia de pareamento para mais detalhes.

O que você pode fazer pelo celular

Depois de parear, você recebe um push quando o Claude termina, precisa de uma permissão ou faz uma pergunta. Você pode permitir uma vez, permitir para a sessão ou negar uma permissão, escolher uma resposta para a pergunta do Claude e enviar a próxima instrução quando o Claude terminar. Se você estiver longe, o terminal espera a resposta do celular, até um limite que você define, e para de esperar assim que você digita no teclado. Rode ccn doctor no servidor para verificar os hooks, as credenciais e a conexão com o relay. Veja os preços dos apps de celular; a ferramenta de linha de comando é gratuita.

05Mantenha o Claude Code rodando quando o SSH cair

As três opções exigem que o próprio Claude Code continue rodando. Se você inicia o claude direto no shell SSH e a conexão cai, a sessão cai junto. Rode-o dentro do tmux ou do GNU screen para que ele sobreviva a uma desconexão, e reconecte depois. Os hooks continuam disparando numa sessão desanexada, e é aí que um push no celular faz diferença. O guia do tmux e o guia sobre sair de perto durante tarefas longas explicam esse fluxo.

06Perguntas frequentes