Feature: transparent_background option to preserve terminal transparency
Problem
Codex TUI paints opaque background tints on message bubbles, composer panels, and diff lines. This breaks terminal transparency, blur effects, and image backgrounds for users who rely on those features.
The transparent codepaths already exist
The codebase already implements this philosophy in multiple places:
Syntax highlighting (highlight.rs):
// Intentionally skip background to avoid overwriting terminal bg.
The convert_style function deliberately omits backgrounds from syntax themes so the terminal's own background shows through.
Message styles (style.rs):
pub fn user_message_style_for(terminal_bg: Option<(u8, u8, u8)>) -> Style {
match terminal_bg {
Some(bg) => Style::default().bg(user_message_bg(bg)),
None => Style::default(), // <-- no background
}
}
When terminal_bg is None, both user_message_style_for and proposed_plan_style_for already return Style::default() — no background tint at all.
Diff rendering (diff_render.rs):
//! ANSI-16 mode always uses foreground-only styling regardless of theme scope backgrounds.
The ANSI-16 fallback path returns foreground-only styles (Style::default().fg(Color::Green) / Color::Red) with no backgrounds, and fallback_diff_backgrounds returns ResolvedDiffBackgrounds::default() for ANSI-16.
Proposal
Add a single boolean config option following the existing animations / show_tooltips pattern:
[tui]
transparent_background = true # default: false
When enabled, the TUI would route to the existing background-free codepaths:
user_message_style()/proposed_plan_style()→ returnStyle::default()(same as whenterminal_bgisNone)resolve_diff_backgrounds()→ returnResolvedDiffBackgrounds::default()(same as ANSI-16 fallback)- Gutter backgrounds skipped (same pattern)
Default behavior is completely unchanged. The option defaults to false.
Scope
~50 lines across 5 files:
codex-rs/core/src/config/types.rs— add field toTuistructcodex-rs/core/src/config/mod.rs— map toConfigcodex-rs/tui/src/style.rs— early return when transparentcodex-rs/tui/src/diff_render.rs— skip backgrounds when transparentcodex-rs/tui/src/lib.rs— wire up at startup
Happy to contribute a PR if invited.
This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