Ringly

Notificações nativas cross-platform para o Claude Code, com tradução pt-BR / en-US.

Native cross-platform notifications for Claude Code, with pt-BR / en-US translation.

---

Português 🇧🇷

O Ringly liga os hooks do Claude Code (Notification, Stop, StopFailure, SubagentStop) a notificações nativas do sistema operacional, com mensagens traduzidas e contextualizadas pelo nome do projeto. Você nunca mais precisa ficar olhando o terminal pra saber o que o Claude está esperando de você.

O projeto é distribuído em duas camadas complementares e obrigatórias, nesta ordem:

1. Pacote npm ringly (passo 1) — registra o AUMID do Windows (sem ele, o Windows 10/11 silencia o toast nativo), instala o atalho no Menu Iniciar, escreve a configuração inicial e fornece os utilitários ringly doctor / ringly config / ringly uninstall.
2. Plugin do Claude Code (passo 2) — registra os hooks (Notification, Stop, StopFailure, SubagentStop) e roda o dispatcher que delega ao módulo Node do ringly e, por fim, monta e dispara o toast usando o AUMID já registrado no passo 1.

⚠️ Os dois passos são obrigatórios. O plugin sozinho até roda o dispatcher, mas no Windows 10/11 o ToastNotificationManager exige um AUMID registrado para exibir notificações na Central de Ações — esse registro é feito apenas pelo ringly init. Sem ele, você ouve no máximo um beep de fallback (ou nada).

Status

O Ringly está em desenvolvimento ativo. Windows 10 e 11 são os sistemas suportados na v1.0. macOS e Linux têm os back-ends estruturados e estão planejados para a próxima versão.

Recurso	Windows 10/11	macOS	Linux
Toast nativo	✓	⏳	⏳
Som de fallback	✓	⏳	⏳
Registro AUMID	✓	—	—
Notificações em pt-BR/en-US	✓	✓	✓
TUI e CLI em pt-BR/en-US	✓	✓	✓

Instalação

A instalação é feita em dois passos. Pule um e o toast nativo não vai aparecer no Windows 10/11 — não é uma escolha, é uma exigência do próprio sistema operacional (veja a nota acima sobre o AUMID).

Passo 1 — Instalar a CLI ringly (registra o AUMID)

npm install -g ringly
ringly init

O instalador interativo:

• registra o AUMID Claude.Code.CLI no Windows (obrigatório para que o ToastNotificationManager autorize o toast),
• cria o atalho no Menu Iniciar amarrado a esse AUMID,
• salva a configuração no ~/.claude/settings.json (com backup automático),
• imprime o comando exato do passo 2 pra você colar no Claude Code.

Passo 2 — Instalar o plugin no Claude Code (registra os hooks)

Dentro do Claude Code:

/plugin marketplace add nickdevcode/Ringly
/plugin install ringly@ringly

O plugin registra os hooks (Notification, Stop, StopFailure, SubagentStop) e o dispatcher embutido passa a usar o AUMID já registrado no passo 1. A partir daí, configure idioma, eventos, som e debug pelo ringly config (TUI) ou editando ~/.claude/settings.json direto — a partir da v0.5.0 o Ringly não expõe mais uma tela no gerenciador de plugins do Claude Code (veja a seção Configuração para o porquê).

Atualizando

A partir da v0.4.0, o próprio Ringly te avisa quando tem uma versão nova:

1. Aviso automático. Uma vez por dia, no início da sessão do Claude Code, o plugin checa o npm em background. Se tiver versão nova, dispara uma toast nativa do tipo "Ringly 0.5.0 disponível — rode /ringly-update no Claude Code". É a mesma toast que você já conhece, só vinda do próprio plugin.

2. Atualização guiada via slash command. Dentro do Claude Code, rode:

   /ringly-update
   

   O comando consulta o npm, mostra a diferença entre a versão instalada e a mais recente, pede confirmação e roda npm install -g ringly@latest por você. No final, ele lembra de rodar /reload-plugins para a sessão ativa carregar a nova versão (ou fechar e reabrir o Claude Code se houver lock de arquivos no Windows).

Atualização manual

Se preferir fazer na mão (ou estiver fora do Claude Code):

npm install -g ringly@latest

Verifique a versão instalada com ringly --version ou ringly update --check (esse último imprime um JSON com current, latest, hasUpdate, reachable — útil em scripts e CI). O plugin do Claude Code atualiza automaticamente quando uma nova versão é publicada no marketplace; force com /plugin marketplace update dentro do Claude Code se quiser puxar manualmente.

