Claude Code no tmux ou screen: receba notificações de uma sessão desanexada

01Anexado: deixe as notificações passarem pelo tmux

O tmux fica entre o Claude Code e o seu terminal e, por padrão, engole as escape sequences que o Claude Code usa para notificações de desktop. O guia de terminal da Anthropic traz este bloco para o ~/.tmux.conf:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Aplique no servidor em execução:

tmux source-file ~/.tmux.conf

O allow-passthrough deixa notificações e atualizações de progresso chegarem ao terminal externo. As outras linhas corrigem o Shift+Enter para quebras de linha. Com isso, os terminais que exibem as notificações do Claude Code fora do tmux (Ghostty, Kitty e iTerm2 com alertas ativados) passam a exibi-las dentro do tmux também.

O mesmo vale para hooks que retornam uma terminalSequence. A referência de hooks da Anthropic diz que o próprio Claude Code escreve essas sequências, o que funciona dentro do tmux e do GNU screen. Os guias de macOS, Linux e SSH têm exemplos.

02Anexado, mas em outra janela: use o bell

Se o Claude Code roda numa janela do tmux e você trabalha em outra, o bell é um sinal simples. Configure o Claude Code para sempre enviar um:

{
  "preferredNotifChannel": "terminal_bell"
}

Depois faça o tmux reagir a ele, no ~/.tmux.conf:

setw -g monitor-bell on
set -g bell-action other
set -g visual-bell off

O monitor-bell (ativado por padrão) sinaliza a janela que tocou o bell, e o tmux a marca com ! na barra de status. O bell-action other repassa ao seu terminal os bells das janelas que não são a que você está vendo, para que o terminal possa apitar ou pular. Use any para incluir também a janela atual. Definir visual-bell como on mostra uma mensagem no tmux em vez de repassar o bell.

03Mostre qual sessão precisa de você

Com várias sessões rodando, uma notificação que só diz "Claude precisa de você" não ajuda muito. O hook roda no ambiente do painel, então pode pedir ao tmux o nome da sessão e da janela. Este exemplo para Linux os exibe numa notificação de desktop:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
where=""
if [ -n "$TMUX_PANE" ]; then
  where=$(tmux display-message -p -t "$TMUX_PANE" '#S:#W')
fi
notify-send "Claude Code ${where}" "$msg"

Salve como ~/.claude/hooks/notify-tmux.sh, rode chmod +x nele e use-o como comando de um hook Notification ou Stop. #S é o nome da sessão e #W o nome da janela; nomeie suas sessões com tmux new -s api-refactor e a notificação diz para onde ir. Troque o notify-send pelo comando da sua plataforma, ou por um push. O guia de múltiplas sessões tem mais formas de diferenciar sessões.

04Desanexado: você precisa de um push

Desanexar é a graça do tmux: você inicia uma tarefa longa, desanexa e vai embora. O Claude Code continua trabalhando na sessão desanexada. Mas agora não há terminal para exibir uma escape sequence ou um bell, e se o servidor do tmux foi iniciado via SSH, um comando de notificação de desktop talvez também não tenha para onde ir.

Um hook que faz uma requisição de rede não se importa se alguém está anexado. Qualquer serviço de push funciona. O guia do ntfy e o guia de Telegram, Slack e Discord têm hooks prontos para colar. Eles avisam que algo aconteceu, mas não conseguem responder ao Claude, então um prompt de permissão continua esperando até você reanexar com tmux attach -t api-refactor.

05Onde o Claude Code Notifier se encaixa

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 em Mac, Windows e Linux. Como ela se conecta ao Claude Code e não ao terminal, funciona igual no tmux, no screen ou num shell comum, anexado ou desanexado:

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

Num computador desktop, ela mostra uma notificação de desktop quando o Claude termina, precisa de uma permissão ou faz uma pergunta. Pareie um celular e os mesmos eventos chegam como push pelo relay criptografado da TouchTap, de qualquer máquina onde o ccn rode, inclusive um servidor acessado via SSH.

O celular preenche a lacuna que uma sessão desanexada deixa. Quando aparece uma permissão, você pode permitir uma vez, permitir para a sessão ou negar pelo celular, e o Claude segue sem você precisar reanexar. Você pode escolher uma resposta quando o Claude faz uma pergunta e enviar a próxima instrução logo que o Claude termina. Se você digitou nos últimos 30 segundos, nada espera pelo celular e o terminal pergunta normalmente. Se você estiver longe, o terminal espera a resposta do celular até um limite que você define (hold_ceiling_seconds) e para de esperar assim que você toca no teclado.

Veja como parear um celular, como sair de perto durante tarefas longas e a página do ccn. Os apps de celular exigem assinatura ou compra vitalícia; veja os preços.

06GNU screen

O screen funciona de forma parecida com o tmux nesse caso. A referência de hooks da Anthropic diz que a saída terminalSequence dos hooks funciona dentro do screen, e o screen mostra uma mensagem quando uma janela que você não está vendo toca o bell. Sessões desanexadas do screen têm o mesmo problema do tmux desanexado: não há nada na tela, então use um push.

07Perguntas frequentes