Windows Desktop: focused window shows black / wallpaper-colored transparent border unless opaqueWindows is enabled

Resolved 💬 3 comments Opened May 31, 2026 by zyzhen Closed Jun 12, 2026

What happened?

After updating Codex Desktop on Windows, clicking/focusing the Codex window causes the outer window/background area to render as black or as a wallpaper-colored translucent region instead of the expected solid Codex surface.

This reproduced on two Windows machines. On one machine, after restoring the Windows theme/wallpaper settings to their original state, the artifact changed from a black border to a blue wallpaper-colored translucent border, which suggests the window backdrop is letting the desktop/Mica background bleed through.

Environment

  • Codex Desktop: 26.527.3686.0
  • OS tested in detail: Windows 10 Enterprise, build 19045, 64-bit
  • Windows app theme: light apps with dark system shell (AppsUseLightTheme=1, SystemUsesLightTheme=0)
  • Windows transparency effects enabled

Steps to reproduce

  1. Launch Codex Desktop on Windows.
  2. Open any conversation.
  3. Click/focus the Codex window.
  4. Observe the outer window/sidebar/background region around the main content.

Expected behavior

The Codex window should render with an opaque, solid app chrome/background. Focusing the window should not reveal a black backdrop or the desktop wallpaper color around the content.

Actual behavior

When the window is focused, parts of the Codex window background appear black or translucent/wallpaper-colored. The effect is visible around the window chrome/sidebar/main content boundary.

Workaround found

Setting both desktop chrome themes to use opaque windows fixes the issue locally:

[desktop]
appearanceLightChromeTheme = { accent = "#339cff", contrast = 45, fonts = { code = "", ui = "" }, ink = "#1a1c1f", opaqueWindows = true, semanticColors = { diffAdded = "#00a240", diffRemoved = "#ba2623", skill = "#924ff7" }, surface = "#ffffff" }
appearanceDarkChromeTheme = { accent = "#339cff", contrast = 60, fonts = { code = "", ui = "" }, ink = "#ffffff", opaqueWindows = true, semanticColors = { diffAdded = "#40c977", diffRemoved = "#fa423e", skill = "#ad7bf9" }, surface = "#181818" }

After restarting Codex with the above config, the border/transparency artifact disappears.

Suspected cause

This looks like a Windows Desktop regression in the transparent/Mica window backdrop path. In the app bundle, the Windows non-opaque path appears to use a transparent background with backgroundMaterial: "mica"; forcing opaqueWindows=true avoids that path and renders the window with a solid surface.

View original on GitHub ↗

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