Desativando a checagem automática

A checagem é throttled a uma request por dia, não envia nada além da consulta pública ao npm e respeita o opt-out. Pra desligar, marque check_updates: false rodando ringly config ou editando ~/.claude/settings.json direto.

Configuração

A partir da v0.5.0, o Ringly é configurado exclusivamente pela CLI. O plugin.json não declara mais um userConfig, então a tela /plugin → Installed → Ringly → Configure do Claude Code não aparece de propósito. Mais sobre o porquê logo abaixo.

Por que não usar o gerenciador de plugins do Claude Code

Até a v0.4.x o Ringly aparecia no /plugin manager nativo. Na prática a UX era ruim e cheia de armadilhas que vinham do próprio gerenciador, não do nosso plugin:

• O campo language era um input de texto livre. O schema oficial do userConfig (documentado pela Anthropic em code.claude.com) só permite string/number/boolean/directory/file — não tem suporte a enum. Resultado: o usuário precisava digitar pt-BR ou en-US letra por letra (com hífen), e um typo virava auto silenciosamente.
• Enter em booleano não toggle. No plugin manager, Enter apenas confirma a navegação entre campos. Pra alternar um boolean você precisava lembrar de apertar Space. Várias pessoas reportaram "marquei a opção mas continuou ligada".
• Sem validação visual, sem confirmação atômica. O plugin manager grava direto em ~/.claude/settings.json sem backup explícito e sem aviso de /reload-plugins.

Nada disso é culpa do Claude Code — o userConfig é um schema genérico e funciona bem pra plugins simples (uma URL, um token). Pro caso do Ringly (idioma com enum, 7 toggles, contexto de "isso vai disparar notificações no seu SO"), o custo da UX ruim era maior do que o ganho de ter uma tela nativa.

A solução técnica seria pedir pra Anthropic adicionar enum e Enter-toggle no schema. Enquanto isso não acontece, optamos por remover o userConfig completamente em vez de fingir que a UX é boa.

Como configurar (única forma oficial)

Forma	Quando usar
ringly config — TUI bonita no terminal (✨ recomendado)	Melhor experiência: setas pra navegar, espaço pra toggle, seletor visual de idioma. Escreve no settings.json por você (atomic + backup com timestamp) e lembra de rodar /reload-plugins ao final.
Editar settings.json manualmente	Para automação/CI. As chaves ficam em pluginConfigs.ringly.options (veja Opções disponíveis). Sempre rode /reload-plugins depois.
ringly init	Roda o instalador interativo de novo (com banner, registro de AUMID, setup completo). Use quando estiver reinstalando ou se o settings.json foi apagado.

Se você procurar pelo Ringly em /plugin → Installed, o plugin aparece lá (ele está instalado — os hooks estão registrados), mas o item Configure simplesmente não existe pro Ringly. Isso é proposital, não bug.

Como o Ringly resolve a configuração em runtime

O dispatcher dos hooks lê, nesta ordem de prioridade:

1. ~/.claude/settings.json → pluginConfigs.ringly.options — fonte única em estado estável. O Ringly lê esse arquivo diretamente no início de cada hook, então qualquer mudança feita por ringly config é aplicada imediatamente, sem precisar de restart.
2. Variáveis de ambiente RINGLY_DEBUG=1 e CLAUDE_PLUGIN_OPTION_* — overrides voláteis. As CLAUDE_PLUGIN_OPTION_* continuam sendo lidas como override opcional (útil pra forçar debug=true por uma única sessão sem persistir nada), mas o Claude Code não exporta mais nada automaticamente já que o userConfig foi removido. Você precisa setar essas variáveis manualmente no seu shell se quiser usar.
3. Defaults internos — última camada.

Opções disponíveis

As chaves abaixo ficam em pluginConfigs.ringly.options dentro de ~/.claude/settings.json. O ringly config cria/edita todas elas pra você.

Chave	Tipo	Padrão	Descrição
language	auto / pt-BR / en-US	auto	auto detecta pelo locale do sistema.
events_notification	boolean	true	Notifica quando o Claude pede permissão ou input.
events_stop	boolean	true	Notifica quando o Claude termina uma resposta.
events_stopFailure	boolean	true	Notifica quando um erro de API encerra a sessão.
events_subagentStop	boolean	false	Notifica quando um subagent termina.
sound	boolean	true	Toca som junto da notificação.
debug	boolean	false	Escreve logs detalhados.
check_updates	boolean	true	Checa o npm 1x/dia no SessionStart e avisa via toast quando tem versão nova.

