An Oh-My-Zsh plugin that automatically changes your terminal background color based on the SSH host you connect to.
Each host gets a unique, consistent color — making it easy to instantly see where you are.
-
🎨 Unique background per host:
The hostname is hashed to a color hue, ensuring each host always gets the same color. -
🌗 Fixed lightness (20%):
Keeps the color dark enough for text to remain readable. -
🔄 Automatic reset:
When the SSH session closes, the terminal background resets to your default base color. -
⚙️ Customizable via environment variables:
Fine-tune saturation, lightness, hashing method, or disable wrapping entirely. -
🧩 Seamless integration:
Works with normalsshcommands or through the helper commandssh-warrior.
- Zsh
- Oh My Zsh
- A terminal that supports OSC 11 / OSC 111 escape sequences
(Kitty, iTerm2, Alacritty, GNOME Terminal, etc. all work great)
-
Clone the repository:
git clone https://github.com/OfferPi/ssh-warrior.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/ssh-warrior -
Enable the plugin:
Edit your
~/.zshrcand addssh-warriorto theplugins=( … )list:plugins=( git ssh-warrior )
-
Reload Zsh:
source ~/.zshrc
You can set any of these in your ~/.zshrc before source $ZSH/oh-my-zsh.sh.
| Variable | Default | Description |
|---|---|---|
SSH_WARRIOR_DISABLE |
0 |
Set to 1 to disable all behavior. |
SSH_WARRIOR_WRAP |
1 |
Wrap the normal ssh command. If 0, only ssh-warrior is available. |
SSH_WARRIOR_ENABLE_SSH_WARRIOR |
1 |
Create the explicit ssh-warrior helper command. |
SSH_WARRIOR_BASE_HEX |
171421 |
Base color to restore on exit (HEX without #). |
SSH_WARRIOR_SATURATION |
0.65 |
Saturation value of generated colors. |
SSH_WARRIOR_LIGHTNESS |
0.20 |
Lightness (brightness) value of generated colors. |
SSH_WARRIOR_RESET_STRATEGY |
auto |
How to reset the background. auto: try OSC 111 then fallback. base_only: skip OSC 111. |
SSH_WARRIOR_HASH_CMD |
cksum |
Hash function for color generation (cksum or poly). |
SSH_WARRIOR_DEBUG |
0 |
Set to 1 for debug output to the terminal. |
You can use ssh-warrior in two ways:
Just connect like you normally do:
ssh user@myserverThe plugin automatically adjusts your background color before connecting and restores it when the session closes.
If you prefer to keep your normal ssh untouched:
export SSH_WARRIOR_WRAP=0Then use:
ssh-warrior myserverYou can preview what color a host would get without connecting:
ssh-warrior-preview myserver
# => myserver → #12345A (S=0.65 L=0.20)