🎨 pick-colorscheme.wez

Spice up your terminal with a random color scheme at the press of a key!

A lightweight WezTerm plugin that randomly picks a color scheme from WezTerm's extensive collection of built-in themes. Perfect for discovering new color schemes or adding variety to your terminal experience.

✨ Features

🎲 Random Theme Selection - Instantly switch to a random color scheme from 200+ built-in WezTerm themes
🪟 Per-Window or All Windows - Apply to just the active window, or change all windows at once with separate keybindings
💧 Preserves Opacity - Maintains your current background opacity settings
🔄 Manual Update - Optional keybinding to update the plugin without leaving WezTerm

🚀 Installation

Add the following to your WezTerm configuration file (~/.wezterm.lua or ~/.config/wezterm/wezterm.lua):

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Load the plugin
local colorscheme = wezterm.plugin.require("https://github.com/qq3g7bad/pick-colorscheme.wez")

-- Initialize the plugin
colorscheme.setup()

-- Apply to config (adds keybinding)
colorscheme.apply_to_config(config)

return config

That's it! The plugin will automatically set up the event listener and keybinding.

See Also: Check out example.wezterm.lua for a complete configuration example with all available options.

Alternative: Manual Integration

If you prefer not to use the plugin system, you can manually copy the code from wezterm.lua into your configuration. However, the plugin-based installation above is recommended for easier updates and cleaner configuration.

🎯 Usage

Press Ctrl+Shift+C (default) in any WezTerm window to apply a random color scheme to that window only.

If you have multiple WezTerm windows open, only the focused window will change its theme. This allows you to keep different color schemes for different windows.

To change all windows at once, bind a separate key (see Apply to All Windows below).

🛠️ Customization

Change the Keybinding

Pass custom options to apply_to_config() to change the keybinding:

-- Use Ctrl+Alt+R instead of Ctrl+Shift+C
colorscheme.apply_to_config(config, {
  key = 'r',
  mods = 'CTRL|ALT',
})

Apply to All Windows

Add a separate keybinding to apply a random color scheme to all open windows at once:

colorscheme.apply_to_config(config, {
  apply_all_key = 'a',
  apply_all_mods = 'CTRL|SHIFT',
})

Now Ctrl+Shift+C changes only the active window, while Ctrl+Shift+A changes all windows — both available at the same time.

You can combine all options in a single apply_to_config call:

colorscheme.apply_to_config(config, {
  key = 'c',
  mods = 'CTRL|SHIFT',          -- active window
  apply_all_key = 'a',
  apply_all_mods = 'CTRL|SHIFT', -- all windows
  update_key = 'u',
  update_mods = 'CTRL|SHIFT',    -- update plugin
})

Add an Update Keybinding

Bind a key to manually update the plugin (and all other WezTerm plugins) without leaving your terminal:

colorscheme.apply_to_config(config, {
  update_key = 'u',
  update_mods = 'CTRL|SHIFT',
})

Press Ctrl+Shift+U to trigger the update. WezTerm will pull the latest changes and reload automatically.

🔄 Updating

WezTerm plugins are cached in ~/.local/share/wezterm/plugins/. There are several ways to update:

Option 1: Keybinding (Recommended)

Add an update keybinding to your config (see Add an Update Keybinding above), then simply press the bound key.

Option 2: Lua API

Run this in WezTerm's Debug Overlay (Ctrl+Shift+L):

wezterm.plugin.update_all()

Option 3: Manual git pull

cd ~/.local/share/wezterm/plugins/
# Find the plugin directory (name is derived from the URL)
ls
# cd into the matching directory, then:
git pull

🐛 Troubleshooting

The color scheme doesn't change

Make sure you've reloaded your WezTerm configuration
Check the WezTerm console for any Lua errors
Verify that the keybinding doesn't conflict with other shortcuts

Opacity resets to default

This happens when window_background_opacity isn't set in your config overrides. The plugin preserves existing opacity, but if none is set, it will be nil. To fix this, set a default opacity in your main config:

config.window_background_opacity = 0.9

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Built with WezTerm - A powerful cross-platform terminal emulator

Enjoy exploring WezTerm's color schemes! 🌈

qq3g7bad/pick-colorscheme.wez