Comandos da CLI

ringly help                    # lista os comandos no idioma configurado
ringly init                    # instalador interativo (TUI)
ringly init --non-interactive  # aplica defaults, sem TUI
ringly config                  # reconfigura interativamente
ringly doctor                  # diagnóstico do ambiente local
ringly test --event Stop --lang pt-BR
ringly update                  # checa o npm e roda a atualização guiada
ringly update --check          # imprime JSON {current, latest, hasUpdate, reachable, language, notes}
ringly update --yes            # pula a confirmação e instala direto
ringly uninstall               # remove AUMID, atalho e configurações do Ringly

Dentro do Claude Code, dois slash commands cobrem o dia a dia:

• /ringly-update — espelha ringly update, com confirmação visual via AskUserQuestion, resumo amigável do que mudou na nova versão (lido do CHANGELOG.md empacotado) e instrução automática pra rodar /reload-plugins no final. Tudo aparece no idioma configurado.
• /ringly-help — roda ringly help e mostra a lista de comandos direto no chat (com aviso de que esses comandos rodam no seu terminal externo, não dentro do Claude Code).

Como funciona

1. O Claude Code emite um evento de hook (SessionStart, Notification, Stop, StopFailure, SubagentStop).
2. O hooks.json do plugin executa node ${CLAUDE_PLUGIN_ROOT}/hooks/dispatch.mjs <Event>.
3. O dispatch.mjs lê o ~/.claude/settings.json e checa as opções do Ringly. Se o evento estiver desabilitado pelo usuário (events_* ou check_updates), o dispatcher encerra silenciosamente — sem disparar nada. O SessionStart é tratado como um caminho separado: em vez de virar toast direto, ele dispara uma checagem de versão (throttled a 24h) que só vira toast se o npm tiver versão nova.
4. Caso o evento esteja habilitado, o dispatcher lê o payload JSON via stdin e tenta, nessa ordem:
   • o módulo Node ringly/hook — caminho normal quando a CLI foi instalada (passo 1 da instalação). Traz a tradução mais rica e contexto de projeto.
   • o binário ringly no PATH — usado quando o módulo não é resolvido pelo require mas a CLI existe globalmente.
   • um fallback embutido em PowerShell + WinRT — último recurso, só dispara se os dois anteriores falharem. Como o AUMID Claude.Code.CLI precisa estar registrado pelo ringly init, esse fallback não substitui o passo 1: sem CLI, ele toca no máximo um beep e sai.
5. No Windows, o toast é gerado como XML e exibido via o AUMID registrado Claude.Code.CLI. Um beep é tocado como fallback se o Modo Foco ou Não Perturbe estiverem bloqueando as notificações.

Solução de problemas

• Não aparece toast: confira Modo Foco ou Não Perturbe no Windows. Rode ringly doctor para inspecionar o registro AUMID e as permissões.
• AUMID ausente: rode ringly init --force para recriar o atalho do Menu Iniciar e re-registrar o ID da aplicação.
• Hook parece silencioso: ative debug: true na config do plugin e verifique o log mostrado no fim do ringly doctor.

Contribuindo

Issues e pull requests são bem-vindos. Leia o CONTRIBUTING.md antes de abrir uma PR — ele tem o setup local, padrões de commit e como rodar os checks.

Histórico de versões: CHANGELOG.md.

Repositório: github.com/nickdevcode/Ringly.

---

English 🇺🇸

Ringly wires up the Claude Code hook system (Notification, Stop, StopFailure, SubagentStop) to native operating-system notifications, with translated, project-aware messages so you always know what Claude needs from you without staring at your terminal.

It is distributed as two complementary layers, both required, in this order:

1. ringly npm package (step 1) — registers the Windows AUMID (without it Windows 10/11 silently drops the native toast), installs the Start Menu shortcut, writes the initial configuration, and ships the ringly doctor / ringly config / ringly uninstall utilities.
2. Claude Code plugin (step 2) — registers the hooks (Notification, Stop, StopFailure, SubagentStop) and runs the dispatcher that delegates to the ringly Node module and ultimately builds and shows the toast using the AUMID already registered in step 1.

⚠️ Both steps are required. The plugin alone runs the dispatcher, but on Windows 10/11 ToastNotificationManager only displays notifications from apps with a registered AUMID — and that registration is performed exclusively by ringly init. Skip it and you'll get a fallback beep at best, nothing at worst.

Status

Ringly is in active development. Windows 10 and 11 are the supported targets for v1.0. macOS and Linux toast back-ends are scaffolded and planned for the next release.

