test: include alternate_screen in tui default

Author: hjanuschka

codex-rs/core/src/config/mod.rs

@@ -1632,6 +1632,7 @@ persistence = "none"
                 scroll_wheel_tick_detect_max_ms: None,
                 scroll_wheel_like_max_duration_ms: None,
                 scroll_invert: false,
+                alternate_screen: AltScreenMode::Auto,
             }
         );
     }

codex-rs/protocol/src/config_types.rs

@@ -83,10 +83,27 @@ pub enum TrustLevel {
 
 /// Controls whether the TUI uses the terminal's alternate screen buffer.
 ///
-/// Using alternate screen provides a cleaner fullscreen experience but prevents
-/// scrollback in terminal multiplexers like Zellij that follow the xterm spec
-/// (which says alternate screen should not have scrollback).
-#[derive(Debug, Serialize, Deserialize, Default, Clone, Copy, PartialEq, Eq, Display, JsonSchema, TS)]
+/// **Background:** The alternate screen buffer provides a cleaner fullscreen experience
+/// without polluting the terminal's scrollback history. However, it conflicts with terminal
+/// multiplexers like Zellij that strictly follow the xterm specification, which defines
+/// that alternate screen buffers should not have scrollback.
+///
+/// **Zellij's behavior:** Zellij intentionally disables scrollback in alternate screen mode
+/// (see https://github.com/zellij-org/zellij/pull/1032) to comply with the xterm spec. This
+/// is by design and not configurable in Zellij—there is no option to enable scrollback in
+/// alternate screen mode.
+///
+/// **Solution:** This setting provides a pragmatic workaround:
+/// - `auto` (default): Automatically detect the terminal multiplexer. If running in Zellij,
+///   disable alternate screen to preserve scrollback. Enable it everywhere else.
+/// - `always`: Always use alternate screen mode (original behavior before this fix).
+/// - `never`: Never use alternate screen mode. Runs in inline mode, preserving scrollback
+///   in all multiplexers.
+///
+/// The CLI flag `--no-alt-screen` can override this setting at runtime.
+#[derive(
+    Debug, Serialize, Deserialize, Default, Clone, Copy, PartialEq, Eq, Display, JsonSchema, TS,
+)]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 pub enum AltScreenMode {

codex-rs/tui/src/cli.rs

@@ -85,8 +85,11 @@ pub struct Cli {
     #[arg(long = "add-dir", value_name = "DIR", value_hint = ValueHint::DirPath)]
     pub add_dir: Vec<PathBuf>,
 
-    /// Disable alternate screen mode for better scrollback in terminal multiplexers like Zellij.
-    /// This runs the TUI in inline mode, preserving terminal scrollback history.
+    /// Disable alternate screen mode
+    ///
+    /// Runs the TUI in inline mode, preserving terminal scrollback history. This is useful
+    /// in terminal multiplexers like Zellij that follow the xterm spec strictly and disable
+    /// scrollback in alternate screen buffers.
     #[arg(long = "no-alt-screen", default_value_t = false)]
     pub no_alt_screen: bool,
 

codex-rs/tui/src/lib.rs

@@ -502,19 +502,7 @@ async fn run_ratatui_app(
         ..
     } = cli;
 
-    // Determine whether to use alternate screen based on CLI flag and config.
-    let use_alt_screen = if no_alt_screen {
-        false
-    } else {
-        match config.tui_alternate_screen {
-            AltScreenMode::Always => true,
-            AltScreenMode::Never => false,
-            AltScreenMode::Auto => {
-                let terminal_info = codex_core::terminal::terminal_info();
-                !matches!(terminal_info.multiplexer, Some(Multiplexer::Zellij { .. }))
-            }
-        }
-    };
+    let use_alt_screen = determine_alt_screen_mode(no_alt_screen, config.tui_alternate_screen);
     tui.set_alt_screen_enabled(use_alt_screen);
 
     let app_result = App::run(
@@ -549,6 +537,37 @@ fn restore() {
     }
 }
 
+/// Determine whether to use the terminal's alternate screen buffer.
+///
+/// The alternate screen buffer provides a cleaner fullscreen experience without polluting
+/// the terminal's scrollback history. However, it conflicts with terminal multiplexers like
+/// Zellij that strictly follow the xterm spec, which disallows scrollback in alternate screen
+/// buffers. Zellij intentionally disables scrollback in alternate screen mode (see
+/// https://github.com/zellij-org/zellij/pull/1032) and offers no configuration option to
+/// change this behavior.
+///
+/// This function implements a pragmatic workaround:
+/// - If `--no-alt-screen` is explicitly passed, always disable alternate screen
+/// - Otherwise, respect the `tui.alternate_screen` config setting:
+///   - `always`: Use alternate screen everywhere (original behavior)
+///   - `never`: Inline mode only, preserves scrollback
+///   - `auto` (default): Auto-detect the terminal multiplexer and disable alternate screen
+///     only in Zellij, enabling it everywhere else
+fn determine_alt_screen_mode(no_alt_screen: bool, tui_alternate_screen: AltScreenMode) -> bool {
+    if no_alt_screen {
+        false
+    } else {
+        match tui_alternate_screen {
+            AltScreenMode::Always => true,
+            AltScreenMode::Never => false,
+            AltScreenMode::Auto => {
+                let terminal_info = codex_core::terminal::terminal_info();
+                !matches!(terminal_info.multiplexer, Some(Multiplexer::Zellij { .. }))
+            }
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum LoginStatus {
     AuthMode(AuthMode),

codex-rs/tui2/src/lib.rs

@@ -524,9 +524,15 @@ async fn run_ratatui_app(
         ..
     } = cli;
 
-    // Determine whether to use alternate screen based on CLI flag and config.
-    // Alternate screen provides a cleaner fullscreen experience but prevents
-    // scrollback in terminal multiplexers like Zellij that follow xterm spec.
+    // Run the main chat + transcript UI on the terminal's alternate screen so
+    // the entire viewport can be used without polluting normal scrollback. This
+    // mirrors the behavior of the legacy TUI but keeps inline mode available
+    // for smaller prompts like onboarding and model migration.
+    //
+    // However, alternate screen prevents scrollback in terminal multiplexers like
+    // Zellij that strictly follow the xterm spec (which disallows scrollback in
+    // alternate screen buffers). This auto-detects the terminal and disables
+    // alternate screen in Zellij while keeping it enabled elsewhere.
     let use_alt_screen = if no_alt_screen {
         // CLI flag explicitly disables alternate screen
         false