TL;DR: I wired custom voice audio into Claude Code, Codex CLI, and Gemini CLI using their hook systems — so my agents literally speak to me when they’re done, waiting, or need attention. Here’s how, and how you can add your own sounds.

Why

When you’re deep in work with multiple AI CLI agents running, you stop watching the terminal. You miss when they’re done. You miss when they need input. The feedback loop breaks.

The fix: ambient audio hooks. Each agent plays a voice sound at the right moment — done, waiting, listening, needs help — so you know what’s happening without looking.

What We Built

The architecture consists of three layers:

  1. Lifecycle event hooks — each CLI has events (session start, prompt submitted, agent done, notification). We wire audio to those.
  2. Intent‑matched sounds — sounds chosen to match the meaning of the event, not just “something happened.”
  3. Attention re‑trigger timer — if you don’t respond within 30 s after a Notification, it nudges you again every 2 minutes until you do.

The Sound Library

All sounds live in ~/.agents/sounds/cli/. The shared player script is at ~/.agents/sounds/peon/play_sound.sh — it accepts multiple file paths and picks one at random.

Intent Groups

Intent Sample Files
Ready / Starting cli-im-here.mp3, cli-alright.mp3, cli-i-got-this.mp3
Acknowledging / On it cli-i-can-do-that.mp3, cli-i-got-you.mp3, cli-ill-try.mp3
Needs attention / Help cli-i-need-your-attention.mp3, cli-help-pls.mp3, cli-i-need-more-info.mp3
Done — Claude cli-im-done-claude.mp3, cli-im-done-eyes-here-pls.mp3
Done — Codex cli-im-done-codex.mp3
Done — Gemini cli-im-done-gemini.mp3
Wait mode (timer) cli-im-on-wait-mode.mp3 (first nudge), cli-been-waiting.mp3 (repeat)

The Attention Timer

File: ~/.agents/sounds/cli/attention_timer.sh

When an agent finishes its turn (Stop or AfterAgent), the timer starts. This ensures that if the agent is waiting for your review or has hit a notification state, you get a nudge:

  • 30 seconds → plays cli-im-on-wait-mode.mp3 (first nudge)
  • Every 2 minutes after → plays cli-been-waiting.mp3
  • When you respond → the timer PID is killed, and an acknowledgment sound plays.

The timer uses a shared PID file at /tmp/cli-attention-timer.pid. Responding to any of the three agents cancels the timer for all of them.

Hook Configs: The Technical Wiring

Claude Code — ~/.claude/settings.json

Event Behavior
SessionStart Ready sounds
UserPromptSubmit Stops timer + acknowledging sounds
Notification Attention sounds only — no timer (fires too broadly)
Stop Done sounds (Claude‑specific) + starts timer

Codex — ~/.codex/hooks/notify_peon.py

Codex uses a Python hook script wired via ~/.codex/config.toml. The script receives a JSON payload with an event type and picks sounds accordingly:

Event Behavior
agent-turn-complete Done sounds (Codex‑specific) + starts timer
approval-requested Attention/help sounds
(default) Stops timer + acknowledging sounds

Gemini — ~/.gemini/settings.json

Event Behavior
SessionStart Ready sounds
BeforeAgent Stops timer + acknowledging sounds
Notification Attention sounds only — no timer
AfterAgent Done sounds (Gemini‑specific) + starts timer

Claude → Gemini event name mapping (for reference):

Claude Gemini
UserPromptSubmit BeforeAgent
Stop AfterAgent
PreToolUse BeforeTool
PostToolUse AfterTool
SessionStart SessionStart
Notification Notification

The Player Script

~/.agents/sounds/peon/play_sound.sh is the backbone. It ensures the CLI never blocks by running in the background.

# Play one random sound from a list
~/.agents/sounds/peon/play_sound.sh \
  ~/.agents/sounds/cli/cli-im-here.mp3 \
  ~/.agents/sounds/cli/cli-alright.mp3

Key Design Decisions

  • Non‑blocking Execution: All sounds run fire‑and‑forget (nohup ... &).
  • Selective Nudging: By moving the timer start to the Stop event rather than Notification, we catch the moment the agent finishes its work, which is the most critical time for human re‑engagement.
  • Vocal Identity: Unique “Done” sounds allow for audio‑only identification of which agent has completed its task.

What We Call This

This pattern isn’t just about sounds; it’s Ambient AI Presence Design. It uses lifecycle event hooks and intent‑matched audio to create an attention re‑trigger pattern.

It’s about lowering the cognitive load of multitasking with autonomous systems. When your agents can tell you how they’re feeling, you can spend more time doing the thinking that only humans can do. 🎧✨

Further Reading

If you’re interested in deeper CLI customizations, check out the related post A Better Codex CLI Wrapper (with Logs + Defaults) for advanced logging and default handling techniques.

END_OF_REPORT 🌿✨