Switchcraft

Switchcraft is a GTK/Libadwaita developed desktop utility in Vala that makes your whole desktop follow the light/dark style on GNOME and KDE Plasma. A lightweight background monitor watches the system preference and, on every switch, runs your shell commands and applies per-theme settings such as icons, wallpaper, GTK, shell and Kvantum themes. It can also switch the style for you at sunset and sunrise or at custom times.

This AppImage bundles everything and it should work on any Linux distro, including old and musl-based ones.

Switchcraft doesn't require FUSE to run, thanks to the uruntime

Preview

Features

• Custom commands: Run any shell command when the desktop switches to light or dark style.
• Built-in commands: Pick a setting and a value from a list instead of typing a command. Only the ones for the running desktop are offered:
  • GNOME: color scheme, accent color, icon, GTK, cursor and shell theme, wallpaper, Night Light.
  • KDE Plasma: global theme, color scheme, Plasma style, icon and cursor theme, wallpaper.
  • Any desktop: Kvantum theme, when Kvantum is installed.
• Automatic switching: Switch between light and dark style at sunset and sunrise, or at custom times, in Preferences → Automatic Switching. Uses GeoClue for the location when allowed, else the system time zone. On KDE Plasma it switches the default light and dark global themes, unless Plasma's own automatic switching is enabled.
• Background monitor: The Monitor switch in the header starts the background process and adds it to autostart. The window can stay closed, and edits apply on the next theme switch without a restart.
• Constants: Define reusable variables once and reference them in commands as $NAME or ${NAME}.
• Command management: Add, edit, enable or disable and delete commands, with undo for deletes. Drag rows to reorder them and flip a command between light and dark with one toggle.
• Import and export: Save commands and constants into a zip archive and restore them on another machine.

Command Examples (click to open)

• Change Dash 2 Dock Lite background based on theme and using constants

Light theme:

gsettings --schemadir $D2DL_SCHEMADIR set $D2DL_SCHEMA background-color '(0.063, 0.1216, 0.1882, 1.0)'

Dark theme:

gsettings --schemadir $D2DL_SCHEMADIR set $D2DL_SCHEMA background-color '(0.3373, 0.4392, 0.5294, 1.0)'

• Set constants:

D2DL_SCHEMADIR="$HOME/.local/share/gnome-shell/extensions/dash2dock-lite@icedman.github.com/schemas"
D2DL_SCHEMA="org.gnome.shell.extensions.dash2dock-lite"

• Change legacy theme to dark:

gsettings set org.gnome.desktop.interface gtk-theme 'adw-gtk3-dark'

• Change icon theme to light:

gsettings set org.gnome.desktop.interface icon-theme 'MacTahoe-light'

Install

Simply download the latest AppImage and double click to run it.

For seamless AppImage integration use AppManager.

Requirements

• Build tools: a C compiler, valac, meson (>= 0.59), ninja, pkg-config, gettext, glib-compile-resources, glib-compile-schemas
• Libraries (with development headers): gtk4, libadwaita-1 (>= 1.8), glib-2.0 (>= 2.66), gio-2.0, json-glib-1.0
• Runtime tools: gsettings, zip and unzip (configuration export and import), pgrep and pkill (managing the background monitor). Optional: GeoClue with location services on, for exact sunrise and sunset; Plasma's plasma-apply-* tools for the KDE built-ins; kvantummanager for the Kvantum built-in
• AnyLinux AppImage packaging with scripts/make-anyimage.sh: podman (the build runs in an Arch Linux container)
• Local AppImage packaging with scripts/make-appimage.sh: bash, jq and appimagetool (downloaded automatically if missing)

Build

Install development dependencies

(click to open)

Your distribution must provide libadwaita >= 1.8. The lists include zip, unzip and jq.

• Debian / Ubuntu:

sudo apt install build-essential valac meson ninja-build pkg-config gettext \
  libglib2.0-dev libgtk-4-dev libadwaita-1-dev libjson-glib-dev zip unzip jq

• Fedora:

sudo dnf install gcc vala meson ninja-build pkgconf-pkg-config gettext \
  glib2-devel gtk4-devel libadwaita-devel json-glib-devel zip unzip jq

• Arch Linux / Manjaro:

sudo pacman -S --needed base-devel vala meson ninja gettext glib2 gtk4 libadwaita json-glib zip unzip jq

On Arch Linux / Manjaro, base-devel supplies the C compiler and pkgconf.

jq is needed by scripts/make-appimage.sh, but not by the Meson build itself.

Default setup

meson setup build --prefix=$HOME/.local

Build and install

meson compile -C build
meson install -C build

Uninstall

ninja -C build remove

For a system-wide install use --prefix=/usr/local and run the install and remove steps with sudo.

Build portable AppImage versions:

scripts/make-anyimage.sh  # anylinux version (long build)
scripts/make-appimage.sh  # standard AppImage (requires FUSE)

Translations

UI strings use gettext. See po/README.md for the workflow. ./scripts/translations.sh --pot-only refreshes the template without touching existing .po files.

Configuration

Details (click to open)

All runtime configuration lives under ~/.local/share/switchcraft/.

• commands.json - per-theme command lists. Example:

{
  "dark": [{ "command": "notify-send 'Dark mode enabled'", "enabled": true }],
  "light": [{ "command": "notify-send 'Light mode enabled'", "enabled": true }]
}

• constants.json - reusable variables referenced inside commands using $NAME or ${NAME}. Values are expanded by the shell, so $HOME works inside them.

Example:

{
  "D2DL_SCHEMADIR": "$HOME/.local/share/gnome-shell/extensions/dash2dock-lite@icedman.github.com/schemas",
  "D2DL_SCHEMA": "org.gnome.shell.extensions.dash2dock-lite"
}

Built-in commands are stored in commands.json as normal gsettings lines with two extra fields, so the dialog can reopen them:

{ "command": "gsettings set org.gnome.desktop.interface gtk-theme 'adw-gtk3-dark'",
  "enabled": true, "builtin": "gtk-theme", "value": "adw-gtk3-dark" }