Skip to content
theme-agent

Platform support

Current platform contract

Section titled “Current platform contract”
Platform Detection Live updates Appearance application User service
macOS NSUserDefaults AppleInterfaceStyle NSDistributedNotificationCenter on the main-thread run loop Reconciles through osascript when effective state differs from observed OS state launchd user agent
Linux XDG desktop portal, with gsettings read fallback Portal SettingChanged signal Detection-only systemd user unit
Windows HKCU AppsUseLightTheme RegNotifyChangeKeyValue watcher thread Detection-only Per-user logon scheduled task

macOS is currently the only backend that applies effective appearance to the host. To avoid write/notification feedback loops, it calls osascript only when the last observed system value differs. An appearance-application failure is logged as a warning; resolution, hooks, and event broadcasts continue.

Linux and Windows detect appearance and report live changes but do not write OS appearance in the current backends.

Deterministic mock backend

Section titled “Deterministic mock backend”

Development and integration tests can replace native detection:

Terminal window
THEME_AGENT_MOCK_SYSTEM=dark theme-agent daemon

Supported variables:

  • THEME_AGENT_MOCK_SYSTEM=light|dark|none selects a static initial system value.
  • THEME_AGENT_MOCK_FILE points to a file polled for live mock changes.
  • THEME_AGENT_MOCK_APPLY_FILE records the most recent appearance the daemon requested from the OS backend.

These controls work on any OS and make state transitions and appearance-application behavior deterministic. For ownership and event flow, continue to Architecture.