›_ Codex Issues
Codex Issues / #14661

Feature: transparent_background option to preserve terminal transparency

Open 💬 5 comments Opened Mar 14, 2026 by douglance
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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 ↗

5 Comments

github-actions[bot] contributor · 5 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • ##12912
  • ##12986
  • ##13012

Powered by Codex Action

Visio-Vanitas · 4 months ago

Sorry for the noise here. I ran into the same issue myself, so I put together a patch on my fork, but GitHub is preventing me from opening a PR because pull requests to openai/
codex are limited to repository collaborators.

The implementation is available here:

  • Fork: Visio-Vanitas/codex
  • Branch: anon/tui-transparent-background
  • Commit: ef4ce5fbe (add tui transparent background option)

This change adds a tui.transparent_background option to the Rust TUI so major surfaces can omit explicit background fills and terminal transparency can show through when
supported. It also preserves diff foreground readability in transparent mode and includes tests/snapshots.

Validated with:

  • cargo fmt --all
  • cargo clippy -p codex-config -p codex-core -p codex-tui --tests --all-targets -- -D warnings
  • cargo test -p codex-core tui_transparent_background -- --nocapture
  • cargo test -p codex-tui transparent_background -- --nocapture

If this direction looks good, a maintainer could open a PR from this branch or cherry-pick the commit.

joverarm · 4 months ago

The text with background color is generally hard to read (green on green, red on red for diffs for example). This is not an exotic problem with transparent terminal windows. This affects also users that use a plain terminal emulator without any transparency.

Unfortunately all "duplicates" which complain about the background color being set since 0.105 have been closed without the problem being resolved.

This is not a terminal emulation issue. This is a codex issue. I fully support the suggested fix, except that I would vote to set the default to true which was the pre 0.105 behavior which everyone was happy with. The new behavior with background colors is _broken_.

Can this please be escalated to a defect. This is not an enhancement request.

Visio-Vanitas · 4 months ago

I would suggest revisiting /theme and expanding it a bit, similar to some of the previously closed issues such as #12749. I may be missing some context on why those were closed, but this still feels like a reasonable direction to explore.

I implemented a local prototype to illustrate this idea and pushed it to my branch here:

The current behavior in my prototype is:

  • /theme opens a secondary theme menu instead of jumping directly into syntax theme selection
  • /theme syntax opens the syntax theme picker
  • /theme background opens a background mode picker
  • background mode is persisted in config through [tui].background_mode

For background behavior, the modes are currently defined as:

  • auto: keep Codex default behavior
  • opaque: always paint Codex panel and diff backgrounds
  • classic: preserve normal UI/panel backgrounds while restoring the older diff style
  • transparent: avoid painting explicit panel and diff backgrounds

I tested this locally on my Mac, and the prototype works well in practice. In particular, I verified:

  • the new /theme menu flow works as expected
  • /theme syntax and /theme background both dispatch correctly
  • background mode changes persist correctly in config
  • classic and transparent both improve readability for transparent terminal setups
  • the implementation builds and passes the relevant local tests

Validation used for the prototype:

``bash
cargo test -p codex-core tui_background_mode
cargo test -p codex-core config_schema_matches_fixture
cargo test -p codex-tui classic_
cargo test -p codex-tui background_transparency_enabled_follows_mode
cargo test -p codex-tui slash_theme_background_opens_background_mode_picker
cargo check -p codex-config -p codex-core -p codex-tui
``
I have attached a screenshot below to show the general direction. I hope this is useful:

<img width="1920" height="1080" alt="Image" src="https://github.com/user-attachments/assets/5b5562b7-ca0c-4de5-83d7-612236660b5e" />

ekwoodrich · 2 months ago

This is a very frustrating issue that is also still occurring on the built-in ChromeOS terminal app and making diffs unreadable.