convez.ai
AgenteUtilidadesIniciante
mannanj

Claude Cues — Sinais sonoros para Claude Code

mannanj/claude-cues

Sons suaves que indicam o que seu agente está fazendo sem olhar

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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-cues

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
1

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

HookWhen it firesWhat you hear
SessionStartNew sessionthe personality's theme
UserPromptSubmitYou hit entera soft acknowledgment (3 variants)
StopTask donea completion tone
PermissionRequestClaude needs youa distinct prompt tone
PostToolUseFailureSomething faileda gentle low note
PreCompactContext compactinga 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
chimecrisp, bright, bell-like
humwarm, low, rounded
pingminimal, 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 (afplay on macOS; ffplay/mpg123/paplay on 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).

Ver o original no GitHub

Bom para

Relacionados