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

[hjanuschka]

Fixes #2558

Codex uses alternate screen mode (CSI 1049) which, per xterm spec, doesn't support scrollback. Zellij follows this strictly, so users can't scroll back through output.

Changes:

• Add tui.alternate_screen config: auto (default), always, never
• Add --no-alt-screen CLI flag
• Auto-detect Zellij and skip alt screen (uses existing ZELLIJ env var detection)

Usage:

# CLI flag
codex --no-alt-screen

# Or in config.toml
[tui]
alternate_screen = "never"

With default auto mode, Zellij users get working scrollback without any config changes.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[hjanuschka]

I have read the CLA Document and I hereby sign the CLA

[hjanuschka]

recheck

[etraut-openai]

Thanks for the diagnosis and the PR.

I'm not that excited about exposing a configuration knob for this. We will probably look for a better solution. However, your diagnosis is valuable regardless.

I'll need to discuss with my colleagues to decide what to do here since I'm personally not that familiar with the TUI code. Most of the codex team is on holiday break, so it may be a week or more before we have a chance to discuss and make a decision.

[hjanuschka]

Hey, totally understand the hesitation on the config knob - I was not thrilled about it either tbh.

I spent some time digging into this to see if there is a better way. Here is what I found:

On Zellij side: They intentionally disabled scrollback in alternate screen (zellij-org/zellij#1032) to follow the xterm spec strictly. This was not a bug - it is by design. The xterm spec says alternate screen buffers should not have scrollback, and Zellij follows that. There is no config option to change it and unlikely to ever be one.

How others handle it: tmux has alternate-screen off and terminal-overrides to disable smcup/rmcup. kitty has plugins for secondary screen access. But these are all variations of "don't use alternate screen" - there is no magic way to have both full-screen alt mode AND scrollback.

Looking at TUI2: I noticed the transcript-based architecture already prints history to scrollback on exit/suspend, which is great - but that does not help when you want to scroll back during the session without quitting. And while Ctrl+T opens the transcript pager, it is not the same as natural scrollback - you have to context-switch into a separate view.

So realistically the options are:

1. Detect Zellij and skip alternate screen (what this PR does)
2. Live with the Ctrl+T workaround (not ideal)

I am happy to strip out the config options entirely and just make it pure auto-detection if that feels cleaner? No user-facing knobs, just "it works in Zellij" silently.

No rush on this - enjoy the holidays! Just wanted to share what I found in case it is useful for the discussion.

[imsnif]

Hey, I hope you don't mind me chiming in. I came upon this PR because this issue has been reported quite a few times on the Zellij side.

@hjanuschka 's analysis is accurate. This is one of those "you can't have your cake and eat it" sort of situations.

I don't know your requirements or time/workforce availability - but I think your utopian solution would be to implement scrollback on your own. If you control all the contents in the scrollback (and don't need to include output from arbitrary programs) this should be fairly straightforward. Otherwise, you can use some sort of off-the-shelf terminal emulation solution to do it for you.

Hope this helps.

[RickTorresJr]

Just want to provide additional context on how other LLM CLI tools handle this:

• Gemini CLI :
  • Has config switch ui.useAlternateBuffer (default: false)
  • They default to no alternate buffer with opt-in for users who want it
• Claude Code:
  • Avoids the issue entirely by not using a TUI/alternate screen buffer
  • Output goes to normal terminal stream so multiplexer scroll back works natively