pi-system-theme

Sync Pi theme with macOS light/dark appearance

Package details

← Back
extension

Install pi-system-theme from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-system-theme
Package
pi-system-theme
Version
0.4.0
Published
Feb 12, 2026
Downloads
87/mo · 28/wk
Author
ferologics
License
MIT
Types
extension
Size
32.7 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-system-theme

A Pi extension that syncs Pi's theme with system appearance (dark/light mode) on macOS, Linux, and Windows.

Behavior

  • Dark appearance -> darkTheme
  • Light appearance -> lightTheme

Detection backends:

# macOS
/usr/bin/defaults read -g AppleInterfaceStyle

# Linux (GNOME-compatible)
gsettings get org.gnome.desktop.interface color-scheme
# fallback: gsettings get org.gnome.desktop.interface gtk-theme

# Windows
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize" /v AppsUseLightTheme

If detection fails or returns an unknown value, the extension keeps the current Pi theme unchanged.

Defaults (works out of the box)

No config is required.

  • darkTheme: dark
  • lightTheme: light
  • pollMs: 2000

Configuration file (global only)

Path:

  • ~/.pi/agent/system-theme.json

The extension stores only overrides in this file. If all values match defaults, the file is removed.

Example:

{
    "darkTheme": "rose-pine",
    "lightTheme": "rose-pine-dawn"
}

Interactive command

Use /system-theme to open a small settings menu and edit:

  1. dark theme name
  2. light theme name
  3. poll interval (ms)

Choose Save and apply to persist overrides and apply immediately.

Notes

  • This extension acts on macOS, Linux, and Windows (darwin, linux, win32).
  • Linux support currently depends on GNOME-compatible gsettings keys (color-scheme, with gtk-theme fallback).
  • Windows support reads AppsUseLightTheme from HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize.
  • In headless modes without theme support (for example -p print mode), the extension stays idle.
  • If your current theme is custom and darkTheme/lightTheme are still default (dark/light), the extension does nothing to avoid overriding your setup. Configure /system-theme to opt into syncing.
  • If a configured theme name does not exist, Pi keeps the current theme and logs a warning.

Install

From npm (standalone package):

pi install npm:pi-system-theme

From git:

pi install git:github.com/ferologics/pi-system-theme

Or from local source while developing:

pi -e /path/to/pi-system-theme/index.ts