TUI: set DECSET 2031 so an in-place terminal theme change updates the composer colours
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.5k
- PR merge metrics
- PR metrics pending
Description
What variant of Codex are you using?
CLI (codex-cli 0.147.0, macOS arm64)
What feature would you like to see?
Codex reads the terminal's foreground and background once at startup with OSC 10/11 and holds that answer for the process lifetime. The discussion in #18942 is about restoring a re-query on FocusGained. That covers a user switching macOS appearance while Codex sits in a background window, but it cannot cover a terminal that changes its own colours while its window keeps focus, because there is no focus transition to hang the re-query on.
DECSET 2031 is the mechanism for that case:
- The application subscribes with
CSI ? 2031 h, and unsubscribes withCSI ? 2031 lon shutdown. - The terminal then sends
CSI ? 997 ; 1 nwhen it becomes dark andCSI ? 997 ; 2 nwhen it becomes light, whenever its colour scheme changes for any reason. - The report is a prompt to re-ask rather than the news itself, so the handler is just "re-issue the OSC 10/11 probe" and reuses whatever probe path the
FocusGainedfix lands on. The 1/2 payload only says which direction it moved.
This matters for every terminal whose theme is its own rather than the OS's: Ghostty and WezTerm configs, iTerm2 profiles, and any host app with its own palette. Concretely, in Threading, a macOS terminal I maintain that hosts agent CLIs and owns its own themes, a user switching the app theme from a dark one to a light one leaves a running Codex painting a #393939 composer plate with #CFCFCF ink onto a #FFFFFF background, and there is no focus change anywhere in that interaction. Quitting and resuming the session is the only recovery.
Claude Code subscribes to 2031 and re-themes live under the same theme switch. strings on the Codex 0.147.0 binary contains no 2031, so a terminal that emits the report has nothing Codex can hear.
Additional information
Measured against 0.147.0 in a bare PTY (no tmux, no SSH, no emulator), harness and results in https://github.com/openai/codex/issues/18942: exactly one OSC 10/11 query per process, at startup, and none afterwards under focus events, keyboard input, window resize or SIGWINCH.
2031 originates in Contour's terminal spec and is implemented by Ghostty, WezTerm, foot and others, so the report arrives from real terminals today.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the existing OSC 10/11 probe and the FocusGained handling mentioned in the issue, then find the terminal event and shutdown paths. Use the PTY harness and results linked from #18942 to check behavior. Done means DECSET 2031 is subscribed and unsubscribed correctly, reports trigger the existing probe path, and an in-place terminal theme change updates the composer colors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100