Como criei um sistema de notificações integrado ao Claude Code no macOS

Automação, produtividade e fluxo de trabalho unificado entre terminal, macOS e iCloud.

Nos últimos meses, tenho aprimorado meu fluxo de desenvolvimento usando ferramentas de IA locais, especialmente o Claude Code. Ele se tornou essencial para acelerar tarefas repetitivas, gerar código, auditar scripts e automatizar partes do meu workflow.

Mas havia um problema: eu não queria ficar preso ao terminal esperando o Claude terminar alguma tarefa — fosse uma refatoração grande, um build complexo ou uma operação mais demorada. Eu precisava de uma forma simples, rápida e elegante de receber notificações instantâneas diretamente na Central de Notificações do macOS, sincronizadas com meu iPhone, iPad e Apple Watch via iCloud.

Então decidi criar um sistema próprio:

Um script shell inteligente que envia notificações avançadas, com tipos, sons, logs, aliases poderosos e integração total com o Claude Code.

Este post conta exatamente como construí isso, por que funciona tão bem e como você pode adaptar para seu próprio setup.

---

Por que criar um sistema de notificações?

Enquanto trabalhava com Claude Code, várias situações aconteciam rotineiramente:

• Pedir ao Claude para refatorar centenas de linhas e depois esquecer de voltar.
• Realizar builds pesados (React, Next, Vite) sem nenhum aviso visual de conclusão.
• Rodar testes longos e precisar esperar olhando para o terminal.
• Executar automações via scripts sem feedback algum.

Eu queria algo que:

• Fosse rápido.
• Não dependesse de aplicativos externos.
• Funcionasse com qualquer comando.
• Integrasse com CI/CD, Git, npm, Claude CLI, cron, zsh e VSCode.
• Enviasse notificações persistentes (com título, subtítulo, som e contexto).
• Registrasse logs para auditoria posterior.

O macOS já tinha a base perfeita: AppleScript + Notification Center. O que faltava era construir a camada de automação.

---

Como o sistema funciona tecnicamente

O script principal (notifications_claude_code.sh) executa três funções fundamentais:

1. Recebe argumentos e flags (tipo, título, som, subtítulo, modo silencioso, log etc).
2. Gera e executa AppleScript usando osascript, exibindo a notificação.
3. Cria aliases no .zshrc, permitindo comandos curtos e intuitivos.

Além disso, implementei:

• 5 tipos de notificação (info, success, warning, error, important).
• Sons personalizados.
• Logs persistentes em ~/.claude_notifications.log.
• Alias avançados como cn-build-ok, cn-tests-fail, cn-important.
• Integração natural com:
  • npm
  • git
  • gh (GitHub CLI)
  • claude (Claude CLI)
  • Scripts bash
  • cron jobs
  • CI/CD local/remoto

Tudo usando apenas bash e osascript.

---

Principais recursos criados

1. Comando universal

O comando principal aceita opções e uma mensagem.

claude-notify [OPÇÕES] <mensagem>

Com o alias curto, fica ainda mais simples:

cn "Sua mensagem aqui"

2. Tipos de notificação

• info
• success
• warning
• error
• important

Cada tipo gera um estilo visual diferente no macOS, ajudando a identificar a natureza da notificação rapidamente.

3. Títulos, subtítulos, sons e logs

É possível customizar cada notificação com detalhes.

Exemplo:

cn -t "Build" -s "v2.0.0" -T success -l "Finalizado com sucesso"

4. Aliases inteligentes

Foram criados aliases para os tipos de notificação:

• cn-success <msg>
• cn-error <msg>
• cn-warning <msg>
• cn-info <msg>
• cn-important <msg>

E também atalhos para cenários comuns de desenvolvimento:

• cn-build-ok
• cn-build-fail
• cn-tests-ok
• cn-tests-fail
• cn-deploy-ok
• cn-task-done

5. Integração com Claude Code

Execute um comando do Claude e receba uma notificação ao final.

claude "Corrija o arquivo auth.js" && cn-task-done

---

Como implementei o script

A lógica central do script é baseada em:

• getopts: Para capturar flags e argumentos de forma robusta.
• Montagem dinâmica: O comando AppleScript é construído dinamicamente com base nos parâmetros fornecidos.
• Execução segura: O osascript é usado para exibir a notificação de forma nativa.

osascript -e 'display notification "Mensagem" with title "Título"'

• Logs formatados: Um registro de cada notificação é salvo para histórico e auditoria.

[2025-11-16 14:30:45] [SUCCESS] Title: Claude Code | Subtitle: | Message: Build completed

---

Exemplos reais de uso

Build com notificação automática

npm run build && cn-build-ok || cn-build-fail

Testes

npm test && cn-tests-ok || cn-tests-fail

Commits e push

git push origin main && cn -t "Git" -T success "Código enviado para o repositório"

Claude Code

claude "Gerar documentação para o projeto" && cn-success "Documentação gerada pelo Claude"

Scripts em background

./meu_job_demorado.sh && cn -q -l "Processo em background concluído"

---

Configuração no macOS

Para que as notificações funcionem, ative-as para os seguintes aplicativos nas Configurações do Sistema:

• Terminal
• iTerm2 (ou seu emulador de terminal preferido)
• VSCode (se executar tarefas a partir do terminal integrado)

As notificações são sincronizadas automaticamente com seus dispositivos via iCloud:

• iPhone
• iPad
• Apple Watch

Nenhum software extra é necessário.

---

Logs persistentes

O arquivo de log é salvo em:

~/.claude_notifications.log

Para ver as últimas entradas, use o comando tail:

tail -20 ~/.claude_notifications.log

---

Como instalar no seu sistema

1. Tornar o script executável:

   chmod +x notifications_claude_code.sh
   

2. Adicionar os aliases ao seu .zshrc (ou .bashrc) e recarregar o shell:

   source ~/.zshrc
   

3. Testar a instalação:

   cn "Olá, mundo! O sistema de notificações está funcionando."
   

---

Boas práticas utilizadas

• Mensagens curtas e claras: Para que a notificação seja objetiva.
• Uso de títulos relevantes: Facilita a identificação da origem da notificação.
• Notificações silenciosas (-q): Ideal para automações que não precisam de som.
• Encadeamento com && e ||: Para notificar sucesso ou falha de um comando.
• Logging para tarefas críticas: Garante que há um registro do que aconteceu.
• Evitar spam: Cuidado para não gerar notificações excessivas em loops.

---

Por que isso aumentou tanto minha produtividade?

Esse sistema resolveu um dos maiores gargalos ao trabalhar com IA local: a espera ociosa.

Não preciso mais ficar olhando para o terminal. Meu fluxo de trabalho agora é:

1. Peço ao Claude Code (ou a qualquer outro processo) para executar uma tarefa.
2. Continuo trabalhando em outra coisa.
3. Recebo a notificação no Mac, iPhone ou Apple Watch quando a tarefa é finalizada.

Resultados:

• Menos tempo perdido.
• Menos ansiedade de ficar verificando o terminal.
• Mais foco e concentração.
• Automação elegante e silenciosa.
• Histórico completo de atividades via logs.

É uma automação pequena, mas que muda completamente o ritmo de trabalho.

---

Conclusão

Criar esse sistema de notificações com Shell Script e AppleScript transformou meu fluxo de desenvolvimento no macOS. A integração com o Claude Code e outras ferramentas de linha de comando ficou simples, elegante e, acima de tudo, extremamente útil.

Se você é um desenvolvedor que usa o terminal para automações ou tarefas longas, recomendo fortemente implementar uma solução parecida. A produtividade ganha é imensa.