Claude Cues — Sinais sonoros para Claude Code
mannanj/claude-cues
Sons suaves que indicam o que seu agente está fazendo sem olhar
Ver no GitHubAgent que fornece pistas de áudio distintas para cada fase da sessão do Claude Code (início, submissão, conclusão, permissão, erro, compactação). Usa três personalidades vocais (chime, hum, ping) que alternam automaticamente sem interferir no fluxo de trabalho.
Instalação
npx convez-ai mannanj/claude-cues1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Saber quando Claude terminou uma tarefa sem olhar a tela
- Captar atenção em pedidos de permissão ou erros críticos
- Manter contexto ao alternar entre abas/tarefas paralelas
Veredito

Ferramenta minimalista e bem executada (~200KB, zero deps, fire-and-forget). Resolve um problema real de UX em ambientes de trabalho multitarefa, com instalação simples e capacidade extensível via personalidades customizáveis.
README
A tradução para o português deste README ainda está na fila.
Claude Code doesn't tell you when it finishes or needs permission. You tab away, lose the thread, and come back twenty minutes later to a question it asked nineteen minutes ago.
claude-cues fixes that with sound. Six moments in every session get a soft, distinct cue — so you can walk away and still know exactly what your agent is doing.
It's ~200KB of original audio, one shell script, and zero dependencies. No daemon, no network, no telemetry, and it never blocks Claude — every sound is fire-and-forget.
Install
Inside Claude Code:
/plugin marketplace add mannanj/claude-cues
/plugin install claude-cues@claude-cues
Restart Claude Code (or /reload-plugins). That's it — you'll hear it on your next session.
git clone https://github.com/mannanj/claude-cues.git
cd claude-cues && ./install.sh
install.sh is ~80 readable lines: it copies the files to
~/.claude/claude-cues/ and safely merges (never overwrites) six hook
entries into ~/.claude/settings.json, backing it up first.
Remove everything with ./uninstall.sh.
The sounds
| Hook | When it fires | What you hear |
|---|---|---|
SessionStart | New session | the personality's theme |
UserPromptSubmit | You hit enter | a soft acknowledgment (3 variants) |
Stop | Task done | a completion tone |
PermissionRequest | Claude needs you | a distinct prompt tone |
PostToolUseFailure | Something failed | a gentle low note |
PreCompact | Context compacting | a quiet transition |
Personalities
Every session gets one consistent voice, rotating session to session so it never goes stale — and never mixes voices mid-session.
| Character | |
|---|---|
| chime | crisp, bright, bell-like |
| hum | warm, low, rounded |
| ping | minimal, dry, precise |
Audition all three on the demo page →
Make your own
A personality is just a folder of mp3s:
sounds/<your-name>/{start,submit,done,permission,error,precompact}/*.mp3
Drop one in and it joins the rotation automatically. Missing an event folder? That event is silent for that personality — it never borrows another voice. PRs with new original (CC0) personalities are very welcome.
Configure
/claude-cues:toggle mutes/unmutes. /claude-cues:status shows current state.
Or edit ~/.claude/claude-cues/config:
ENABLED=1 # master switch
VOLUME=3.0 # macOS gain multiplier (the tones are mastered quiet)
PERSONALITY=hum # pin one voice instead of rotating
How it works
- Claude Code hooks call one small script:
bin/play.sh - It picks a random sound from the session personality's folder for that event
- Playback is backgrounded (
afplayon macOS;ffplay/mpg123/paplayon Linux) — the hook returns instantly - No sound player found, or folder empty? Silent. It can never error your session.
FAQ
Does it slow Claude Code down? No. The hook backgrounds the player and returns immediately; there's no daemon and nothing to wait on.
Can I use my own sounds? Yes — see Make your own.
Windows? Not yet (the script no-ops silently). PRs welcome.
How do I mute just one event? Delete or empty that event's folder in the personality — or pin a personality that doesn't define it.
Will it play over my music? It plays alongside; the cues are under a second each and mastered soft.
Uninstall
Plugin: /plugin uninstall claude-cues. Script install: ./uninstall.sh.
License
Code is MIT. All audio in sounds/ is original,
synthesized for this project, and dedicated to the public domain under
CC0 — see credits.
Inspired by the walk-away problem everyone has with coding agents, and by rubenflamshepherd/starcraft-claude, which proved how good sound feels in Claude Code (this project ships only original audio).