Codex iTerm2 Jumps to the Top? Test Raw Output

If Codex CLI jumps to the top of the transcript when a long response finishes in iTerm2, run /raw on before the next comparable response. In the current macOS reproduction, raw output preserved the reader's scroll position while rich output replayed the transcript and moved the viewport to the top. Treat this as a temporary diagnostic and containment step, not a confirmed upstream fix.

This guide applies to a narrow signature: you scroll upward while a long answer is still streaming, remain above the live tail, and the viewport jumps only when the answer completes. It does not cover Codex Desktop thread navigation, a terminal that has discarded old scrollback, or a shell command that is still printing output.

Match the Completion-Time Scroll Jump

Confirm the sequence before changing iTerm2 settings:

1. Codex CLI is running inside iTerm2.

2. A long assistant response is still streaming.

3. You scroll upward to read earlier output and stop away from the live tail.

4. The response finishes.

5. The viewport suddenly moves to the beginning of the replayed transcript.

The August 9 report reproduced this with Codex CLI 0.147.0 and iTerm2 3.6.11 on macOS 26.5.2. The reporter had already enabled both Save lines to scrollback in alternate screen mode and Save lines to scrollback when an app status bar is present. The jump still occurred with and without a Markdown table, so a pipe table was not required for that reproduction.

Use a different path when the symptoms differ:

Do not clear the terminal, delete Codex state, or reset your iTerm2 profile. Those changes remove evidence without testing the rich-output boundary.

Preserve Your Place Before the Next Response

If the current answer contains something you must retain, save it before reproducing the jump. Ask Codex to write the result to a reviewed project file, or copy only the relevant non-secret excerpt. Do not rely on the visible viewport as the only copy of a deployment result, generated command, or external job identifier.

Then note the versions and active mode:

codex --version

Inside Codex, confirm that rich output is active with /raw off. Record the iTerm2 version from iTerm2 > About iTerm2. Also note whether tmux, screen, zellij, SSH, or WSL sits between Codex and the terminal. The selected reproduction used none of those layers, which makes it a useful control rather than proof that every terminal shares the same cause.

If you run codex doctor --json, review the output locally and retain only the fields needed for the report. A full diagnostic can include local paths, provider configuration, and other private details.

Test Raw Output Once

In the active Codex session, enter:

/raw on

Ask for one long, read-only response that is similar in length and structure to the failing response. While it streams, scroll upward and remain there until completion.

Success for this diagnostic means the response completes and iTerm2 keeps the viewport where you left it. The August 9 reporter observed that result in raw mode after rich mode jumped in the same manual scrolling workflow.

Raw mode changes presentation, so it may reduce Markdown rendering and other rich formatting you want. It also does not prove which internal reflow condition caused the jump. Use it when preserving scroll position matters more than rich rendering, and restore the normal presentation later with:

/raw off

If raw mode also jumps, stop treating the current report as a match. Capture the failed A/B result instead of repeating the test or changing several terminal settings at once.

Run a Controlled A/B Reproduction

Use a disposable session with no deployment, database write, or approval waiting in the transcript. Keep the terminal size fixed for both passes.

First, confirm /raw off and give Codex this prompt:

Produce a long read-only explanation with headings, blockquotes, numbered steps, bullet lists, and two fenced code examples. Do not use a Markdown pipe table. Do not run commands or edit files.

Scroll upward while the answer streams and note where the viewport lands when it finishes. Then turn on /raw on, repeat with a comparable prompt, and perform the same scroll action.

Record only these fields:

• Codex CLI version;

• operating system and architecture;

• terminal name and version;

• terminal rows and columns;

• rich or raw mode;

• whether the viewport moved at completion;

• whether a terminal multiplexer, SSH, or WSL was present; and

• the matching upstream issue URL.

One failing rich-output pass and one passing raw-output pass are enough. Repeatedly generating long responses adds noise and can make the transcript itself another variable.

Why Raw Mode Is Useful Evidence

The current issue points to two completion-time paths in Codex 0.147.0 that can rebuild terminal history. The streaming controller can require transcript reflow when a response had a live tail or when the completed message differs from the streamed form. The resize-reflow path can clear and reinsert terminal history while resetting its internal viewport area.

That makes a completion-only jump plausible without blaming iTerm2's ordinary mouse scrolling. It is still an inference from the linked source and reproduction, not an OpenAI root-cause statement.

Raw mode does not simply turn every reflow path off. The issue reporter notes that raw mode changes a Markdown table tail budget, while other completion-difference paths remain possible. A passing raw-mode test narrows the investigation to presentation or reflow behavior, but it does not identify the exact line that failed.

Do Not Apply Unrelated Scroll Fixes

Avoid these shortcuts:

• do not increase iTerm2 scrollback when old lines are already present;

• do not toggle several renderer, alternate-screen, and reflow settings together;

• do not run clear, reset the terminal, or delete Codex session files;

• do not assume a Markdown table is required, because the selected reproduction passed without one;

• do not use a Codex Desktop scroll workaround for this CLI-only completion jump; and

• do not present /raw on as a permanent fix until the upstream issue confirms one.

If the jump affects only an older release, update Codex with the same package manager or installer that owns the current installation, then rerun one controlled pair. Do not mix a version change with terminal-setting changes in the same test.

Report a Useful Result

Add evidence to the matching issue rather than opening a duplicate. The fresh iTerm2 report is the best match when rich output jumps at completion and raw output does not. The older WSL report is useful corroboration for long-session viewport jumps, but it did not provide the same rich-versus-raw control.

Keep prompts, model output, provider details, local paths, and full diagnostics private. A concise A/B matrix with versions and the jump result is more useful than a complete transcript.

Monitor the Fix With Aident Loadout

Start with the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then give your agent a bounded, read-only request:

Check Aident Loadout authentication and Vault status. Discover the current GitHub issue-search Action and Hacker News search Action, inspect both schemas, and preflight them. If the estimates are free, return the state, updated time, labels, comment count, and canonical URL for openai/codex issues 37777 and 22936, plus at most three Hacker News results for Codex terminal scroll jump. Do not create, edit, close, label, comment on, or react to any issue, and do not write to Hacker News.

The measurable result is two current issue records and up to three community signals with no provider write. In the August 9 research snapshot, issue 37777 was open with one comment, issue 22936 was open with eight comments, Hacker News had one adjacent terminal-jump comment but no dedicated exact discussion, and YouTube returned no exact scrolling tutorial.

Set up Aident Loadout and monitor the Codex scroll issue read-only.

Sources

• Codex issue 37777: iTerm2 viewport jumps when rich output completes

• Codex issue 22936: long WSL sessions can jump to the top

• Codex source: completion-time streaming reflow selection

• Codex source: resize reflow clears and rebuilds terminal history

• Codex source: raw-mode table tail behavior

• iTerm2 documentation

Refresh this guide when issue 37777 changes state, a Codex release preserves the viewport anchor in rich output, or /raw on no longer distinguishes the reported failure.