Zero dependencies

Hear your agent think.

Procedural audio feedback for Claude Code. Every tool call, file edit, search, and git push gets a distinct sound — synthesized from math, not audio files.

Get started Read the Handbook

Install

npm install -g claude-sfx

Init

claude-sfx init

Demo

claude-sfx demo

Why Audio Feedback?

When an AI agent reads, writes, searches, and deploys on your behalf, you lose visibility. Sound restores awareness.

Accessibility

Hear state changes, errors, and completions without watching the terminal scroll.

Flow

Know a test passed or a push landed without context-switching away from what you're doing.

Presence

The agent feels like a collaborator, not a black box. Sound makes the work feel real.

The 7 Verbs

Every Claude Code action maps to one of 7 core verbs. Modifiers alter the sound without breaking coherence.

Verb

Triggers

Sound

intake

Read, WebFetch, WebSearch

Soft rising sine — something coming in

transform

Edit

FM-textured pulse — reshaping

commit

Write, NotebookEdit, git commit

Sharp stamp tone — sealed

navigate

Grep, Glob

Sonar ping — scanning

execute

Bash, npm test, tsc

Noise burst + tone — mechanical action

move

mv, cp, subagent spawn

Wind whoosh — air displacement

sync

git push, git pull

Dramatic whoosh + tonal anchor

Quick Start

Install & init

npm install -g claude-sfx
cd your-project
claude-sfx init       # install hooks
claude-sfx demo       # hear all 7 verbs

Modifiers

claude-sfx play navigate --status ok
claude-sfx play navigate --status err
claude-sfx play sync --direction up
claude-sfx play sync --direction down
claude-sfx play intake --scope remote

Profiles

Switch palettes

claude-sfx demo --profile retro
claude-sfx preview minimal
claude-sfx config set profile retro
claude-sfx config repo retro

Custom profiles

# Copy a built-in profile
cp profiles/minimal.json my-profile.json

# Edit the synthesis parameters
# Every number maps to the synth engine

claude-sfx play navigate \
  --profile ./my-profile.json

Anti-Annoyance

What separates a product from a toy.

Feature

Behavior

Debounce

Same verb within 200ms → one sound

Rate limit

Max 8 sounds per 10-second window

Quiet hours

All sounds suppressed during configured hours

Mute

Instant toggle, survives session restart

Volume

0–100 gain control

Per-verb disable

Turn off specific verbs you don't want

How It Works

Zero audio files. Every sound is synthesized at runtime from math.

Oscillators

Sine, square, sawtooth, triangle, and white noise — the building blocks of every sound.

FM Synthesis

Frequency modulation adds texture and character. Envelopes shape attack, decay, sustain, release.

Bandpass Whoosh

State-variable filter sweeps through noise for realistic wind and movement sounds.