Notificações do Claude Code no Linux

01O que o Claude Code faz por conta própria

Quando o Claude termina uma tarefa ou espera uma permissão e parece que você não está por perto, o Claude Code dispara um evento de notificação. O guia de terminal da Anthropic diz que o Ghostty e o Kitty transformam isso em notificação de desktop; outros terminais, como o GNOME Terminal, o Konsole ou o terminal do VS Code, não mostram nada.

Em vez disso, você pode pedir um bell em qualquer terminal:

{
  "preferredNotifChannel": "terminal_bell"
}

O que o bell faz depende do terminal e do desktop. Ele pode apitar, piscar ou marcar a janela como urgente. O guia do terminal bell explica isso. Para uma notificação de verdade, use um hook.

02Instale o notify-send

Verifique se você já tem:

notify-send 'Claude Code' 'test'

Se o comando não for encontrado, instale:

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

Se o comando roda mas nada aparece, você não tem um daemon de notificações. GNOME, KDE Plasma, Cinnamon e Xfce já incluem um. Em um gerenciador de janelas tiling como Sway, i3 ou Hyprland, instale e inicie um você mesmo, por exemplo o mako ou o dunst. Funciona tanto no Wayland quanto no X11, porque o notify-send conversa com o daemon via D-Bus, não com o display.

03Um Notification hook

Este é o exemplo para Linux do guia de hooks da Anthropic. Adicione ao ~/.claude/settings.json, ao lado das chaves que você já tem:

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

Digite /hooks no Claude Code para vê-lo listado em Notification. O matcher vazio dispara para todo tipo de notificação. Os principais são permission_prompt, depois que uma aprovação espera cerca de seis segundos sem você digitar, e idle_prompt, cerca de 60 segundos depois que o Claude termina. O guia do Notification hook tem a lista completa.

04Saiba na hora em que o Claude terminar

O idle_prompt chega com um minuto de atraso. Já um hook Stop roda assim que o Claude encerra o turno. Ele não usa matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

O -a define o nome do app que o daemon exibe. Outras opções úteis: -u critical mantém a notificação na tela até você fechá-la, na maioria dos daemons, e -i dialog-information adiciona um ícone. Mais sobre esse evento no guia do Stop hook.

05Mostre a mensagem real, com som

Os hooks recebem JSON pela entrada padrão, e a entrada do Notification inclui um campo message. Um script pode exibir esse texto e tocar um som. Salve isto como ~/.claude/hooks/notify-linux.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

Torne o script executável com chmod +x ~/.claude/hooks/notify-linux.sh e use ~/.claude/hooks/notify-linux.sh como comando do hook. O jq está nos repositórios de todas as distribuições. O paplay funciona com o PulseAudio e com a camada PulseAudio do PipeWire, e o arquivo de som vem do tema de sons do freedesktop (sound-theme-freedesktop no Debian e no Ubuntu). Use qualquer .oga ou .wav que quiser.

06Sem notify-send? Use uma sequência de escape

Se o seu terminal entende sequências de escape de notificação, um hook pode pedir ao Claude Code que envie uma. Hooks não têm terminal próprio, então você retorna a sequência em um campo terminalSequence e o Claude Code a escreve. A referência da Anthropic lista OSC 777 para Ghostty, urxvt e Warp, e OSC 99 para Kitty. Por exemplo:

#!/bin/bash
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Isso não precisa de daemon na máquina onde o Claude Code roda, e é por isso que também é o truque para servidores remotos via SSH.

07Quando o notify-send funciona no shell mas não a partir do Claude Code

notify-send precisa do endereço da sessão D-Bus do seu login no desktop. Os hooks herdam o ambiente do Claude Code, então o Claude Code iniciado a partir de um terminal do desktop funciona sem problemas. Já o Claude Code iniciado via SSH, por um serviço do systemd, em um container ou dentro de um servidor tmux que foi iniciado pela primeira vez via SSH pode não ter esse endereço, e a notificação simplesmente se perde. Rode echo $DBUS_SESSION_BUS_ADDRESS no mesmo shell em que você inicia o claude; se o resultado estiver vazio, as notificações de desktop dessa sessão não vão aparecer. O guia do tmux e o guia de SSH explicam essas configurações.

08Onde o Claude Code Notifier se encaixa

Os hooks acima são uma boa escolha quando você está na frente da máquina. Mas não te alcançam quando você sai da mesa, e uma notificação de desktop não consegue responder ao Claude.

O Claude Code Notifier é uma ferramenta independente (feita pela TouchTap, não pela Anthropic) construída sobre os hooks do Claude Code. Sua ferramenta de linha de comando gratuita, o ccn, roda no Mac, no Windows e no Linux. No Linux:

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

ou npx @touchtap/ccn se você tiver Node.js. Ele adiciona suas entradas de hook ao ~/.claude/settings.json, mantém todo o resto e guarda um backup. A partir daí, mostra uma notificação de desktop no Linux quando o Claude termina, precisa de uma permissão ou faz uma pergunta. Essa parte não precisa de rede nem de celular. Ele roda por alguns milissegundos a cada evento; nada fica rodando em segundo plano.

Pareie um iPhone ou celular Android e os mesmos eventos chegam como push notifications, mesmo em uma máquina sem desktop nenhum. Pelo celular, você pode permitir ou negar uma permissão, escolher uma resposta para a pergunta do Claude e enviar a próxima instrução quando o Claude terminar. Veja como parear um celular, a página do ccn e os preços dos apps de celular. No Linux, o ccn guarda o token em um arquivo que só você pode ler.

Se você instalar o ccn, remova seus próprios hooks de notify-send para evitar duplicatas.

09Perguntas frequentes