pi-theme-overrides

Auto-switch Pi's dark/light theme based on your system theme for the Pi coding agent.

This package installs a Pi extension that watches your host system appearance and automatically switches Pi between the matching dark and light runtime themes. The bundled palettes intentionally match Pi's default themes; provide user config when you want to override either palette.

What it does

• Automatically switches Pi to dark or light when your system theme changes.
• Applies Pi's default dark / light palettes by default.
• Lets you override either palette with user-provided theme JSON.
• Detects system appearance on macOS, Linux, Windows, WSL, and OrbStack.
• Re-applies on startup and periodically checks for appearance changes.
• Backs off when you choose a non-built-in/custom Pi theme.

Install

From npm after publication:

pi install npm:pi-theme-overrides

From GitHub after a repo/tag exists:

pi install git:github.com/zer09/theme-overrides@v0.1.0

Configuration

~/.pi/agent/theme-overrides/config.json

You can also point at an explicit config file:

PI_THEME_OVERRIDES_CONFIG=/path/to/config.json pi

Example user config:

{
  "enabled": true,
  "fallbackTheme": "dark",
  "pollIntervalMs": 3000,
  "queryTimeoutMs": 1500,
  "themes": {
    "dark": "/absolute/path/to/dark.json",
    "light": "/absolute/path/to/light.json"
  }
}

Relative theme paths in ~/.pi/agent/theme-overrides/config.json are resolved relative to ~/.pi/agent/theme-overrides/. Relative theme paths in PI_THEME_OVERRIDES_CONFIG are resolved relative to that config file's directory. Bundled defaults resolve relative to this package directory.

If no user config exists, the bundled palettes under themes/ are used. These bundled palettes are copies of Pi's default dark and light themes.

Options

Option	Default	Description
enabled	true	Enables automatic theme overriding.
fallbackTheme	dark	Theme used when system appearance detection fails.
pollIntervalMs	3000	How often to re-check system appearance, in milliseconds.
queryTimeoutMs	1500	Timeout for each OS appearance command.
themes.dark	./themes/dark.json	Dark palette path.
themes.light	./themes/light.json	Light palette path.

Appearance detection

The extension executes small local commands through Pi's extension API:

Platform	Probe
macOS	defaults read -g AppleInterfaceStyle
Linux	dbus-send against org.freedesktop.portal.Desktop / org.freedesktop.appearance color-scheme
Windows / WSL	reg.exe Query HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize /v AppsUseLightTheme
OrbStack	mac defaults read -g AppleInterfaceStyle

If a probe fails, times out, or is unsupported, the extension uses fallbackTheme.

Security

Pi packages run with your local user permissions. This extension reads local JSON files and runs the appearance-detection commands listed above. Review the source before installing any Pi package you do not trust.

Troubleshooting

• Theme does not change: make sure Pi's selected theme is dark or light. The extension intentionally backs off for other theme names.
• Linux always falls back: ensure a DBus session and xdg-desktop-portal are available.
• WSL always falls back: ensure Windows' reg.exe is available at /mnt/c/Windows/System32/reg.exe or on PATH.
• Theme flickers or keeps changing: make sure you are not loading both a global development copy and this package copy at the same time.