Surface	Windows 10/11	macOS	Linux
Native toast	✓	⏳	⏳
Sound fallback	✓	⏳	⏳
AUMID register	✓	—	—
Notifications in pt-BR/en-US	✓	✓	✓
TUI & CLI in pt-BR/en-US	✓	✓	✓

Installation

Installation is a two-step process. Skip either one and native toasts won't show up on Windows 10/11 — this isn't a choice, it's an OS-level requirement (see the note above about the AUMID).

Step 1 — Install the ringly CLI (registers the AUMID)

npm install -g ringly
ringly init

The interactive installer:

• registers the Claude.Code.CLI AUMID on Windows (required for ToastNotificationManager to authorize the toast),
• creates a Start Menu shortcut bound to that AUMID,
• writes the configuration to ~/.claude/settings.json (with an automatic backup),
• prints the exact step 2 command to paste into Claude Code.

Step 2 — Install the plugin inside Claude Code (registers the hooks)

Inside Claude Code:

/plugin marketplace add nickdevcode/Ringly
/plugin install ringly@ringly

The plugin registers the hooks (Notification, Stop, StopFailure, SubagentStop) and the embedded dispatcher uses the AUMID registered in step 1. From here, tweak language, events, sound, and debug via ringly config (TUI) or by editing ~/.claude/settings.json directly — starting with v0.5.0 the plugin no longer exposes a Claude Code plugin-manager screen (see the Configuration section for why).

Updating

Starting in v0.4.0, Ringly tells you when there's a new version available:

1. Automatic notice. Once a day, at the start of a Claude Code session, the plugin checks npm in the background. If a newer version is out, it fires the same native toast you already know — "Ringly 0.5.0 available — run /ringly-update inside Claude Code".

2. Guided update via slash command. Inside Claude Code, run:

   /ringly-update
   

   The command queries npm, shows the diff between the installed and the latest version, asks for confirmation, and runs npm install -g ringly@latest for you. At the end it reminds you to run /reload-plugins so the active session picks up the new version (or close and reopen Claude Code if Windows holds the files locked).

Manual update

If you'd rather do it by hand (or you're outside Claude Code):

npm install -g ringly@latest

Check the installed version with ringly --version or ringly update --check (the latter prints a JSON snapshot with current, latest, hasUpdate, reachable — handy for scripts and CI). The Claude Code plugin updates automatically when a new version lands in the marketplace; force a manual refresh with /plugin marketplace update if you want it now.

Disabling the automatic check

The check is throttled to one request per day, only hits the public npm registry, and respects opt-out. To disable it, set check_updates: false by running ringly config or editing ~/.claude/settings.json directly.

Configuration

As of v0.5.0, Ringly is configured exclusively from the CLI. The plugin.json no longer declares a userConfig block, so Claude Code's /plugin → Installed → Ringly → Configure screen does not appear by design. Read on for why.

Why we don't use Claude Code's plugin manager

Up to v0.4.x Ringly showed up in /plugin's native configuration UI. In practice the UX was full of footguns that came from the manager itself, not from our plugin:

• The language field was a free-text input. The official userConfig schema (documented by Anthropic at code.claude.com) only supports string / number / boolean / directory / file — no enum support. Users had to type pt-BR or en-US letter-by-letter (with the dash) and a typo silently fell back to auto.
• Enter on a boolean does not toggle it. Inside the plugin manager, Enter only confirms field navigation — you had to remember to press Space to flip a boolean. Plenty of folks reported "I unchecked it and it was still on".
• No visual validation, no atomic-write confirmation. The plugin manager writes directly to ~/.claude/settings.json with no explicit backup and no reminder to run /reload-plugins.

None of this is the Claude Code team's fault — userConfig is a deliberately minimal schema that fits simple plugins (one URL, one token). For Ringly's shape (enum language, seven toggles, "this fires OS notifications" context) the bad UX outweighed the upside of a native screen.

The technical fix would be to ask Anthropic to add enum and Enter-toggle to the schema. Until that lands, we chose to drop userConfig entirely rather than pretend the experience is fine.

How to configure (the only supported flow)

Method	When to use
ringly config — slick TUI in your terminal (✨ recommended)	Best experience: arrow keys to navigate, space to toggle, visual language picker. Writes into settings.json for you (atomic + timestamped backup) and reminds you to run /reload-plugins at the end.
Edit settings.json directly	Best for automation/CI. Keys live under pluginConfigs.ringly.options (see Available settings). Always run /reload-plugins after.
ringly init	Re-run the interactive installer (banner, AUMID register, full setup). Use it when reinstalling or if settings.json was wiped.

