fix(tui): default alternate_screen to never

Keep the welcome splash inline in the host terminal. The shell prompt
stays above the app unless the user opts in via config or --alternate-screen.

Co-authored-by: Mathis <echobt@users.noreply.github.com>

Author: cursoragent

CHANGELOG.md

@@ -10,8 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 
 ### Changed
-### Changed
-- The TUI enters the **alternate screen** on interactive start so the host shell prompt is hidden. Opt out with `[tui] alternate_screen = false`.
+- The TUI runs **inline** by default (`alternate_screen` never). It does not enter the alternate screen on start; the real shell prompt stays in scrollback above the app. Opt in with `cortex --alternate-screen` or `[tui] alternate_screen = true`.
 - Empty-session splash is `Welcome to Cortex, the coding agent CLI` plus `v{package version} · / commands · @ files · ! shell · & cloud`. After the first user turn the splash is dropped (composer + footer only). No mascot, no painted `> cortex` shell lines.
 - Composer lock: empty is `> ` + white block at input col 0 + dim `Plan, search, build anything` after that cell (never a white rect after the placeholder). Blink-off (~530ms) hides the block so the placeholder starts at col 0. Typed copy is `#F5F5F5` with the block at the caret.
 

docs/configuration/config.md

@@ -150,9 +150,9 @@ max_bytes = 10000000
 [tui]
 animations = true
 notifications = true
-# Enter the alternate screen (default). Set false to stay inline in the host
-# terminal. Equivalent CLI flag: --alternate-screen
-alternate_screen = true
+# Stay inline in the host terminal (default / never). Set true only to take
+# over the alternate screen buffer. Equivalent CLI flag: --alternate-screen
+alternate_screen = false
 
 [tui.theme]
 name = "dark"              # dark, light, ocean_dark, monokai

docs/guides/tui.md

@@ -16,22 +16,27 @@ cortex --profile work           # load a profile from config.toml
 The TUI needs a terminal on both stdin and stdout. If either is redirected it
 refuses to start and points you at [`cortex run` or `cortex exec`](exec.md).
 
-The session starts on the **alternate screen**, so the host shell prompt
-and the typed `cortex` command are hidden. The welcome splash is two lines:
+The session runs **inline** in the host terminal (`alternate_screen` is
+never on by default). Cortex does not enter the alternate screen buffer
+on start, so your shell prompt and the typed command stay visible above
+the app. The welcome splash is two lines:
 `Welcome to **Cortex**, the coding agent CLI` then
 `v{version} · / commands · @ files · ! shell · & cloud`. It does
 not paint a fake shell prompt or working directory. After the first user
 turn the splash is dropped; an empty session is composer and footer only.
 
-To stay inline in the host terminal instead:
+To opt in to a full-screen alternate buffer:
 
 ```bash
-# config.toml
-[tui]
-alternate_screen = false
+cortex --alternate-screen
 ```
 
-`--alternate-screen` forces the alternate buffer on (already the default).
+or in `~/.cortex/config.toml`:
+
+```toml
+[tui]
+alternate_screen = true
+```
 
 ## The session view
 

docs/reference/cli.md

@@ -32,7 +32,7 @@ A positional prompt seeds that session. Without a terminal, use
 | `--add-dir <DIR>` | Extra writable directory; repeatable |
 | `-i`, `--image <PATH>` | Attach an image to the initial prompt |
 | `--search` | Enable web search |
-| `--alternate-screen` | Force the alternate screen buffer (already the default). Set `[tui] alternate_screen = false` to stay inline. |
+| `--alternate-screen` | Opt in to the alternate screen buffer. Default is inline (`never`): the host shell prompt stays visible above the app. Same as `[tui] alternate_screen = true`. |
 | `--max-agent-threads <N>` | Concurrent agent threads |
 | `--max-tool-threads <N>` | Concurrent tool executions |
 | `--command-timeout <SECONDS>` | Shell command timeout |

src/cortex-cli/src/cli/args.rs

