ringly .
PT EN
v0.6.0 · now bilingual for real

Stop staring at the terminal.

Native Windows toasts when Claude finishes, asks for permission, or fails. Translated, project-aware, installed in two commands.

Windows 10/11 pt-BR · en-US MIT Open source
Get started View on GitHub
claude — Claude Code

$ claude

● Thinking...

Claude needs your attention

Waiting for you to confirm a permission · my-project

Claude Code now
The problem

You always end up watching the terminal.

You ask Claude to run something, switch tabs, forget. Five minutes later you remember. You come back — it's been waiting four minutes for you to confirm a permission. Those five minutes add up.

Silent terminal

Native toast fires

You respond in seconds

Features

What makes Ringly feel native.

i18n

First-class bilingual

192+ keys in full parity between pt-BR and en-US. Toast, TUI, CLI, doctor, update notes — everything respects the chosen language.

pt-BR

Claude terminou

Pronto pra próxima · meu-projeto

en-US

Claude finished

Ready for next · my-project

163 tests
0

Real coverage, running in ~600ms via Vitest.

0

Zero deps in the hook

Hot path is standalone. The plugin works even without the npm package.

Atomic writes

Every settings.json mutation writes to a temp file and atomically renames. No race conditions between the TUI and the hook.

Automatic AUMID

ringly init registers the Claude.Code.CLI AUMID and creates the Start Menu shortcut. Without it, Windows 10/11 silences the toast.

256kb

256KB stdin limit

Sanitized payloads, strings truncated at 500 chars, paths at 1024. Defense in depth.

hooks

5 events covered

Notification, Stop, StopFailure, SubagentStop, SessionStart. Each one has its own toggle and translation.

NotificationStopStopFailureSubagentStopSessionStart
slash command

Guided updates

/ringly-update shows a friendly summary of what changed (read from CHANGELOG) before asking for confirmation.

/ringly-update

Update Ringly from 0.5.2 to 0.6.0?

· Friendly CHANGELOG summary

· Messages in your language

MIT

Open source, atomic writes, 163 tests, zero dependencies on the hot path.

Read license
How it works

Five steps between Claude and your desktop.

No polling, no background daemon. Just Claude Code's official hooks, read by a 3kb zero-dep dispatcher.

  1. 01

    Claude emits an event

    Notification, Stop, StopFailure, SubagentStop, or SessionStart — any of the five official hooks.

  2. 02

    hooks.json runs dispatch.mjs

    The plugin registers the hooks and fires a ~3kb Node script with zero dependencies.

  3. 03

    Reads ~/.claude/settings.json

    Resolved at runtime: language, enabled events, sound, debug. No cache, no restart, always fresh.

  4. 04

    Tries 3 paths in order

    Node module ringly/hook → CLI binary on PATH → embedded PowerShell fallback. Silent failure, never breaks the session.

  5. 05

    Toast XML via registered AUMID

    ToastNotificationManager builds the XML and fires through the Claude.Code.CLI AUMID registered by ringly init.

Supported events

The five Claude Code hooks, translated.

Each event fires a toast with a different tone and urgency. Toggle them individually through ringly config.

Notification

Claude requested permission or input. Pops up when you need to intervene.

Claude needs your attention

Waiting for you to reply · my-project

Stop

Claude finished responding. Time to review.

Claude finished

Ready for your next instruction · my-project

StopFailure

An API error ended the session. Good to know right away.

Claude's session stopped

An API error ended the session · my-project

SubagentStop

A subagent finished. Off by default — turn on if you use them heavily.

Subagent finished

code-reviewer completed · my-project

SessionStart

Background update check, throttled to once a day.

Ringly 0.6.0 available

Run /ringly-update inside Claude Code to update.

i18n done right

No leaks. No typos. No afterthoughts.

Every TUI string, CLI message, doctor check, toast body, and guided-update line — all in pt-BR / en-US parity. Detected by system locale or set explicitly via ringly config.

Toast
pt-BR

Claude terminou

Pronto pra próxima instrução · meu-projeto

en-US

Claude finished

Ready for your next instruction · my-project

CLI
pt-BR

✓ Toast exibido com sucesso

9 passou · 0 avisos · 0 falhou

en-US

✓ Toast shown successfully

9 passed · 0 warnings · 0 failed

ringly config TUI
pt-BR

◉ Ringly · config · Eventos

↑ ↓ navegar · espaço alternar · enter salvar

en-US

◉ Ringly · config · Events

↑ ↓ navigate · space toggle · enter save

Under the hood

Built with the engineering you'd expect from a serious devtool.

163 tests
0 deps in the hook
<3kb dispatcher
24h update throttle
2 languages
5 hook events

Built with

TypeScript Node.js React Ink Vitest Biome tsup yargs npm Windows GitHub MIT
Installation

Two steps, both matter.

Windows 10/11 silences toasts from apps without a registered AUMID. That's why the npm step is required — it does the register. Skip it and you get a beep at best.

Step 1

Install the ringly CLI

1

Registers the Claude.Code.CLI AUMID on Windows, creates the Start Menu shortcut, writes the initial config, and prints the step 2 command for you to paste.

shell 
$ npm install -g ringly
$ ringly init
Step 2

Install the plugin inside Claude Code

2

Registers the Notification, Stop, StopFailure, SubagentStop, and SessionStart hooks. Uses the AUMID already registered in step 1.

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

Skipping either step is the only way the native toast won't show up. It's a Windows requirement, not a design choice.

Read the full documentation
FAQ

Frequently asked questions.

  • Does it work on macOS and Linux?

    v1.0 covers Windows 10/11. The macOS and Linux back-ends are scaffolded, translations are ready, but the native toasts are planned for the next release.

  • Do I really need both install steps?

    Yes. Windows requires a registered AUMID for ToastNotificationManager to display notifications in the Action Center. Only ringly init does that registration. Without it, the plugin at most plays a beep.

  • How do I change the language after installing?

    Run ringly config in your terminal. The TUI has arrow keys to navigate, space to toggle, and a visual language picker. Writes to settings.json with backup and atomic write.

  • Can I disable the automatic update check?

    Yes. Run ringly config and set check_updates to false. Or edit settings.json directly. The check is throttled to once per day anyway.

  • Why doesn't Ringly show up under /plugin → Configure?

    Design decision since v0.5.0. The Claude Code plugin manager schema doesn't support enums or Enter-toggle on booleans, which made the UX confusing. All config lives in ringly config, which is more robust.

  • Is it secure?

    Atomic writes, 0600 permissions on settings.json on Unix, payload sanitization (256KB stdin limit, 500 chars on strings), regex-validated AUMID. All MIT, open source, 163 tests.

  • How do I debug if something doesn't work?

    Run ringly doctor — 9+ environment checks. Set debug: true in settings.json for detailed logs. Logs rotate at 5MB.

  • How can I contribute?

    Open an issue or PR in the repository. CONTRIBUTING.md has the local setup, commit conventions, and how to run lint/typecheck/tests. Bilingual PRs welcome.
Let's go

Make Claude Code feel native.

Two commands, a clean TUI, and your desktop tells you instead of you constantly glancing at it.

Install now Star on GitHub