If you search for Ringly under /plugin → Installed, the plugin shows up there (it is installed — hooks are registered), but the Configure entry simply does not exist for Ringly. That's intentional, not a bug.

How Ringly resolves the config at runtime

The hook dispatcher reads, in this priority order:

1. ~/.claude/settings.json → pluginConfigs.ringly.options — the only persistent source. Ringly reads this file directly at the start of every hook, so changes made by ringly config apply immediately, with no restart required.
2. Environment variables RINGLY_DEBUG=1 and CLAUDE_PLUGIN_OPTION_* — volatile overrides. CLAUDE_PLUGIN_OPTION_* is still honoured as an optional override (useful to force debug=true for a single shell without persisting anything), but Claude Code no longer exports anything on its own now that userConfig is gone. You have to set these env vars yourself if you want them.
3. Built-in defaults — final fallback.

Available settings

The keys below live in pluginConfigs.ringly.options inside ~/.claude/settings.json. ringly config creates/edits all of them for you.

Key	Type	Default	Description
language	auto / pt-BR / en-US	auto	Auto-detects from system locale when set to auto.
events_notification	boolean	true	Notify when Claude requests permission or input.
events_stop	boolean	true	Notify when Claude finishes a response.
events_stopFailure	boolean	true	Notify when an API error ends the session.
events_subagentStop	boolean	false	Notify when a subagent finishes.
sound	boolean	true	Play a sound with each notification.
debug	boolean	false	Write detailed logs.
check_updates	boolean	true	Check npm once a day at session start and notify via toast when a new version ships.

CLI commands

ringly help                    # list the commands in the configured language
ringly init                    # interactive installer (TUI)
ringly init --non-interactive  # apply defaults, skip the TUI
ringly config                  # reconfigure interactively
ringly doctor                  # run a diagnostic of the local setup
ringly test --event Stop --lang pt-BR
ringly update                  # check npm and run the guided update
ringly update --check          # print {current, latest, hasUpdate, reachable, language, notes} JSON
ringly update --yes            # skip the prompt and install directly
ringly uninstall               # remove AUMID, shortcut, and Ringly settings

Inside Claude Code, two slash commands cover the everyday flow:

• /ringly-update — mirrors ringly update, with visual confirmation via AskUserQuestion, a friendly summary of what changed in the new version (read from the packaged CHANGELOG.md), and an automatic prompt to run /reload-plugins at the end. Everything shows up in the configured language.
• /ringly-help — runs ringly help and shows the command list straight in the chat (with a warning that these commands must run in your external terminal, not inside Claude Code).

How it works

1. Claude Code emits a hook event (SessionStart, Notification, Stop, StopFailure, SubagentStop).
2. The plugin's hooks.json runs node ${CLAUDE_PLUGIN_ROOT}/hooks/dispatch.mjs <Event>.
3. dispatch.mjs reads ~/.claude/settings.json and checks your Ringly options. If the event is disabled (events_* or check_updates), the dispatcher exits silently — nothing is fired. SessionStart follows its own path: instead of becoming a toast directly, it triggers an npm version check (throttled to 24h) that only turns into a toast when a newer release is found.
4. If the event is enabled, the dispatcher reads the JSON payload from stdin and tries, in order:
   • the ringly/hook Node module — the normal path once the CLI has been installed (step 1 of the installation). Ships the richest translations and project-aware context.
   • the ringly CLI binary on PATH — used when require can't resolve the module but the CLI is installed globally.
   • an embedded PowerShell + WinRT fallback — last resort, only fires if the two above failed. Because the Claude.Code.CLI AUMID has to be registered by ringly init, this fallback does not replace step 1: without the CLI it plays a beep at best and exits.
5. On Windows, the toast is generated as XML and shown via the registered AUMID Claude.Code.CLI. A beep is played as a fallback if Focus Assist or Do Not Disturb is blocking notifications.

Troubleshooting

• No toast appears: check Focus Assist or Do Not Disturb on Windows. Run ringly doctor to inspect AUMID registration and notification permissions.
• AUMID missing: re-run ringly init --force to recreate the Start Menu shortcut and re-register the application ID.
• Hook seems silent: enable debug mode (debug: true in the plugin config) and check the log file path printed by ringly doctor.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md before opening a PR — it covers local setup, commit conventions, and how to run the checks.

Release history: CHANGELOG.md.

Repository: github.com/nickdevcode/Ringly.

---

License

MIT