fix: add tui.alternate_screen config and --no-alt-screen CLI flag

Fixes #2558 - Zellij users cannot scroll back due to alternate screen mode.

This adds:
- `AltScreenMode` enum with values: auto, always, never
- `tui.alternate_screen` config option (default: auto)
- `--no-alt-screen` CLI flag to force inline mode
- Auto-detection: When running in Zellij (detected via ZELLIJ env vars),
  alternate screen is automatically disabled to preserve scrollback

The implementation:
- Detects Zellij using existing terminal_info() infrastructure
- In "auto" mode, skips enter_alt_screen() when in Zellij
- In "never" mode or with --no-alt-screen flag, always uses inline mode
- In "always" mode, uses alternate screen (original behavior)

Author: hjanuschka

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

@@ -32,6 +32,7 @@ use crate::protocol::AskForApproval;
 use crate::protocol::SandboxPolicy;
 use codex_app_server_protocol::Tools;
 use codex_app_server_protocol::UserSavedConfig;
+use codex_protocol::config_types::AltScreenMode;
 use codex_protocol::config_types::ForcedLoginMethod;
 use codex_protocol::config_types::ReasoningSummary;
 use codex_protocol::config_types::SandboxMode;
@@ -236,6 +237,14 @@ pub struct Config {
     /// consistently to both mouse wheels and trackpads.
     pub tui_scroll_invert: bool,
 
+    /// Controls whether the TUI uses the terminal's alternate screen buffer.
+    ///
+    /// This is the same `tui.alternate_screen` value from `config.toml` (see [`Tui`]).
+    /// - `auto` (default): Disable alternate screen in Zellij, enable elsewhere.
+    /// - `always`: Always use alternate screen (original behavior).
+    /// - `never`: Never use alternate screen (inline mode, preserves scrollback).
+    pub tui_alternate_screen: AltScreenMode,
+
     /// The directory that should be treated as the current working directory
     /// for the session. All relative paths inside the business-logic layer are
     /// resolved against this path.
@@ -1418,6 +1427,11 @@ impl Config {
                 .as_ref()
                 .and_then(|t| t.scroll_wheel_like_max_duration_ms),
             tui_scroll_invert: cfg.tui.as_ref().map(|t| t.scroll_invert).unwrap_or(false),
+            tui_alternate_screen: cfg
+                .tui
+                .as_ref()
+                .map(|t| t.alternate_screen)
+                .unwrap_or_default(),
             otel: {
                 let t: OtelConfigToml = cfg.otel.unwrap_or_default();
                 let log_user_prompt = t.log_user_prompt.unwrap_or(false);
@@ -3211,6 +3225,7 @@ model_verbosity = "high"
                 tui_scroll_wheel_tick_detect_max_ms: None,
                 tui_scroll_wheel_like_max_duration_ms: None,
                 tui_scroll_invert: false,
+                tui_alternate_screen: AltScreenMode::Auto,
                 otel: OtelConfig::default(),
             },
             o3_profile_config
@@ -3294,6 +3309,7 @@ model_verbosity = "high"
             tui_scroll_wheel_tick_detect_max_ms: None,
             tui_scroll_wheel_like_max_duration_ms: None,
             tui_scroll_invert: false,
+            tui_alternate_screen: AltScreenMode::Auto,
             otel: OtelConfig::default(),
         };
 
@@ -3392,6 +3408,7 @@ model_verbosity = "high"
             tui_scroll_wheel_tick_detect_max_ms: None,
             tui_scroll_wheel_like_max_duration_ms: None,
             tui_scroll_invert: false,
+            tui_alternate_screen: AltScreenMode::Auto,
             otel: OtelConfig::default(),
         };
 
@@ -3476,6 +3493,7 @@ model_verbosity = "high"
             tui_scroll_wheel_tick_detect_max_ms: None,
             tui_scroll_wheel_like_max_duration_ms: None,
             tui_scroll_invert: false,
+            tui_alternate_screen: AltScreenMode::Auto,
             otel: OtelConfig::default(),
         };
 

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

@@ -3,6 +3,7 @@
 // Note this file should generally be restricted to simple struct/enum
 // definitions that do not contain business logic.
 
+pub use codex_protocol::config_types::AltScreenMode;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use std::collections::BTreeMap;
 use std::collections::HashMap;
@@ -505,6 +506,17 @@ pub struct Tui {
     /// wheel and trackpad input.
     #[serde(default)]
     pub scroll_invert: bool,
+
+    /// Controls whether the TUI uses the terminal's alternate screen buffer.
+    ///
+    /// - `auto` (default): Disable alternate screen in Zellij, enable elsewhere.
+    /// - `always`: Always use alternate screen (original behavior).
+    /// - `never`: Never use alternate screen (inline mode only, preserves scrollback).
+    ///
+    /// Using alternate screen provides a cleaner fullscreen experience but prevents
+    /// scrollback in terminal multiplexers like Zellij that follow the xterm spec.
+    #[serde(default)]
+    pub alternate_screen: AltScreenMode,
 }
 
 const fn default_true() -> bool {

codex-rs/protocol/src/config_types.rs

@@ -80,3 +80,21 @@ pub enum TrustLevel {
     Trusted,
     Untrusted,
 }
+
+/// 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)]
+#[serde(rename_all = "lowercase")]
+#[strum(serialize_all = "lowercase")]
+pub enum AltScreenMode {
+    /// Auto-detect: disable alternate screen in Zellij, enable elsewhere.
+    #[default]
+    Auto,
+    /// Always use alternate screen (original behavior).
+    Always,
+    /// Never use alternate screen (inline mode only).
+    Never,
+}

codex-rs/tui/src/cli.rs

@@ -85,6 +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.
+    #[arg(long = "no-alt-screen", default_value_t = false)]
+    pub no_alt_screen: bool,
+
     #[clap(skip)]
     pub config_overrides: CliConfigOverrides,
 }

