Hellwal - Fast, Extensible Color Palette Generator

Star History

Click to expand star history

Installation

1. Archlinux:

yay -S hellwal

2. Mac/Linux via Homebrew:

brew install hellwal

3. NixOS, nixpkgs unstable:

environment.systemPackages = [
  pkgs.hellwal
];

Building

Clone git repo, run make command and you are ready to go! - you just need a C compiler and gnumake!

git clone https://github.com/danihek/hellwal && cd hellwal && make

How to use?

Run this with your wallpaper image:

hellwal -i [image]

You can also randomly pick an image from a given directory like this:

hellwal -i <folder> --random

Generated templates are saved in ~/.cache/hellwal/.

Comfort mode

Use --comfort-mode for restrained wallpaper colors with explicit text contrast targets:

hellwal -i wallpaper.png --comfort-mode
hellwal -i wallpaper.png --comfort-mode --light

Comfort mode uses deterministic OKLab clustering to preserve wallpaper hues, reduce excessive saturation, and fit colors to the background. Dark remains the default. Monochrome wallpapers remain monochrome. Existing appearance flags, including --neon-mode, --invert, offsets, grayscale and --dominant-background, work with it; contrast correction runs last. --check-contrast is redundant in comfort mode. --skip-luminance-sort keeps deterministic selection order instead of perceptual lightness order.

Role	Contrast target against its background
Main text (color7, color15, foreground)	7.2:1
Regular colored text (color1–color6) and accent	5.2:1
Bright colored text (color9–color14)	6.2:1
Muted text (color8)	4.7:1
Text on accents, selections and cursors	At least 5.2:1 where possible

An image is required. Theme merging through --override-colors is supported; explicit static colors and theme slots outside the override list remain exact. If these fixed colors prevent a target, hellwal warns on stderr, including on cache hits. JSON output remains valid.

Use the additional template variables below in your own templates for selections and cursors. These targets apply to the intended foreground/background pairs; template filters, transparency and other background pairings can change contrast. Existing templates remain available.

For background, see relative luminance, color difference, and OKLab. The mathematics follow OKLab and W3C relative luminance and contrast. The targets are chosen comfort defaults, not medically established limits or an eye-damage prevention claim. Classic palette generation remains the default.

Palette cache

Finished palettes are stored in ~/.cache/hellwal/cache/, or cache/ inside --output. Each appearance-argument combination has its own folder, for example:

cache/
  comfort-dark-<arguments-hash>/<image-content-hash>.palette
  comfort-light-<arguments-hash>/<image-content-hash>.palette
  classic-dark-<arguments-hash>/<image-content-hash>.palette

Default dark, light, and dark with --dark-offset 0.2 are cached separately. The argument key includes the algorithm, appearance flags, offsets, grayscale, static colors and theme override slots. Implicit dark and explicit --dark share an entry. Image and theme contents determine the file identity, so editing either invalidates the palette even if its filename or timestamp stays the same. Output formatting, template folders, quiet mode and scripts do not create extra palette variants. Comfort mode and classic mode use this same cache layout; there is no separate extraction cache. Use --no-cache to bypass reads and writes.

Clear all cached palette variants without an image:

hellwal --clear-cache
hellwal --clear-cache --output /path/to/output

The command reports the number of files removed, cached-data bytes removed and disk space reclaimed. Generated templates in the output folder remain in place. It also removes legacy palette caches. Add --json for machine-readable totals.

Templates

[INFO] - if you got hellwal from the AUR, examples of default templates can be found in /usr/share/docs/.

There are also examples in the templates folder. They look more-less like this:

# Main
background='%%background%%'
foreground='%%foreground%%'

# Path
wallpaper_path='%%wallpaper%%'

# Colors
color0='%%color0.hex%%'
color1='%%color1.hex%%'

# ... and so on and so forth.

color15='%%color15.hex%%'


# RGB
backgroundRGB='%%background.rgb%%'
foregroundRGB='%%foreground.rgb%%'

color15butRGB='%%color15.rgb%%'

Available template variables

