Troubleshooting

Most issues are diagnosed in 30 seconds by running ringly doctor. Always start there.

Quick diagnosis

ringly doctor

This runs 9+ checks on your environment. Expected output:

✓ Node.js v22.14.0           (>= 20.0.0)
✓ Platform                   win32 x64
✓ PowerShell                 v5.1 detected
✓ AUMID registered           Claude.Code.CLI
✓ Claude Code settings       8 options set, en-US
✓ Plugin installed           ringly@0.6.0
✓ Hooks registered           5/5 active
✓ Start Menu shortcut        present
✓ Test fire                  toast displayed

9 passed · 0 warnings · 0 failed

Each failing check comes with a fix suggestion. If everything passes but the toast still doesn’t show up, read the blocks below.

Common issues

No toast at all

• Focus Assist or Do Not Disturb is on. Open Settings → System → Notifications and turn it off, or add Claude Code to the exceptions list.
• AUMID not registered. Run ringly init --force to re-create the shortcut and re-register.
• Volume muted or notification sound disabled. Check the notification sound toggle in Settings → System → Sound → Advanced.

Toast appears but looks wrong

• auto language detected wrongly. Run ringly config and pin it to pt-BR or en-US.
• Truncated text. Can happen when the project name is very long — Windows truncates by design. Consider renaming the project folder to something shorter.

Hook seems silent

• Enable debug. ringly config → set debug to true. Logs go to a file path printed at the end of ringly doctor.
• Check that the event is enabled. If you turned off events_stop for example, the Stop event never fires a toast.

spawn EINVAL when running ringly update --yes on Windows

Known Node ≥ 20.12 bug (CVE-2024-27980) that refuses to spawn .bat/.cmd directly. Fixed in v0.5.1. If you’re still on an older version:

npm install -g ringly@latest

Plugin installed, but hooks don’t fire

• Run /reload-plugins in Claude Code. Hooks load at session start, so changes require a reload.
• Check ~/.claude/settings.json and verify the hooks key was written correctly by Claude Code (should have all 5 Ringly events).
• As a last resort, uninstall and reinstall the plugin:

  /plugin uninstall ringly
  /plugin install ringly@ringly

/plugin → Configure screen doesn’t appear for Ringly

That’s intentional. Since v0.5.0 Ringly no longer uses the plugin manager’s userConfig due to known schema limitations (no enum support, Enter doesn’t toggle booleans, no atomic write). All config lives in ringly config. Read Why we don’t use the plugin manager.

Debug log

When debug: true, Ringly writes detailed logs to:

• Windows: %LOCALAPPDATA%\Ringly\ringly.log
• macOS: ~/Library/Logs/Ringly/ringly.log
• Linux: ~/.local/state/ringly/ringly.log

The log rotates automatically at 5 MB — the current file becomes ringly.log.1 and the new one starts fresh. The size check is throttled to once per minute to keep the hot path cheap.

Still not working?

Open an issue at github.com/nickdevcode/Ringly/issues with:

• full output from ringly doctor
• Windows version (winver)
• Node version (node --version)
• Claude Code version (claude --version)
• debug log content (if applicable)

The more context, the faster the resolution.