feat(tui): add system dark/light mode matching

[justinlevinedotme]

Summary

Adds an option to automatically sync TUI theme mode with OS appearance.

Resolves #9697

Demo:

CleanShot.2026-01-20.at.15.03.26.mp4

Changes

• Add getOSDarkMode() function for cross-platform OS dark mode detection:
  • macOS: defaults read -g AppleInterfaceStyle
  • Windows: Registry query for AppsUseLightTheme
  • Linux: GNOME/KDE detection with terminal fallback
• Add "Match system dark/light mode" toggle command in System category
• Poll OS appearance every 3 seconds when enabled
• Persist setting to kv.json as auto_mode_enabled (off by default)

Implementation Notes

• Opt-in by default - feature is disabled until user explicitly enables it
• Dynamic command title - shows "Stop matching..." when enabled
• Works with any theme that has light/dark variants (e.g., github, catppuccin, rosepine)
• The special system theme derives colors from terminal palette, so light/dark switching doesn't apply to it

Testing Checklist

• macOS: Tested dark/light mode switching
• Windows: Verify registry query works correctly
• Linux (GNOME): Verify gsettings detection works
• Linux (KDE): Verify kreadconfig5 detection works

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search, I found one potentially related PR:

Related PR:

• feat(tui): add appearance setting with dark/light/system modes #7182 - feat(tui): add appearance setting with dark/light/system modes

This PR appears to be addressing similar functionality for TUI appearance/theme mode management. It may be implementing a related or overlapping feature for system dark/light mode support. You should review this PR to understand if it's a duplicate or if these PRs address different aspects of the same feature.

[disrupted]

commenting on this because I would really like to see this feature too. there is however a new standardised way to get the terminal appearance. https://github.com/contour-terminal/contour/blob/master/docs/vt-extensions/color-palette-update-notifications.md#adoption-state
It uses the new CSI ? 996 n query which works cross-platform on supported terminal emulators.

[hugodemenez]

Hi @justinlevinedotme!

I was searching for a performant and elegant way to solve this issue.

Your solution #9719 works great!

I would like to raise a question: I am not sure polling for the system theme every 3 seconds is really performant.

Isn’t there a better way? Can’t we listen to the system preferences directly, like we do with media queries on the web?

[hugodemenez]

Looks like #7182 is trying to achieve the same feature with 2s polling longer

[disrupted]

polling is definitely not the preferred way to implement this. instead we should enable DSR (device status report) messages for color palette updates. the link I shared in my previous comment explains this. then we are subscribed to notifications for when the appearance changes and can act directly

[hugodemenez]

@disrupted did you try implementing this?

[disrupted]

I think it would require some sort of feedback on this topic from the maintainers before starting actual work on it. this repo is currently getting flooded by PRs without prior planning (most of these will never get merged). I would not want to invest effort into this before a green light

[justinlevinedotme]

I think it would require some sort of feedback on this topic from the maintainers before starting actual work on it. this repo is currently getting flooded by PRs without prior planning (most of these will never get merged). I would not want to invest effort into this before a green light

100%, polling is used in other parts of app, so that's why I used it here.

I also was trying to not add too much to the app, using existing systems where possible.