Agent-Skills.md

Agent Skills: Agent Sounds

Add audible notifications (chimes) to Claude Code and other coding agents. Provides a small script that plays configurable sounds on common lifecycle hooks like plan completion, task completion, errors, and long-running command completion. Defaults work out of the box on macOS (system sounds) with cross-platform fallbacks.

UncategorizedID: foogunlana/skills/agent-sounds

Repository

foogunlana/skills
foogunlana
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/foogunlana/skills/tree/HEAD/.claude/skills/agent-sounds

Skill Files

Browse the full folder contents for agent-sounds.

Download Skill

Loading file tree…

.claude/skills/agent-sounds/SKILL.md

Skill Metadata

Name
agent-sounds
Description
Add audible notifications (chimes) to Claude Code and other coding agents. Provides a small script that plays configurable sounds on common lifecycle hooks like plan completion, task completion, errors, and long-running command completion. Defaults work out of the box on macOS (system sounds) with cross-platform fallbacks.

Agent Sounds

This skill adds audible cues (like an "oven ding") to agent workflows by running a tiny local script that plays a configured sound for a given hook event.

Quick Start

  1. Generate a default config (optional):
python3 .claude/skills/agent-sounds/scripts/agent_sounds.py init
  1. When a hook happens, run:
python3 .claude/skills/agent-sounds/scripts/agent_sounds.py emit plan.done

If no config exists, defaults are used (macOS system sounds when available, otherwise terminal bell).

Hooks (Recommended Defaults)

Use these hook names consistently so different agents and workflows can share the same config:

  • plan.done - when the final plan is complete (your "oven ding")
  • task.done - when a user-visible task is completed
  • run.done - when a long-running command finishes
  • error - when the agent hits an error or needs attention
  • waiting - when the agent is blocked waiting for user input

Default Behavior In This Skill

When this skill is active, follow these rules:

  1. After producing a plan (a numbered plan or clearly labeled "Plan"), immediately emit plan.done.
  2. After implementing a user request and finishing verification (tests/lint/build), emit task.done.
  3. After running a command that took noticeable time, emit run.done.
  4. If an error occurs (failed command, exception, missing dependency), emit error after you present the next action to the user.
  5. If you ask the user a question and must wait, emit waiting right after the question.

Onboarding Flow (First Use)

If .claude/agent-sounds.json does not exist:

  1. Create it with a sensible default mapping (see references/config-guide.md).
  2. Offer the user a short customization pass:
    • Choose the "ding" sound for plan.done
    • Choose whether error should be louder/different
    • Enable/disable any hooks they find noisy

Configuration

Config lives at .claude/agent-sounds.json.

  • Schema, defaults, and examples: references/config-guide.md
  • How to integrate with other agent frameworks: references/integrations.md