Can't enter alternate screen buffer

One focused triage note from a local repo read: the config path appears to be fairly direct: config.tui_alternate_screen is passed through determine_alt_screen_mode(), and anything other than AltScreenMode::Never enables alt-screen unless --no-alt-screen is set. The actual enter path then calls EnterAlternateScreen in codex-rs/tui/src/tui.rs, but currently ignores the crossterm result.

That makes this issue especially useful if the reporter can add:

• the exact ~/.codex/config.toml snippet, including whether it is under [tui]
• whether codex --config tui.alternate_screen=always changes behavior
• echo $TERM, infocmp | grep -E "smcup|rmcup", and whether tmux/screen has terminal overrides that disable alternate-screen switching
• whether this reproduces outside tmux/screen in the same terminal emulator

If this turns out to be terminal capability related, a small product improvement might be to stop swallowing EnterAlternateScreen/LeaveAlternateScreen failures and surface a warning in codex doctor or startup diagnostics when always is configured but the terminal does not actually switch buffers.

I have the exact same issue on Mac.

• Codex CLI Version: 0.136.0
• Operating System: MacOS 26.5
• Terminal Emulator: Tried on Iterm2, Ghostty and the default Apple Terminal
• TERM Variable: xterm-256color

I have set tui.alternate_screen to "always" in ~/.codex/config.toml as well. Running codex --config tui.alternate_screen=always had no effect, the issue still occurs. infocmp | grep -E "smcup|rmcup" - both present.

I was not using screen/tmux/zellij. My Copilot CLI and Claude code and other programs are able to use alternate screen in the same terminal, so i don't think it's a terminal capability related issue.

This my tui settings in ~/.codex/config.toml , if it helps.

[tui]
alternate_screen = "always"
session_picker_view = "comfortable"
status_line = [
  "codex-version",
  "model-with-reasoning",
  "context-window-size",
  "used-tokens",
  "context-used",
  "five-hour-limit",
  "weekly-limit",
  "current-dir",
  "git-branch",
  "thread-title",
]
status_line_use_colors = true
terminal_title = ["activity", "thread-title"]
theme = "monokai-extended"
pet = "codex"

[tui.model_availability_nux]
"gpt-5.5" = 4

[features]
js_repl = false
terminal_resize_reflow = false

I can reproduce this on codex-cli 0.144.6 on macOS 26.3.2.

Terminals tested:

• Ghostty 1.3.1
• Apple Terminal

Configuration:

[tui]
alternate_screen = "always"

I verified that the configuration is recognized: codex --strict-config doctor --json reports config.load: ok. These were fresh Codex sessions, with no --no-alt-screen flag and no tmux, Zellij, or screen involved.

In both terminals, scrolling moves the entire Codex UI, including the composer/input box, as if Codex were still rendering in the primary terminal buffer. Setting alternate_screen = "always" does not change the behavior.

This suggests the issue is still present in 0.144.6 and is not specific to a particular macOS terminal emulator.

Follow-up after additional iTerm2 testing (2026-07-22): this owned-screen series correctly establishes a retained full-screen viewport, pinned composer, paused follow state, and jump control, but its current fixed-step virtual wheel scroller does not yet match Claude Code’s mature fullscreen scrolling behavior. Please treat this branch as an experimental prototype rather than a production-ready parity claim. For natural iTerm2 scrolling and selection today, use the isolated native-scrollback branch: https://github.com/Andrewwilliamross/codex/tree/agent/fix-iterm2-native-scrollback.

I confirmed this is not a missing terminal capability: the current tui.alternate_screen = "always" path does not give Codex ownership of a retained full-screen viewport.

I ported OpenAI’s public fcoury/owned-alt-screen-text-selection prototype onto current main, preserving Felipe Coury’s authorship, and completed the user-facing interaction:

• always: Codex physically owns the alternate screen and retains the conversation viewport
• auto: existing overlay-only inline behavior remains unchanged
• never / --no-alt-screen: native terminal scrollback remains available
• fixed composer at the bottom
• PageUp/PageDown and mouse-wheel transcript navigation
• scrolling upward pauses automatic bottom-following
• a clickable Jump to bottom (click) ↓ control restores the latest output and follow state
• draft composer text remains intact while scrolled

Experimental branch: https://github.com/Andrewwilliamross/codex/tree/agent/fix-iterm2-scrollback

The owned-screen foundation is split into the original-author commits 642345cdf339 through f653664b5586; the jump control and current-main compatibility are in dfa4ccd3d19e.

Functional verification: 3,259 codex-tui tests passed, 4 skipped, package fixer/formatter passed, and the basic scroll/pause/draft/click/resume flow passed manual iTerm2 testing. Further human testing identified the scroll-feel limitation described above.

If this architecture matches the intended semantics for always, I’m happy to continue refining it or split the series however maintainers prefer.