walh-shell

A fast, modern, and extensible Zsh (and Bash) plugin for instant terminal color theme switching.

walh-shell lets you instantly change your terminal’s color scheme with a single command. Choose from dozens of beautiful, curated themes, or create your own using simple TOML files. Themes are applied live—no need to restart your shell!

👉 Live Theme Preview & Interactive Playground

• Instant theme switching: Change your terminal colors on the fly with a single command or alias.
• Curated & custom themes: Includes a wide selection of popular color schemes (One Dark, Dracula, Solarized, GitHub, and more).
• Easy customization: Define your own themes in TOML, or tweak existing ones.
• Fast & lightweight: No Python or Node.js required at runtime—just shell scripts.
• Zsh & Bash support: Works in both Zsh and Bash shells.
• Plugin-friendly: Simple to install with any Zsh plugin manager (zinit, zplug, etc).
• Truecolor & tmux support: Works with modern terminals and tmux (see below for config tips).
• Mode announcement: Every theme script exports WALH_MODE=dark|light and COLORFGBG (the ncurses/rxvt convention), both derived from palette luminance, so programs launched from the shell can adopt the mode without querying the terminal.
• Derived base colors: color00 (surface: background mixed 15% toward the foreground) and color08 (dim: foreground washed 40% toward the background on dark palettes, 50% on light) are computed from each theme's own foreground/background, so panels and secondary text stay distinct on any palette while tools keep using the base 16 colors.

zload casonadams/walh-shell

zinit wait lucid for \
  OMZL::key-bindings.zsh \
  OMZL::history.zsh \
  OMZP::git \
  casonadams/walh-shell

You can use walh-shell as a custom plugin in Oh My Zsh:

1. Clone the repository into your custom plugins folder:

   git clone https://github.com/casonadams/walh-shell.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/walh-shell

2. Add walh-shell to your plugin list Edit your ~/.zshrc and add walh-shell to the plugins=(...) array:

   plugins=(... walh-shell)

3. Reload your shell

   source ~/.zshrc

Now you can use the walh command to switch themes!

Clone this repo and source the plugin in your .zshrc:

git clone https://github.com/casonadams/walh-shell.git ~/.walh-shell
echo 'source ~/.walh-shell/walh-shell.plugin.zsh' >> ~/.zshrc

You can use walh-shell in Bash as well!

1. Clone the repo:

   git clone https://github.com/casonadams/walh-shell.git ~/.walh-shell

2. Source the helper in your .bashrc:

   source ~/.walh-shell/profile_helper.sh

3. Reload your shell or run:

   source ~/.bashrc

4. Switch themes with the unified CLI:

   walh onedark
   walh dracula
   # ...and so on!

Switch themes and manage palettes using the unified walh command:

# Apply a theme
walh onedark
walh gruvbox-dark
walh solarized-light

# Show active theme name, mode, and colors
walh current

# Toggle between your active dark and light themes
walh toggle

# List available themes
walh list
walh list --dark
walh list --light

# Apply a random theme
walh random
walh random dark
walh random light

Automatic tab completions are provided for both Zsh and Bash:

• walh <TAB> suggests subcommands and available themes.
• walh list --<TAB> suggests --dark and --light.
• walh random <TAB> suggests dark and light.

You can define hooks that run every time a theme is applied. Place executable scripts in $HOME/.config/walh/hooks (or customize the path via $WALH_SHELL_HOOKS):

# Optional: custom hook directory (defaults to $HOME/.config/walh/hooks)
export WALH_SHELL_HOOKS="$HOME/.config/walh/hooks"

Each hook receives the active palette metadata via environment variables:

• WALH_THEME: Active theme slug (e.g. gruvbox-dark)
• WALH_MODE: Palette luminance mode (dark or light)
• WALH_BG: Background hex color (e.g. #282828)
• WALH_FG: Foreground hex color (e.g. #D5C4A1)

• Themes are defined in simple TOML files in the themes/ directory.
• To add your own, copy an existing .toml file, edit the colors, and re-run uv run generate_themes.py to generate the shell script.
• PRs for new themes are welcome!

If you want to change terminal colors dynamically inside tmux, ensure tmux is configured for passthrough and truecolor:

For tmux 3.3 and newer:

set -g allow-passthrough on
set-option -g default-terminal "xterm-256color"
set-option -sa terminal-overrides ",${TERM}:RGB"

For older tmux:

set-option -g default-terminal "xterm-256color"
set-option -sa terminal-overrides ",${TERM}:RGB"

• Found a bug? Want to add a new theme? PRs and issues are welcome!
• Please keep new themes consistent with the TOML format and color slot order.

MIT

Enjoy beautiful, instant terminal themes with walh-shell!