claudeding

Why I built it

I kept losing time to the same dumb pattern. I'd hand Claude Code a long-running task — a refactor, a migration, a multi-step plan — and then catch myself five minutes later still staring at the terminal like a hawk. Or worse, switch to another tab, completely forget about it, and circle back twenty minutes later to find the agent had been waiting on me for input the whole time.

Both failure modes have the same root cause: Claude Code is silent. The terminal updates, but nothing about the rest of my machine reacts. So I built the smallest possible tool to fix it — a CLI that wires audio cues into Claude Code's hook system, so finishing a task actually makes a sound, and asking for input makes a different sound, and the whole loop becomes ambient instead of active.

It has genuinely changed how I work. I don't babysit long-running tasks anymore. I queue something up, switch to the next thing on my list, and the moment Claude needs me I get a quiet ding from across the room. No wasted glances, no tab checking, no “is it still going” anxiety. The productivity gain compounds — the more comfortable I get trusting the cues, the deeper I can context-switch.

How it works

Claudeding hooks into three points in Claude Code's lifecycle, each with its own sound so you can tell what happened without looking:

• Completion sound— fires on the Stop hook when Claude finishes a task. Soft, satisfying, doesn't demand attention.
• Feedback sound— fires on the Notification hook when Claude is waiting for your input. A touch sharper, the one you actually want to hear when you've walked away.
• Error sound— fires on the ToolFailure hook when something blows up mid-run. Low and short, more “oh no” than alarm.

Every ding is paired with a system notification showing which project it came from, so you can keep three or four Claude sessions running across different repos and instantly know which one wants you.

Smart silencing

The problem with naive notifications is that they're naive — they fire whether you're looking at the terminal or not. Claudeding ships with a small layer of intent detection so it only dings when a ding actually adds information:

• Focus detection — if your terminal window is already in focus, no sound plays. You can already see what happened.
• AFK override— if you've been idle for 30+ seconds (no keyboard or mouse), focus detection is bypassed and the ding fires anyway. Catches the case where the terminal is up on your screen but you're actually away.
• Debouncing— multiple parallel Claude sessions finishing within a tight window collapse to one sound. You don't get a tinny machine-gun of dings.
• System DND respect— opt-in integration with macOS Focus mode. If you've told the system to leave you alone, claudeding shuts up too.
• Quiet hours — set a window (e.g. 10pm–8am) where sounds are auto-muted. Notifications still fire if you want, just silently.

Setup

One-line install, one-line setup, you're done:

# install globally
npm install -g @byricky/claudeding
claudeding setup

# or one-shot via npx
npx @byricky/claudeding setup

claudeding setup installs the hooks into your Claude Code config, drops a default config file, and — the key trick — also adds a small instruction block to your ~/.claude/CLAUDE.md so Claude itself knows how to control claudeding when you ask. So when you type “mute the dings” or “test the ding” or “change the sound” in a Claude session, it knows the right command to run instead of asking you what to do.

Commands

claudeding setup        # install hooks + config + Claude instructions
claudeding status       # current state, which hooks are wired up
claudeding settings     # interactive settings menu
claudeding sounds       # browse and pick from built-in sound packs
claudeding play complete  # test a sound by name
claudeding mute --on    # mute everything
claudeding mute --off   # unmute
claudeding snooze 30m   # silence for the next 30 minutes
claudeding uninstall    # remove hooks and CLAUDE.md instructions

Other niceties

• Per-project sound packs — different repos can have different sounds, so you can tell which session is calling you across multiple terminals.
• Webhooks— fanout to Slack or Discord on completion or feedback events. For when the “walked away” surface is your phone, not your speakers.
• macOS menu-bar widget — quick toggle for mute, snooze, sound pack, and volume without dropping into the CLI.
• Volume control— 0–100, scoped to claudeding only, doesn't fight your system volume.
• Random message text— small touch, the system notification copy varies (“🎉 All done!” / “👋 Need your input!” / etc.) so it feels less robotic. Custom messages also supported.
• Usage stats (opt-in) — local-only counters that track how many tasks you completed, how often Claude had to wait on you, etc. Mostly for fun, occasionally illuminating.

What it changed

The honest version: I get more done in a day with claudeding installed. Not because Claude Code got faster — because the mental cost of running a long task dropped to roughly zero. Before, I'd either watch it (slow) or forget it (slower). After, I just queue it and move on, and the moment it needs me the room reminds me. The productivity unlock is in the confidence that I won't miss the moment.

It's also become my favorite small example of why ambient/eventful UX matters in agentic tools. The agent already does the work. The only piece humans need is a clean signal for “you again” — and once that signal is reliable, you stop leashing the thing.