codex-rs/tui2/src/cli.rs

@@ -85,6 +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.
+    #[arg(long = "no-alt-screen", default_value_t = false)]
+    pub no_alt_screen: bool,
+
     #[clap(skip)]
     pub config_overrides: CliConfigOverrides,
 }
@@ -109,6 +114,7 @@ impl From<codex_tui::Cli> for Cli {
             cwd: cli.cwd,
             web_search: cli.web_search,
             add_dir: cli.add_dir,
+            no_alt_screen: cli.no_alt_screen,
             config_overrides: cli.config_overrides,
         }
     }

codex-rs/tui2/src/lib.rs

@@ -22,6 +22,8 @@ use codex_core::config::resolve_oss_provider;
 use codex_core::find_conversation_path_by_id_str;
 use codex_core::get_platform_sandbox;
 use codex_core::protocol::AskForApproval;
+use codex_core::terminal::Multiplexer;
+use codex_protocol::config_types::AltScreenMode;
 use codex_protocol::config_types::SandboxMode;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use std::fs::OpenOptions;
@@ -514,13 +516,34 @@ async fn run_ratatui_app(
         resume_picker::ResumeSelection::StartFresh
     };
 
-    let Cli { prompt, images, .. } = cli;
+    let Cli {
+        prompt,
+        images,
+        no_alt_screen,
+        ..
+    } = 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.
+    let use_alt_screen = if no_alt_screen {
+        // CLI flag explicitly disables alternate screen
+        false
+    } else {
+        match config.tui_alternate_screen {
+            AltScreenMode::Always => true,
+            AltScreenMode::Never => false,
+            AltScreenMode::Auto => {
+                // Auto-detect: disable in Zellij, enable elsewhere
+                let terminal_info = codex_core::terminal::terminal_info();
+                !matches!(terminal_info.multiplexer, Some(Multiplexer::Zellij { .. }))
+            }
+        }
+    };
 
-    // 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.
-    let _ = tui.enter_alt_screen();
+    if use_alt_screen {
+        let _ = tui.enter_alt_screen();
+    }
 
     let app_result = App::run(
         &mut tui,
@@ -535,7 +558,9 @@ async fn run_ratatui_app(
     )
     .await;
 
-    let _ = tui.leave_alt_screen();
+    if use_alt_screen {
+        let _ = tui.leave_alt_screen();
+    }
     restore();
     if let Ok(exit_info) = &app_result {
         let mut stdout = std::io::stdout();

docs/config.md

@@ -936,6 +936,18 @@ scroll_wheel_like_max_duration_ms = 200
 
 # Invert scroll direction for mouse wheel/trackpad. TUI2 only.
 scroll_invert = false
+
+# Alternate screen mode. TUI2 only.
+# Controls whether the TUI uses the terminal's alternate screen buffer.
+# Valid values: "auto" (default), "always", "never"
+#
+# - "auto": Disable alternate screen in Zellij (which follows xterm spec and
+#   doesn't support scrollback in alternate screen), enable elsewhere.
+# - "always": Always use alternate screen (original behavior).
+# - "never": Never use alternate screen (inline mode, preserves scrollback).
+#
+# You can also use the --no-alt-screen CLI flag to force "never" mode.
+alternate_screen = "auto"
 ```
 
 > [!NOTE]
@@ -1053,6 +1065,7 @@ Valid values:
 | `tui.scroll_wheel_tick_detect_max_ms`            | number                                                            | Auto-mode threshold (ms) for promoting a stream to wheel-like behavior (default: 12).                                           |
 | `tui.scroll_wheel_like_max_duration_ms`          | number                                                            | Auto-mode fallback duration (ms) used for 1-event-per-tick terminals (default: 200).                                            |
 | `tui.scroll_invert`                              | boolean                                                           | Invert mouse scroll direction in TUI2 (default: false).                                                                         |
+| `tui.alternate_screen`                           | `auto` \| `always` \| `never`                                     | Alternate screen mode in TUI2 (default: `auto`). Use `never` or `--no-alt-screen` for Zellij scrollback.                        |
 | `hide_agent_reasoning`                           | boolean                                                           | Hide model reasoning events.                                                                                                    |
 | `check_for_update_on_startup`                    | boolean                                                           | Check for Codex updates on startup (default: true). Set to `false` only if updates are centrally managed.                       |
 | `show_raw_agent_reasoning`                       | boolean                                                           | Show raw reasoning (when available).                                                                                            |