feat: sound notifications for agent state changes

play a chime when an agent finishes work and an alert when one needs
input. only triggers for background workspaces. configurable via
sound = true/false under [ui] in config.

6 files changed, 83 insertions, 1 deletions

diff --git a/src/app/actions.rs b/src/app/actions.rs
index 8e2e9297..c73ba646 100644
--- a/src/app/actions.rs
+++ b/src/app/actions.rs
@@ -157,12 +157,29 @@ impl AppState {
                 for (ws_idx, ws) in self.workspaces.iter_mut().enumerate() {
                     if let Some(pane) = ws.panes.get_mut(&pane_id) {
                         let is_active_ws = self.active == Some(ws_idx);
+                        let prev_state = pane.state;
+
+                        // Mark unseen when transitioning to Idle in background
                         if state == AgentState::Idle
-                            && pane.state != AgentState::Idle
+                            && prev_state != AgentState::Idle
                             && !is_active_ws
                         {
                             pane.seen = false;
                         }
+
+                        // Sound notifications for background state changes
+                        if self.sound && !is_active_ws && state != prev_state {
+                            match state {
+                                AgentState::Idle if prev_state != AgentState::Idle => {
+                                    crate::sound::play(crate::sound::Sound::Done);
+                                }
+                                AgentState::Waiting => {
+                                    crate::sound::play(crate::sound::Sound::Request);
+                                }
+                                _ => {}
+                            }
+                        }
+
                         pane.detected_agent = agent;
                         pane.state = state;
                         break;
diff --git a/src/app/mod.rs b/src/app/mod.rs
index 62250fb8..47aaa3da 100644
--- a/src/app/mod.rs
+++ b/src/app/mod.rs
@@ -85,6 +85,7 @@ impl App {
             sidebar_collapsed: false,
             confirm_close: config.ui.confirm_close,
             accent: crate::config::parse_color(&config.ui.accent),
+            sound: config.ui.sound,
             keybinds: config.keybinds(),
         };
 
diff --git a/src/app/state.rs b/src/app/state.rs
index b0a81165..440bfc17 100644
--- a/src/app/state.rs
+++ b/src/app/state.rs
@@ -69,6 +69,7 @@ pub struct AppState {
     pub sidebar_collapsed: bool,
     pub confirm_close: bool,
     pub accent: Color,
+    pub sound: bool,
     pub keybinds: Keybinds,
 }
 
@@ -119,6 +120,7 @@ impl AppState {
             sidebar_collapsed: false,
             confirm_close: true,
             accent: Color::Cyan,
+            sound: true,
             keybinds: Keybinds {
                 split_vertical: (KeyCode::Char('v'), KeyModifiers::empty()),
                 split_horizontal: (KeyCode::Char('-'), KeyModifiers::empty()),
diff --git a/src/config.rs b/src/config.rs
index 0022d230..704d176c 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -35,6 +35,8 @@ pub struct UiConfig {
     /// Accent color for highlights, borders, and navigation UI.
     /// Accepts hex (#89b4fa), named colors (cyan, blue), or RGB (rgb(137,180,250)).
     pub accent: String,
+    /// Play sounds when agents change state in background workspaces.
+    pub sound: bool,
 }
 
 impl Default for KeysConfig {
@@ -55,6 +57,7 @@ impl Default for UiConfig {
             sidebar_width: 26,
             confirm_close: true,
             accent: "cyan".into(),
+            sound: true,
         }
     }
 }
diff --git a/src/main.rs b/src/main.rs
index a76b913e..1e31b05a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -18,6 +18,7 @@ mod persist;
 mod platform;
 mod pty_callbacks;
 mod selection;
+mod sound;
 mod ui;
 mod update;
 mod workspace;
@@ -82,6 +83,9 @@ const DEFAULT_CONFIG: &str = r#"# herdr configuration
 # Accent color for highlights, borders, and navigation UI.
 # Accepts: hex (#89b4fa), named colors (cyan, blue, magenta), or rgb(r,g,b)
 # accent = "cyan"
+
+# Play sounds when agents change state in background workspaces
+# sound = true
 "#;
 
 fn main() -> io::Result<()> {
diff --git a/src/sound.rs b/src/sound.rs
new file mode 100644
index 00000000..f4123e10
--- /dev/null
+++ b/src/sound.rs
@@ -0,0 +1,55 @@
+//! Sound notifications for agent state changes.
+//!
+//! Embeds mp3 files in the binary and plays them via system audio tools.
+//! Uses afplay (macOS) or paplay/aplay (Linux) — no Rust audio dependencies.
+
+use std::io::Write;
+use std::process::Command;
+
+static SOUND_DONE: &[u8] = include_bytes!("../assets/sounds/done.mp3");
+static SOUND_REQUEST: &[u8] = include_bytes!("../assets/sounds/request.mp3");
+
+/// Which notification sound to play.
+pub enum Sound {
+    /// Agent finished work (transitioned to Idle).
+    Done,
+    /// Agent needs input (transitioned to Waiting).
+    Request,
+}
+
+/// Play a notification sound in a background thread.
+/// Silently does nothing if no audio player is available.
+pub fn play(sound: Sound) {
+    std::thread::spawn(move || {
+        let data = match sound {
+            Sound::Done => SOUND_DONE,
+            Sound::Request => SOUND_REQUEST,
+        };
+        let _ = play_bytes(data);
+    });
+}
+
+fn play_bytes(data: &[u8]) -> Result<(), String> {
+    // Write to a temp file (audio players need a file path)
+    let tmp = std::env::temp_dir().join(format!("herdr-sound-{}.mp3", std::process::id()));
+    let mut file = std::fs::File::create(&tmp).map_err(|e| e.to_string())?;
+    file.write_all(data).map_err(|e| e.to_string())?;
+    drop(file);
+
+    let result = if cfg!(target_os = "macos") {
+        Command::new("afplay").arg(&tmp).output()
+    } else {
+        // Try paplay (PulseAudio) first, fall back to aplay (ALSA)
+        Command::new("paplay").arg(&tmp).output().or_else(|_| {
+            Command::new("aplay").arg(&tmp).output()
+        })
+    };
+
+    let _ = std::fs::remove_file(&tmp);
+
+    match result {
+        Ok(output) if output.status.success() => Ok(()),
+        Ok(output) => Err(format!("player exited with {}", output.status)),
+        Err(e) => Err(format!("no audio player available: {e}")),
+    }
+}