Variable	Description	Usage
wallpaper	Image path (theme name when using only a theme)	%%wallpaper%%
color0–color15	The 16 palette colors	%%color1.hex%%
background	Background, alias of color0	%%background%%
foreground	Main text, alias of color15	%%foreground%%
cursor	Cursor block background, alias of color15	%%cursor%%
border	Border/indicator color, alias of color15	%%border%%
accent	Wallpaper accent fitted against background; comfort mode only	%%accent%%
accent_foreground	Text on accent; comfort mode only	%%accent_foreground%%
selection_background	Selection fill, same as accent; comfort mode only	%%selection_background%%
selection_foreground	Text on selection_background; comfort mode only	%%selection_foreground%%
cursor_text	Text inside the cursor block; comfort mode only	%%cursor_text%%

All color variables, including the comfort-mode variables, support the formats, alpha modifier and operations below. wallpaper is a string, not a color. Color values omit #; add it in the template when required. For example:

selection_background #%%selection_background.hex%%
selection_foreground #%%selection_foreground.hex%%
cursor #%%cursor.hex%%
cursor_text_color #%%cursor_text.hex%%
accent_rgba = %%accent.rgb alpha=0.8%%
accent_inverted = #%%accent.invert().hex%%

After the color keyword, you can specify the format: hex, rgb, or a single rgb channel. By default, the template output is in hex.

Available color template formats:

Type	Input	Output
hex	color0.hex	000000
rgb	color0.rgb	0, 0, 0
r	color0.r	0
g	color0.g	0
b	color0.b	0

Additional variables accepted by templates

Alongside colors, you can specify some variables to make them more suitable for your needs. For now these variables are available:

Variable	Description	Usage
alpha	Set transparency value	%% color1.hex alpha=0.5 %%

alpha is ignored for single rgb channels.

Color operations and filters

Chain HSL (hue, saturation, lightness) adjustments and RGB filters without changing the base palette. Operations apply from left to right:

%% color1.saturate(0.2).lighten(0.1).hex %%
%% background.sepia(0.5).contrast(1.2).rgb alpha=0.8 %%

Operation	Description
saturate(x) / desaturate(x)	Add / subtract saturation by x (0–1).
lighten(x) / darken(x)	Add / subtract lightness by x (0–1).
saturation(x) / lightness(x)	Set saturation / lightness to x (0–1).
rotate(degrees)	Rotate hue in either direction, wrapping at 360°.
complement()	Rotate hue by 180°.
grayscale()	Remove saturation while preserving lightness.
invert()	Invert each RGB channel (255 - channel).
sepia(amount)	Apply a sepia tint: 0 is unchanged, 1 is full sepia.
contrast(factor)	Scale RGB contrast around mid-gray: 0 is gray, 1 is unchanged.
brightness(factor)	Multiply RGB channels: 0 is black, 1 is unchanged.

Factors must be nonnegative; all arguments must be finite. Results clamp to the valid color range after each operation. HSL adjustments add percentage points: lighten(0.2) adds 20 points of lightness. RGB filters work on sRGB channels.

Use color0–color15, the existing color aliases, or the comfort-mode color variables. Finish the chain with .hex, .rgb, .r, .g, or .b (default: hex), then optionally append alpha=0.5. Hex output omits #; alpha is ignored for individual channels. Invalid operation expressions warn and remain visible in the generated file.

JSON

You can use the --json argument to suppress any other output and write colors to stdout in JSON format. With --comfort-mode, the five additional color variables are included in the special object alongside background, foreground, cursor and border. You can then manipulate the output with jq. For example:

hellwal -i [wallpaper] --json | jq '.'

Themes

You can set your own theme, re-run it anytime and apply it to your config or other programs! It can be a previously generated palette from an image, gruvbox, Tokyo Night, or anything you want! For example, gruvbox theme:

%% color0  = #282828 %%
%% color1  = #cc241d %%
%% color2  = #98971a %%
%% color3  = #d79921 %%
%% color4  = #458588 %%
%% color5  = #b16286 %%
%% color6  = #689d6a %%
%% color7  = #a89984 %%
%% color8  = #928374 %%
%% color9  = #fb4934 %%
%% color10 = #b8bb26 %%
%% color11 = #fabd2f %%
%% color12 = #83a598 %%
%% color13 = #d3869b %%
%% color14 = #8ec07c %%
%% color15 = #ebdbb2 %%

