Themectl Development Guide

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

Quick Reference

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)

Theme Definition Structure

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

{
  name = "theme-name";
  displayName = "Theme Name";

  # 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)

Neovim Colorschemes

VSCode/Cursor Extensions

Wallpapers

Runtime Files (User Home)

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

Adding a New Theme

1. Create theme definition:

``bash cp modules/themes/definitions/tokyo-night.nix modules/themes/definitions/my-theme.nix # Edit with your colors ``

1. Add wallpapers (optional):

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

1. 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

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

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

1. Build and test:

``bash 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

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