Feature: transparent_background option to preserve terminal transparency

Open 💬 5 comments Opened Mar 14, 2026 by douglance

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() → return Style::default() (same as when terminal_bg is None)
  • resolve_diff_backgrounds() → return ResolvedDiffBackgrounds::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:

  1. codex-rs/core/src/config/types.rs — add field to Tui struct
  2. codex-rs/core/src/config/mod.rs — map to Config
  3. codex-rs/tui/src/style.rs — early return when transparent
  4. codex-rs/tui/src/diff_render.rs — skip backgrounds when transparent
  5. codex-rs/tui/src/lib.rs — wire up at startup

Happy to contribute a PR if invited.

View original on GitHub ↗

This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