Save the text above as a file or copy gruvbox from this repo and just run hellwal:

hellwal --theme ./themes/gruvbox.hellwal

I recommend putting all themes in the default theme folder ~/.config/hellwal/themes. This way, you can provide the theme name without specifying the path, and hellwal will pick it up automatically. Of course if you want, you can also set a different theme folder. For example:

hellwal -t gruvbox.hellwal --theme-folder ~/dotfiles/configs/hellwal/themes

Replace selected theme colors with image colors

hellwal -i wallpaper.jpg -t gruvbox.hellwal --override-colors color1,color2,background

This copies matching image-palette slots into the theme: image color1 replaces theme color1, and so on. Select color0–color15, background (color0), or foreground, cursor, and border (all color15). Separate names with commas; duplicates are harmless, and repeated --override-colors options combine their selections. Empty or unknown selectors are errors.

Image colors are sorted and their bright variants prepared before copying. Without adjustment flags, unselected theme colors stay unchanged and mixed mode does not automatically darken the palette. Explicit modes, inversion, offsets, grayscale, static foreground/background, and contrast checks apply to the whole merged palette afterward, so they can also change unselected colors. For example:

hellwal -i wallpaper.jpg -t gruvbox.hellwal --override-colors color1,color2 --light

Both --image and --theme are required. Theme paths, named themes, and --theme-folder work as usual. With --random, only the image is chosen randomly; the specified theme stays fixed. wallpaper in templates/JSON refers to the image. The source theme is never rewritten. Finished palettes are cached by image/theme contents and appearance arguments, including the override list. Combining image and theme without --override-colors remains an error, and --dominant-background can be combined with themes only in comfort mode.

NEON Mode

Neon mode boosts colors to make them look more vibrant and bold. Sometimes it's a pain in the EYE, but it often looks better. Turned off by default.

hellwal -i [wallpaper] --neon-mode

Modes

You can select -d/--dark or -l/--light mode on any given image, theme, etc., no matter if it's generated from an image or from a theme file. There is also --color mode.

Dark mode (on by default)

hellwal -i [wallpaper] --dark

Dominant background

Use the wallpaper's most common color for the background instead of the darkest palette color:

hellwal -i [wallpaper] --dominant-background

Light mode

hellwal -i [wallpaper] --light

color mode (crazyy one)

hellwal -i [wallpaper] --color

The best thing about it is that you are able to combine all of these together. Usually it's not a good idea, but sometimes you can achieve some crazy color combinations!

hellwal -i [wallpaper] --color --light --dark

---

Also, you have a couple of cool arguments to manipulate how colors will be computed:

• you can darken all colors by specifying --dark-offset from 0-1 (the higher the value, the darker the colors):

hellwal -i [wallpaper] --light --dark-offset 0.5

• same with --bright-offset (the higher the value, the brighter the colors):

hellwal -i [wallpaper] --bright-offset 0.5

• invert colors with --invert:

hellwal -i [wallpaper] --light --invert

• specify grayscale, if you want monochromatic colors, with --gray-scale:

hellwal -i [wallpaper] --color --gray-scale 0.8

• ensure colors are readable against the background with --check-contrast:

hellwal -i [wallpaper] --check-contrast

Scripts

With --script or -s you can run a script (or any shell command) after hellwal.

Note: it will only run if hellwal does not encounter any errors.

On a side note:

If you want your new terminals to open with a previously generated or specified color palette, add these templates to your ~/.config/hellwal/templates/ folder:

• variables.sh
• terminal.sh

Run hellwal with an image or theme to generate the output scripts from the templates.

Then in .bashrc, add following lines:

source ~/.cache/hellwal/variables.sh
sh ~/.cache/hellwal/terminal.sh

Alternatively if you use fish:

• variablesfish.fish
• terminal.sh

Then add this to your fish config:

source ~/.cache/hellwal/variablesfish.fish
sh ~/.cache/hellwal/terminal.sh

Showcase

Special thanks:

• dylanaraps - for pywal and other amazing stuff he created.