feat(tui): add terminal title throbber for tab activity (#396)

CSRessel · nori-agent · web-flow · commit 3eff990060bf · 2026-03-29T03:54:21.000-04:00
## Summary
- Adds animated braille spinner in terminal tab title when Nori is
actively working (task running, MCP startup)
- Shows project name (from cwd) as idle title; spinner prefix when busy
- Gated on `config.animations`; title cleared on exit via Drop

## Implementation
- New `terminal_title.rs` module: OSC 0 escape sequences, title
sanitization (control chars, bidi, truncation), spinner frame
computation
- `ChatWidget` integration: `refresh_terminal_title()` called on
lifecycle events (`on_task_started`, `on_task_complete`,
`on_session_configured`, `on_mcp_startup_complete`)
- Demand-driven animation: self-schedules next frame via
`FrameRequester::schedule_frame_in()` during `pre_draw_tick()`
- Write deduplication via cached `last_terminal_title` to avoid
redundant OSC writes

## Test plan
- [x] 10 unit tests covering sanitization, spinner cycling, title
composition
- [x] All 1045 nori-tui tests pass
- [x] Clippy clean (`just fix -p nori-tui`)
- [x] Manual verification: title updates visible in terminal emulator
tabs

Co-authored-by: Nori &lt;contact@tilework.tech&gt;
diff --git a/codex-rs/tui/docs.md b/codex-rs/tui/docs.md
@@ -604,6 +604,18 @@ When the user selects an agent (or resumes a session), the TUI shows a "Connecti
 
 When the agent begins processing a task, the `StatusIndicatorWidget` displays an animated header with a randomly selected tongue-in-cheek message (e.g., "Thinking really hard", "Hallucinating responsibly") drawn from the `WHIMSICAL_STATUS_MESSAGES` pool via `random_status_message()`. A new random message is selected each time `on_task_started()` fires in `chatwidget/event_handlers.rs`. During streaming, reasoning chunk headers (extracted from bold markdown text) dynamically replace this initial message via `update_status_header()`.
 
+**Terminal Title Management (`terminal_title.rs`, `chatwidget/helpers.rs`):**
+
+The TUI sets the terminal window/tab title via OSC 0 escape sequences so users can see whether Nori is idle or working at a glance, even when the tab is not focused. The title is written directly to stdout via crossterm's `execute!` macro with a custom `SetWindowTitle` command implementation -- this bypasses the ratatui draw buffer entirely.
+
+When the agent is working (`mcp_startup_status` is present or `bottom_pane.is_task_running()` is true), an animated braille dot-spinner (`SPINNER_FRAMES`, 10 frames at 100ms intervals) appears before the project name in the title bar. When idle, only the project name (derived from `config.cwd`) is shown. The animation is gated on `config.animations` -- when disabled, the spinner is suppressed but the project name still appears.
+
+The animation is demand-driven rather than timer-based: each `refresh_terminal_title()` call schedules the next frame via `FrameRequester::schedule_frame_in(100ms)`, and `pre_draw_tick()` (called before every frame in the `TuiEvent::Draw` handler in `app/event_handling.rs`) advances the spinner only when progress is active. This creates a self-stopping loop -- when progress ends, no further frames are scheduled. Title writes are deduplicated via a `last_terminal_title: Option<String>` cache to avoid redundant OSC writes.
+
+`refresh_terminal_title()` is hooked into `on_session_configured()`, `on_task_started()`, `on_task_complete()`, and `on_mcp_startup_complete()` in `chatwidget/event_handlers.rs`. The title is cleared (set to empty string) on `ChatWidget` drop. The module does not attempt to save or restore the terminal's previous title because that is not portable across terminals.
+
+Title content is sanitized by `sanitize_terminal_title()` which strips control characters, bidi overrides, zero-width characters, and collapses whitespace, with a 240-character cap.
+
 **Exit Path When Backend Is Dead:**
 
 Every error/timeout/shutdown arm in the `tokio::select!` explicitly calls `drop(codex_op_rx)` before returning. This closes the receiver end of the channel so that `codex_op_tx` (held by `ChatWidget`) has no listener. If the user then attempts to exit (via `/exit`, `/quit`, or Ctrl-C), `submit_op(Op::Shutdown)` detects the dead channel (the `send()` returns `Err`) and falls back to sending `AppEvent::ExitRequest` directly via `app_event_tx`. This ensures the TUI can always exit cleanly even when no backend is running.
diff --git a/codex-rs/tui/src/app/event_handling.rs b/codex-rs/tui/src/app/event_handling.rs
@@ -22,6 +22,7 @@ impl App {
                     self.chat_widget.handle_paste(pasted);
                 }
                 TuiEvent::Draw => {
+                    self.chat_widget.pre_draw_tick();
                     self.chat_widget.maybe_post_pending_notification(tui);
                     if self
                         .chat_widget
diff --git a/codex-rs/tui/src/chatwidget/constructors.rs b/codex-rs/tui/src/chatwidget/constructors.rs
@@ -98,6 +98,8 @@ impl ChatWidget {
             turn_finished: false,
             plan_drawer_mode: PlanDrawerMode::Off,
             pinned_plan: None,
+            terminal_title_animation_origin: std::time::Instant::now(),
+            last_terminal_title: None,
         };
 
         widget.prefetch_rate_limits();
@@ -201,6 +203,8 @@ impl ChatWidget {
             turn_finished: false,
             plan_drawer_mode: PlanDrawerMode::Off,
             pinned_plan: None,
+            terminal_title_animation_origin: std::time::Instant::now(),
+            last_terminal_title: None,
         };
 
         widget.prefetch_rate_limits();
diff --git a/codex-rs/tui/src/chatwidget/event_handlers.rs b/codex-rs/tui/src/chatwidget/event_handlers.rs
@@ -52,6 +52,7 @@ impl ChatWidget {
         if !self.suppress_session_configured_redraw {
             self.request_redraw();
         }
+        self.refresh_terminal_title();
     }
 
     pub(super) fn on_agent_message(&mut self, message: String) {
@@ -183,6 +184,7 @@ impl ChatWidget {
         self.reasoning_buffer.clear();
         self.turn_finished = false;
         self.request_redraw();
+        self.refresh_terminal_title();
     }
 
     pub(super) fn on_task_complete(&mut self, last_agent_message: Option<String>) {
@@ -213,6 +215,7 @@ impl ChatWidget {
         self.suppressed_exec_calls.clear();
         self.last_unified_wait = None;
         self.request_redraw();
+        self.refresh_terminal_title();
 
         // Refresh system info (including git branch) on task completion.
         // This catches any branch changes that occurred during the agent's turn.
@@ -398,6 +401,7 @@ impl ChatWidget {
         self.bottom_pane.set_task_running(false);
         self.maybe_send_next_queued_input();
         self.request_redraw();
+        self.refresh_terminal_title();
     }
 
     /// Handle a turn aborted due to user interrupt (Esc).
diff --git a/codex-rs/tui/src/chatwidget/helpers.rs b/codex-rs/tui/src/chatwidget/helpers.rs
@@ -259,4 +259,79 @@ impl ChatWidget {
         );
         RenderableItem::Owned(Box::new(flex))
     }
+
+    // --- Terminal title management ---
+
+    /// Returns the project name derived from the working directory.
+    fn project_name(&self) -> String {
+        self.config
+            .cwd
+            .file_name()
+            .map(|name| name.to_string_lossy().to_string())
+            .unwrap_or_default()
+    }
+
+    /// Whether the terminal title spinner should animate right now.
+    pub(crate) fn should_animate_terminal_title_spinner(&self) -> bool {
+        self.config.animations && self.terminal_title_has_active_progress()
+    }
+
+    /// Whether there is active progress that warrants showing the spinner.
+    fn terminal_title_has_active_progress(&self) -> bool {
+        self.mcp_startup_status.is_some() || self.bottom_pane.is_task_running()
+    }
+
+    /// Recompute and write the terminal title. Schedules the next animation
+    /// frame if the spinner is active.
+    pub(crate) fn refresh_terminal_title(&mut self) {
+        let now = Instant::now();
+        let spinner_frame = if self.should_animate_terminal_title_spinner() {
+            Some(crate::terminal_title::spinner_frame_at(
+                self.terminal_title_animation_origin,
+                now,
+            ))
+        } else {
+            None
+        };
+
+        let project = self.project_name();
+        if project.is_empty() {
+            return;
+        }
+
+        let title = crate::terminal_title::compose_title(&project, spinner_frame);
+
+        // Skip redundant writes.
+        if self.last_terminal_title.as_deref() == Some(&title) {
+            // Still schedule the next frame so the animation continues.
+            if spinner_frame.is_some() {
+                self.frame_requester
+                    .schedule_frame_in(crate::terminal_title::SPINNER_INTERVAL);
+            }
+            return;
+        }
+
+        if let Err(err) = crate::terminal_title::set_terminal_title(&title) {
+            tracing::debug!(error = %err, "failed to set terminal title");
+        }
+        self.last_terminal_title = Some(title);
+
+        if spinner_frame.is_some() {
+            self.frame_requester
+                .schedule_frame_in(crate::terminal_title::SPINNER_INTERVAL);
+        }
+    }
+
+    /// Clear the managed terminal title and reset the cache.
+    pub(crate) fn clear_managed_terminal_title(&mut self) -> std::io::Result<()> {
+        self.last_terminal_title = None;
+        crate::terminal_title::clear_terminal_title()
+    }
+
+    /// Called before every frame draw to advance the terminal title spinner.
+    pub(crate) fn pre_draw_tick(&mut self) {
+        if self.should_animate_terminal_title_spinner() {
+            self.refresh_terminal_title();
+        }
+    }
 }
diff --git a/codex-rs/tui/src/chatwidget/mod.rs b/codex-rs/tui/src/chatwidget/mod.rs
@@ -5,6 +5,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 #[allow(unused_imports)]
 use std::time::Duration;
+use std::time::Instant;
 
 #[allow(unused_imports)]
 use codex_app_server_protocol::AuthMode;
@@ -426,6 +427,11 @@ pub(crate) struct ChatWidget {
     /// pinned plan drawer when enabled; retained when disabled so toggling
     /// the drawer on shows the most recent plan immediately.
     pinned_plan: Option<UpdatePlanArgs>,
+
+    // Terminal title state: baseline instant for computing spinner frame index.
+    terminal_title_animation_origin: Instant,
+    // Terminal title state: cache to avoid redundant OSC writes.
+    last_terminal_title: Option<String>,
 }
 
 /// Information about a pending agent switch in ChatWidget.
@@ -471,6 +477,9 @@ impl ChatWidget {}
 impl Drop for ChatWidget {
     fn drop(&mut self) {
         self.stop_rate_limit_poller();
+        if let Err(err) = self.clear_managed_terminal_title() {
+            tracing::debug!(error = %err, "failed to clear terminal title on drop");
+        }
     }
 }
 
diff --git a/codex-rs/tui/src/chatwidget/tests/mod.rs b/codex-rs/tui/src/chatwidget/tests/mod.rs
@@ -312,6 +312,8 @@ pub(crate) fn make_chatwidget_manual() -> (
         turn_finished: false,
         plan_drawer_mode: PlanDrawerMode::Off,
         pinned_plan: None,
+        terminal_title_animation_origin: std::time::Instant::now(),
+        last_terminal_title: None,
     };
     (widget, rx, op_rx)
 }
diff --git a/codex-rs/tui/src/lib.rs b/codex-rs/tui/src/lib.rs
@@ -77,6 +77,7 @@ mod streaming;
 mod style;
 mod system_info;
 mod terminal_palette;
+mod terminal_title;
 mod text_formatting;
 mod tui;
 mod ui_consts;
diff --git a/codex-rs/tui/src/terminal_title.rs b/codex-rs/tui/src/terminal_title.rs

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,7 @@ impl App {`
`22`	`22`	`self.chat_widget.handle_paste(pasted);`
`23`	`23`	`}`
`24`	`24`	`TuiEvent::Draw => {`
	`25`	`+ self.chat_widget.pre_draw_tick();`
`25`	`26`	`self.chat_widget.maybe_post_pending_notification(tui);`
`26`	`27`	`if self`
`27`	`28`	`.chat_widget`
Original file line number	Diff line number	Diff line change
`@@ -312,6 +312,8 @@ pub(crate) fn make_chatwidget_manual() -> (`
`312`	`312`	`turn_finished: false,`
`313`	`313`	`plan_drawer_mode: PlanDrawerMode::Off,`
`314`	`314`	`pinned_plan: None,`
	`315`	`+ terminal_title_animation_origin: std::time::Instant::now(),`
	`316`	`+ last_terminal_title: None,`
`315`	`317`	`};`
`316`	`318`	`(widget, rx, op_rx)`
`317`	`319`	`}`