Configuration

Starting in v0.5.0, Ringly is configured exclusively from the CLI. Claude Code’s /plugin → Installed → Ringly → Configure screen does not appear by design — read Why we don’t use the plugin manager for the rationale.

How to configure

Method	When to use
ringly config (recommended)	Slick TUI in your terminal: arrow keys to navigate, space to toggle, visual language picker. Writes to 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. 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.

Available settings

The keys below live in ~/.claude/settings.json under pluginConfigs.ringly.options. ringly config creates and 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.

Sample settings.json

{
  "pluginConfigs": {
    "ringly": {
      "options": {
        "language": "en-US",
        "events_notification": true,
        "events_stop": true,
        "events_stopFailure": true,
        "events_subagentStop": false,
        "sound": true,
        "debug": false,
        "check_updates": true
      }
    }
  }
}

Ringly preserves anything outside pluginConfigs.ringly — theme, hooks, configs from other plugins, etc. The merge is careful and atomic.

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, useful to force debug=true for a single shell without persisting anything. Since Anthropic no longer exports CLAUDE_PLUGIN_OPTION_* automatically (it dropped userConfig in v0.5.0), you need to set those env vars yourself if you want them.
3. Built-in defaults — final fallback.

Why we don’t use the 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 Claude Code’s official schema, not from our plugin:

• The language field was a free-text input. The official userConfig schema 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 stayed 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. 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.

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