@@ -208,8 +208,9 @@ pub struct InteractiveArgs {
     #[arg(long = "search", default_value_t = false, help_heading = "Features")]
     pub web_search: bool,
 
-    /// Force the alternate screen buffer. Default is already on; use
-    /// `[tui] alternate_screen = false` to stay inline in the host terminal.
+    /// Opt in to the alternate screen buffer. Default is **never** (inline):
+    /// the host shell prompt stays visible above the app. Same as
+    /// `[tui] alternate_screen = true`.
     #[arg(
         long = "alternate-screen",
         default_value_t = false,
@@ -1197,7 +1198,7 @@ mod tests {
         let cli = Cli::try_parse_from(["cortex"]).expect("should parse");
         assert!(
             !cli.interactive.alternate_screen,
-            "the flag is force-on; config already enables alt-screen"
+            "the flag is opt-in; default TUI is inline (never alt-screen)"
         );
         let cli = Cli::try_parse_from(["cortex", "--alternate-screen"])
             .expect("should parse --alternate-screen");

src/cortex-engine/src/config/mod.rs

@@ -79,7 +79,7 @@ pub struct Config {
     pub disable_paste_burst: bool,
     /// Enable TUI animations.
     pub animations: bool,
-    /// Opt in to the alternate screen buffer. Default is inline (false).
+    /// Opt in to the alternate screen buffer. Default is inline (`never`).
     pub alternate_screen: bool,
     /// Current agent profile.
     pub current_agent: Option<String>,
@@ -121,7 +121,7 @@ impl Default for Config {
             check_for_update_on_startup: true,
             disable_paste_burst: false,
             animations: true,
-            alternate_screen: true,
+            alternate_screen: false,
             current_agent: None,
             permission: PermissionConfig::default(),
             small_model: None, // Auto-detected based on available providers
@@ -246,7 +246,7 @@ impl Config {
                 toml.tui
                     .as_ref()
                     .map(|t| t.alternate_screen)
-                    .unwrap_or(true)
+                    .unwrap_or(false)
             }),
             current_agent: toml.current_agent,
             permission: toml.permission,
@@ -330,17 +330,24 @@ mod alternate_screen_tests {
     use types::ConfigToml;
 
     #[test]
-    fn from_toml_enables_alternate_screen_by_default() {
+    fn from_toml_keeps_alternate_screen_off_by_default() {
+        assert!(
+            !Config::default().alternate_screen,
+            "default must be inline (never alt-screen)"
+        );
         let toml: ConfigToml = toml::from_str("").unwrap();
         let cfg = Config::from_toml(toml, ConfigOverrides::default(), PathBuf::from("/tmp"));
-        assert!(cfg.alternate_screen);
+        assert!(
+            !cfg.alternate_screen,
+            "default must be inline (never alt-screen)"
+        );
     }
 
     #[test]
-    fn from_toml_honors_tui_alternate_screen_opt_out() {
-        let toml: ConfigToml = toml::from_str("[tui]\nalternate_screen = false\n").unwrap();
+    fn from_toml_honors_tui_alternate_screen_opt_in() {
+        let toml: ConfigToml = toml::from_str("[tui]\nalternate_screen = true\n").unwrap();
         let cfg = Config::from_toml(toml, ConfigOverrides::default(), PathBuf::from("/tmp"));
-        assert!(!cfg.alternate_screen);
+        assert!(cfg.alternate_screen);
     }
 
     #[test]

src/cortex-engine/src/config/types.rs

@@ -327,8 +327,8 @@ pub enum ReasoningSummary {
 pub struct TuiConfig {
     #[serde(default = "default_animations")]
     pub animations: bool,
-    /// Interactive start always uses the alternate screen so the host
-    /// shell prompt is hidden. Set `false` only to stay inline.
+    /// Default is **never** (inline). The host shell prompt stays visible
+    /// above the app. Set `true` only to take over the alternate screen.
     #[serde(default = "default_alternate_screen")]
     pub alternate_screen: bool,
     #[serde(default)]
@@ -341,7 +341,7 @@ impl Default for TuiConfig {
     fn default() -> Self {
         Self {
             animations: true,
-            alternate_screen: true,
+            alternate_screen: false,
             notifications: NotificationsConfig::default(),
             theme: ThemeConfig::default(),
         }
@@ -353,7 +353,7 @@ fn default_animations() -> bool {
 }
 
 fn default_alternate_screen() -> bool {
-    true
+    false
 }
 
 /// Theme configuration.
@@ -488,17 +488,20 @@ mod tui_alternate_screen_tests {
     use super::*;
 
     #[test]
-    fn tui_alternate_screen_defaults_on() {
-        assert!(TuiConfig::default().alternate_screen);
+    fn tui_alternate_screen_defaults_never() {
+        assert!(
+            !TuiConfig::default().alternate_screen,
+            "default must be inline (never alt-screen)"
+        );
 
         let parsed: ConfigToml = toml::from_str("").expect("empty config");
         assert!(parsed.tui.is_none());
 
         let parsed: ConfigToml = toml::from_str("[tui]\n").expect("empty tui table");
-        assert!(parsed.tui.expect("tui").alternate_screen);
+        assert!(!parsed.tui.expect("tui").alternate_screen);
 
         let parsed: ConfigToml =
-            toml::from_str("[tui]\nalternate_screen = false\n").expect("opt-out");
-        assert!(!parsed.tui.expect("tui").alternate_screen);
+            toml::from_str("[tui]\nalternate_screen = true\n").expect("opt-in");
+        assert!(parsed.tui.expect("tui").alternate_screen);
     }
 }

src/cortex-tui/src/runner/app_runner/runner.rs

@@ -79,8 +79,9 @@ impl AppRunner {
 
     /// Create a new app runner with the given configuration.
     ///
-    /// The TUI starts on the **alternate screen** so the host shell prompt
-    /// is hidden. Set `tui.alternate_screen = false` to stay inline.
+    /// The TUI starts **inline** (never alternate screen) so the host shell
+    /// prompt stays visible above the app. Set `tui.alternate_screen = true`
+    /// to opt in to the alternate screen buffer.
     ///
     /// # Arguments
     ///
@@ -1053,17 +1054,20 @@ mod tests {
     fn test_app_runner_terminal_options() {
         let config = Config::default();
 
-        // Default: alternate screen
+        // Default: inline (never alternate screen)
         let runner = AppRunner::new(config.clone());
+        assert!(
+            !runner.terminal_options.alternate_screen,
+            "default must be inline (never alt-screen)"
+        );
+        assert!(!runner.terminal_options.clear_on_start);
+
+        let mut fullscreen = config.clone();
+        fullscreen.alternate_screen = true;
+        let runner = AppRunner::new(fullscreen);
         assert!(runner.terminal_options.alternate_screen);
         assert!(runner.terminal_options.clear_on_start);
 
-        let mut inline = config.clone();
-        inline.alternate_screen = false;
-        let runner = AppRunner::new(inline);
-        assert!(!runner.terminal_options.alternate_screen);
-        assert!(!runner.terminal_options.clear_on_start);
-
         // Custom options
         let custom_options = TerminalOptions::new()
             .alternate_screen(false)

src/cortex-tui/src/runner/login_screen.rs

@@ -1,7 +1,7 @@
 //! Login Screen
 //!
-//! Enters the alternate screen so the host shell prompt is hidden while
-//! the picker is open.
+//! Inline TUI (no alternate screen) so the host shell prompt stays in
+//! scrollback above the picker.
 
 use std::io::stdout;
 use std::path::{Path, PathBuf};
@@ -191,26 +191,19 @@ impl LoginScreen {
     pub async fn run(&mut self) -> Result<LoginResult> {
         crossterm::terminal::enable_raw_mode()?;
         let mut stdout = stdout();
-        crossterm::execute!(
-            stdout,
-            crossterm::terminal::EnterAlternateScreen,
-            crossterm::event::EnableMouseCapture,
-            crossterm::terminal::Clear(crossterm::terminal::ClearType::All),
-        )?;
+        crossterm::execute!(stdout, crossterm::event::EnableMouseCapture)?;
 
         let backend = CrosstermBackend::new(stdout);
         let mut terminal = Terminal::new(backend)?;
-        terminal.hide_cursor()?;
 
         let result = self.run_loop(&mut terminal).await;
 
-        let _ = crossterm::execute!(
+        crossterm::terminal::disable_raw_mode()?;
+        crossterm::execute!(
             terminal.backend_mut(),
             crossterm::event::DisableMouseCapture,
-            crossterm::terminal::LeaveAlternateScreen,
-        );
-        let _ = crossterm::terminal::disable_raw_mode();
-        let _ = terminal.show_cursor();
+        )?;
+        terminal.show_cursor()?;
 
         result
     }

src/cortex-tui/src/runner/terminal.rs

@@ -116,8 +116,7 @@ impl Drop for TerminalGuard {
 /// Configuration options for terminal initialization.
 ///
 /// This struct uses the builder pattern to allow flexible configuration
-/// of terminal features. All features are enabled by default for the
-/// best user experience.
+/// of terminal features. Alternate screen is **off** by default (inline).
 ///
 /// # Example
 ///
@@ -147,26 +146,26 @@ pub struct TerminalOptions {
 
 impl Default for TerminalOptions {
     fn default() -> Self {
-        // Interactive start uses the alternate screen by default.
+        // Interactive start is inline: never enter the alternate screen.
         Self {
-            alternate_screen: true,
+            alternate_screen: false,
             mouse_capture: true,
             bracketed_paste: true,
             title: Some("Cortex".to_string()),
-            clear_on_start: true,
+            clear_on_start: false,
         }
     }
 }
 
 impl TerminalOptions {
     /// Create a new `TerminalOptions` with default settings.
     ///
-    /// Default settings enter the alternate screen so the host shell is hidden:
-    /// - Alternate screen: on (set `tui.alternate_screen = false` to stay inline)
+    /// Default settings stay **inline** (never alternate screen):
+    /// - Alternate screen: off (set `[tui] alternate_screen = true` to opt in)
     /// - Mouse capture: enabled
     /// - Bracketed paste: enabled
     /// - Title: "Cortex"
-    /// - Clear on start: on
+    /// - Clear on start: off
     pub fn new() -> Self {
         Self::default()
     }
@@ -266,10 +265,10 @@ pub struct CortexTerminal {
 }
 
 impl CortexTerminal {
-    /// Create a new terminal with default full-screen mode.
+    /// Create a new terminal with default **inline** mode (no alternate screen).
     ///
     /// This initializes the terminal with:
-    /// - Alternate screen buffer
+    /// - Inline buffer (host shell prompt stays visible above the app)
     /// - Mouse capture
     /// - Bracketed paste mode
     /// - Hidden cursor
@@ -987,11 +986,14 @@ mod tests {
     #[test]
     fn test_terminal_options_default() {
         let options = TerminalOptions::default();
-        assert!(options.alternate_screen);
+        assert!(
+            !options.alternate_screen,
+            "default must be inline (never alt-screen)"
+        );
         assert!(options.mouse_capture);
         assert!(options.bracketed_paste);
         assert_eq!(options.title, Some("Cortex".to_string()));
-        assert!(options.clear_on_start);
+        assert!(!options.clear_on_start);
     }
 
     #[test]