Themectl Development Guide

Manage the cross-platform theme system for NixOS and Darwin.

Quick Reference

Task	Command
Show current theme	themectl status
Apply a theme	themectl apply <theme-name>
Cycle to next theme	themectl cycle --direction next
Cycle wallpapers	themectl cycle-background
Run health checks	themectl doctor
Show hotkeys	themectl hotkeys
Toggle macOS BSP/native	themectl macos-mode --mode bsp

Development Workflow (No Deploy Required)

Quick Testing Without Rebuild

For CLI changes, run themectl directly from source:

# Enter dev shell (has all dependencies)
nix develop --impure

# Run from source
cd scripts/themectl
python -m themectl status
python -m themectl apply tokyo-night

# Or use uv for faster iteration
uv run themectl status

Testing After Theme Definition Changes

Theme definitions are in Nix, so changes require a rebuild:

# Fast local build (no deploy)
nix build .#darwinConfigurations.halcyon.system --impure

# Activate locally
sudo ./result/sw/bin/darwin-rebuild switch --flake .#halcyon

# Test the theme
themectl apply <theme-name>

Running Tests

cd scripts/themectl
uv run pytest
uv run pytest -v tests/test_cli.py::test_specific_test

Key File Locations

Theme Definitions (Nix)

Path	Purpose
modules/themes/definitions/*.nix	Individual theme color palettes
modules/themes/lib.nix	Theme library functions, metadata builder
modules/themes/default.nix	Main theme module

Theme Definition Structure

Each theme in modules/themes/definitions/<name>.nix contains:

{
  name = "theme-name";
  displayName = "Theme Name";
  kind = "dark"; # or "light" — drives OS light/dark mode + editor background

  # Terminal colors
  alacritty = { primary = { background = "#..."; foreground = "#..."; }; ... };
  kitty = { background = "#..."; foreground = "#..."; color0 = "#..."; ... };
  ghostty = { theme = "..."; background = "#..."; palette = [ "0=#..." ... ]; };

  # Editor themes
  nvim = { colorscheme = "..."; };
  vscode = { theme = "..."; extension = "publisher.name"; };
  cursor = { theme = "..."; extension = "publisher.name"; };  # Optional

  # Desktop colors
  hyprland = { activeBorder = "..."; inactiveBorder = "..."; };
  waybar = { foreground = "#..."; background = "#..."; };
  walker = { ... };

  # Application colors
  tmux = { statusBackground = "#..."; ... };
  btop = { main_bg = "#..."; ... };
  mako = { ... };

  # Wallpapers (filenames in wallpapers/<theme>/)
  wallpapers = [ "0-file.jpg" "1-file.jpg" ];
}

Themectl CLI (Python)

Path	Purpose
scripts/themectl/themectl/cli.py	Main CLI entry point, commands
scripts/themectl/themectl/hooks.py	App reload logic (neovim, ghostty, tmux, etc.)
scripts/themectl/themectl/themes.py	Theme class, metadata parsing
scripts/themectl/themectl/assets.py	Asset generation (alacritty, starship configs)
scripts/themectl/themectl/config.py	Configuration loading
scripts/themectl/tests/	Test suite

Neovim Colorschemes

Path	Purpose
modules/home-manager/editor/neovim.nix	Neovim config, colorscheme plugins
modules/home-manager/editor/nvim-colors/*.lua	Custom colorschemes (e.g., matte-black)

VSCode/Cursor Extensions

Path	Purpose
packages/vscode-extensions/default.nix	Custom-packaged theme extensions
modules/home-manager/darwin/cursor-extensions.nix	Extension installation module

Wallpapers

Path	Purpose
modules/themes/wallpapers/<theme>/	Theme wallpapers
external/omarchy/	Upstream omarchy submodule (source for sync)

Runtime Files (User Home)

Path	Purpose
~/.config/themes/.current	Current theme name
~/.config/themes/.current-background	Current wallpaper index
~/.config/alacritty/alacritty.toml	Generated alacritty config
~/.config/ghostty/config	Generated ghostty config
~/.config/nvim/lua/plugins/theme.lua	Mutable neovim theme config

Available Themes

Current themes (check modules/themes/definitions/):

• tokyo-night - Default, blue/purple
• catppuccin - Mocha variant, pastel
• catppuccin-latte - Light variant
• gruvbox - Warm retro
• nord - Arctic blue
• rose-pine - Muted rose
• everforest - Green forest
• kanagawa - Japanese wave
• matte-black - Minimal dark (custom nvim colorscheme)
• osaka-jade - Green/jade Tokyo Night variant
• ristretto - Monokai coffee
• flexoki-light - Warm light theme

Runtime Reload Hooks (hooks.py)

themectl apply runs these in order after updating symlinks/state: VSCode → Cursor → Neovim → tmux → Alacritty → Hyprland → Wallpaper → System appearance → Ghostty (config rewrite) → cmux reload → Ghostty (app reload) → btop.

• System appearance (update_system_appearance): reads theme.is_light (from kind) and flips macOS light/dark via System Events appearance preferences (skips if already matching). On Linux it sets org.gnome.desktop.interface color-scheme when gsettings exists.
• cmux (reload_cmux, macOS only): cmux embeds libghostty and reads ~/.config/ghostty/config for terminal colors; cmux reload-config refreshes terminals in place. cmux's own chrome (sidebar/tabs) uses appearanceMode = system, so it follows the System appearance hook. Do not use cmux themes set — it writes an override that stops cmux reading the Ghostty config themectl manages.
  • cmux's socket defaults to cmuxOnly (only processes spawned inside cmux may connect), which rejects themectl when launched from skhd or another terminal with "Access denied". halcyon's ~/.config/cmux/cmux.json (user-owned, not Nix-managed) sets automation.socketControlMode = "password" with a random socketPassword; the CLI falls back to that saved password automatically, so no env var is needed. cmux hot-reloads cmux.json on save.
• Ghostty: there is no ghostty +reload-config CLI action; the app is reloaded with Cmd+Shift+, via AppleScript on macOS.
• THEME_DISABLE_EDITOR_AUTOMATION=1 disables every AppleScript-based hook (editors, wallpaper, appearance, Ghostty keystroke).
• Automation needs the terminal app to have Automation → System Events permission; the first run prompts for it.

Adding a New Theme

1. Create theme definition:

   cp modules/themes/definitions/tokyo-night.nix modules/themes/definitions/my-theme.nix
   # Edit with your colors; set kind = "light" for light palettes
   

2. Add wallpapers (optional):

   mkdir -p modules/themes/wallpapers/my-theme
   cp /path/to/wallpaper.jpg modules/themes/wallpapers/my-theme/0-wallpaper.jpg
   

3. Add neovim colorscheme (if custom):

   • Either use an existing plugin (add to neovim.nix colorschemes list)
   • Or create custom colorscheme in nvim-colors/my-theme.lua

4. Add VSCode extension (if not in marketplace):

   • Package in packages/vscode-extensions/default.nix
   • Add to cursor-extensions.nix

5. Build and test:

   nix build .#darwinConfigurations.halcyon.system --impure
   sudo ./result/sw/bin/darwin-rebuild switch --flake .#halcyon
   themectl apply my-theme
   

Common Issues

Theme not appearing in themectl status

• Ensure theme definition exports required fields (name, displayName)
• Check nix build for syntax errors

Neovim colorscheme not loading

• Verify colorscheme plugin is in neovim.nix colorschemes list with lazy = false
• For custom colorschemes, ensure file is in nvim-colors/ and added to git
• Check mapping in themeToColorscheme table

VSCode/Cursor theme not applying

• Check if extension is available in marketplace
• For Cursor, may need to package locally (different marketplace)
• Verify vscode.extension and cursor.extension in theme definition

macOS appearance / cmux chrome not switching

• Check kind in the theme definition; themectl apply prints "Set macOS appearance to light|dark" or "already "
• If it prints "Could not set macOS appearance", grant your terminal Automation → System Events in System Settings › Privacy & Security
• cmux sidebar follows macOS appearance only while app.appearance is system (check cmux settings path / defaults read com.cmuxterm.app appearanceMode)
• Confirm no override: cmux themes should show Source: ~/.config/ghostty/config
• "Access denied - only processes started inside cmux can connect": switch automation.socketControlMode to password in ~/.config/cmux/cmux.json (see Runtime Reload Hooks above)

Wallpaper not changing

• Ensure wallpaper files exist in modules/themes/wallpapers/<theme>/
• Check wallpapers array in theme definition matches filenames
• On Darwin, desktoppr must be installed