This tmux tpm plugin automatically changes the tmux theme when the system switches between light/dark mode on macOS and Linux (GNOME, KDE Plasma, COSMIC). Configure light and dark themes, and the plugin handles the rest!

• Features
• Requirements
• Installation
• Configuration
• Usage
• Troubleshooting
• Advanced Usage
• Tips & Related Tools
• More tmux plugins

• 🌙 Automatic theme switching - Responds to system appearance changes on macOS and Linux
• 🔒 Robust process management - Per-server PID tracking prevents duplicate instances
• 🎯 Modular design - Platform-specific backends with shared core
• 🐧 Linux support - GNOME, KDE Plasma, and COSMIC via freedesktop portal with DE-specific fallbacks
• 🛠️ Manual control - Switch themes manually when needed
• 📁 State management - Maintains theme symlinks for tmux config integration
• 🔧 Error handling - Comprehensive validation and helpful error messages

• Bash - For script execution
• Homebrew - Package manager for dependencies
• dark-notify - Install with brew install cormacrelf/tap/dark-notify
• tmux - Terminal multiplexer
• tpm - Tmux Plugin Manager (optional but recommended)

• Bash - For script execution
• tmux - Terminal multiplexer
• tpm - Tmux Plugin Manager (optional but recommended)
• One of the following desktop environments:
  • GNOME - Uses gsettings or freedesktop portal (both typically pre-installed)
  • KDE Plasma - Uses freedesktop portal via dbus-send and dbus-monitor
  • COSMIC (Pop!_OS) - Reads config files directly; optionally install inotify-tools for instant detection

1. Install dependencies:

   macOS:

   brew install cormacrelf/tap/dark-notify

   Linux (GNOME): No additional dependencies — gsettings is typically pre-installed.

   Linux (KDE Plasma): No additional dependencies — dbus-send and dbus-monitor are typically pre-installed.

   Linux (COSMIC): Optionally install inotify-tools for instant theme detection:

   # Debian/Ubuntu/Pop!_OS
   sudo apt install inotify-tools
   
   # Fedora
   sudo dnf install inotify-tools
   
   # Arch
   sudo pacman -S inotify-tools

2. Add plugin to tmux.conf:

   set -g @plugin 'ivuorinen/tmux-dark-notify'
   

3. Install with tpm: Press <prefix>I (default: Ctrl-b I) to install the plugin.

Add these options to your tmux.conf before the tpm initialization:

set -g @dark-notify-theme-path-light '/path/to/your/light-theme.conf'
set -g @dark-notify-theme-path-dark '/path/to/your/dark-theme.conf'

Example with Solarized themes:

set -g @dark-notify-theme-path-light '$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-light.conf'
set -g @dark-notify-theme-path-dark '$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-dark.conf'

Add this after tpm initialization to ensure themes load even if the plugin hasn't run yet:

# Initialize tpm (this line should already exist)
run '~/.config/tmux/plugins/tpm/tpm'

# Fallback theme loading
if-shell "test -e ~/.local/state/tmux/tmux-dark-notify-theme.conf" \
  "source-file ~/.local/state/tmux/tmux-dark-notify-theme.conf"

# Theme plugins (install these first)
set -g @plugin 'seebi/tmux-colors-solarized'
set -g @plugin 'ivuorinen/tmux-dark-notify'

# Configure theme paths
set -g @dark-notify-theme-path-light '$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-light.conf'
set -g @dark-notify-theme-path-dark '$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-dark.conf'

# Initialize tpm
run '~/.config/tmux/plugins/tpm/tpm'

# Fallback theme loading
if-shell "test -e ~/.local/state/tmux/tmux-dark-notify-theme.conf" \
  "source-file ~/.local/state/tmux/tmux-dark-notify-theme.conf"

1. Reload tmux config: <prefix>r or restart tmux
2. Check the theme symlink:

   ls -l ~/.local/state/tmux/tmux-dark-notify-theme.conf

3. Toggle your system appearance mode and watch tmux theme change!

The plugin runs automatically once installed, but you can also use it manually:

The plugin launches automatically with tmux and runs in the background, monitoring for system appearance changes.

# Switch to dark theme
~/.config/tmux/plugins/tmux-dark-notify/main.tmux --theme dark

# Switch to light theme
~/.config/tmux/plugins/tmux-dark-notify/main.tmux --theme light

# Start daemon manually
~/.config/tmux/plugins/tmux-dark-notify/main.tmux --daemon

# Show help
~/.config/tmux/plugins/tmux-dark-notify/main.tmux --help

1. Check dark-notify installation:

   which dark-notify
   # Should output: /opt/homebrew/bin/dark-notify (or similar)

2. Verify theme paths exist:

   # Check if your theme files are readable
   test -r "$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-light.conf" && echo "Light theme OK"
   test -r "$HOME/.config/tmux/plugins/tmux-colors-solarized/tmuxcolors-dark.conf" && echo "Dark theme OK"

3. Check plugin status:

   # Look for running daemon
   ps aux | grep tmux-dark-notify
   
   # Check PID files
   ls -la ~/.local/state/tmux/tmux-dark-notify-*.pid

1. Verify tmux options are set:

   tmux show-options -g | grep dark-notify

2. Test manual switching:

   ~/.config/tmux/plugins/tmux-dark-notify/main.tmux --theme dark

3. Check theme symlink:

   ls -l ~/.local/state/tmux/tmux-dark-notify-theme.conf

The plugin auto-detects your desktop environment. If it can't find a supported method:

1. Check freedesktop portal:

   dbus-send --session --print-reply \
     --dest=org.freedesktop.portal.Desktop \
     /org/freedesktop/portal/desktop \
     org.freedesktop.portal.Settings.Read \
     string:'org.freedesktop.appearance' string:'color-scheme'

2. Check GNOME gsettings:

   gsettings get org.gnome.desktop.interface color-scheme

3. Check COSMIC config:

   cat ~/.config/cosmic/com.system76.CosmicTheme.Mode/v1/is_dark

The plugin uses per-server PID files to prevent duplicate instances. If you see issues:

1. Remove stale PID files:

   rm ~/.local/state/tmux/tmux-dark-notify-*.pid

2. Restart the plugin:

   ~/.config/tmux/plugins/tmux-dark-notify/main.tmux

Set a custom state directory using the XDG specification:

export XDG_STATE_HOME="$HOME/.local/state"

Enable trace mode for debugging:

TRACE=1 ~/.config/tmux/plugins/tmux-dark-notify/main.tmux --daemon

You can call the theme switcher from your own scripts:

#!/bin/bash
# Switch to dark theme for late-night coding
~/.config/tmux/plugins/tmux-dark-notify/main.tmux --theme dark

Set up dark-notify to change your Neovim theme as well!

Use iTerm2 version ≥3.5 for automatic terminal theme switching:

1. Go to iTerm2 Preferences → Profiles → [your profile] → Colors
2. Check "Use different colors for light and dark mode"
3. Configure your light and dark color schemes

Create a macOS keyboard shortcut to toggle system appearance:

1. Create Quick Action in Automator:
   • Open Automator.app
   • Create a new Quick Action
   • Add "Change System Appearance" action
   • Set to "Toggle Light/Dark"
   • Save as appearance_toggle
2. Add Keyboard Shortcut:
   • Open System Settings → Keyboard → Keyboard Shortcuts → Services
   • Find your appearance_toggle service under General
   • Assign a shortcut (e.g., ⌃⌥⌘T)

Built on top of the excellent dark-notify by Cormac Relf and original tmux-dark-notify by Erik Westrup!*