wallhaven-cr

Wallpaper manager for Omarchy, written in Crystal with an immediate-mode GUI (raylib + raygui). No GTK, no Qt, no webview.

The window is drawn in the colours of the active Omarchy theme: it reads ~/.local/state/omarchy/current/theme/colors.toml, derives the shades the theme does not name, and picks the change up while it is running (switch themes and the window follows). Type is JetBrainsMono Nerd Font, the shell's own font. Flat and square on purpose: no rounded corners, and every filter field is labelled inline, on the same baseline as its control.

Features

• Browse wallhaven.cc with the full search surface: categories (general / anime / people), purity (SFW / sketchy / NSFW), sorting and order, toplist range, atleast minimum size, exact resolutions, aspect ratio and colour filter. The grid pages itself as you scroll.
• Look before you decide: clicking a tile opens the whole wallpaper, fetched into a disposable cache (cache/, emptied by Clear cache) — no version, no favourite, nothing added to the library. From there: keep it, crop it, add it to the theme, or just look and move on.
• Favourites are downloaded in the background (durable SQLite job queue) and get whole-image thumbnails — aspect preserved, never cropped, never stretched.
• Crop editor: zoom and drag the image under a frame locked to the target monitor's aspect ratio, then write a version at exactly that monitor's size.
• Every wallpaper keeps its original plus any number of cropped versions; each version is a separate row and can be deleted on its own.
• Add any version to the current Omarchy theme, and remove it again from the Favourites grid, Browse, or the Theme view. Adding is idempotent.
• Add wallpapers that are already on disk.
• Clear cache: one button (two presses) deletes the looked-at images and the derived thumbnails; both are rebuilt on demand, and no library file lives there.
• Progress that does not lie: a download knows its bytes, so it gets a real percentage — in the sidebar (whatever view you are on), on its row in Downloads, and while the look view is fetching. A crop or a thumbnail is a single vips run that reports nothing at all, so those show a moving stripe and a count of thumbnails left, never an invented number.

Screenshots

Browse wallhaven with the full search surface, against the local library — the grid pages itself as you scroll:

Clicking a tile opens the whole wallpaper. It is fetched into a disposable cache, so looking costs nothing: keep it, crop it, add it to the theme, or just move on.

Favourites as cards, one row per version, with the version to add to the theme and the theme chips:

The crop editor, framed to the target monitor:

Requirements

• Crystal >= 1.15 (built and tested with 1.21)
• raylib (5.5) and raygui (4.0) — raylib from the AUR/raylib package or a local install in ~/.local; raygui is built from raysan5/raygui as libraygui.so (see Makefile)
• libvips (vips) or ImageMagick for thumbnails, previews and cropping — libvips is preferred when installed (faster and far less memory per image; set WALLHAVEN_CR_IMAGE_TOOL=magick to force the fallback)
• Hyprland (hyprctl) for monitor geometry; falls back to 1920x1080
• Omarchy, for the theme integration and the palette — without an colors.toml the UI falls back to a neutral dark palette (WALLHAVEN_CR_COLORS points it at another file, WALLHAVEN_CR_FONT at another font)

Build

make            # builds bin/wallhaven-cr
make run        # builds and starts the GUI
make test       # runs the specs

Usage

wallhaven-cr                       # GUI
wallhaven-cr --search -q anime -c 010 -p 100 --pages 2 --json
wallhaven-cr --look ID             # fetch ID's full image to look at, keeping nothing
wallhaven-cr --download ID         # queue a download (moves a looked-at copy in)
wallhaven-cr --convert ID          # queue a monitor-sized version (centred crop)
wallhaven-cr --clear-cache         # empty the looked-at images + derived thumbnails
wallhaven-cr --import-local PATH   # add an image from disk to favourites
wallhaven-cr --import-aether       # queue the old Aether favourites
wallhaven-cr --drain               # run queued jobs to completion
wallhaven-cr --monitors            # Hyprland monitors and their pixel sizes
wallhaven-cr --stats               # library and queue counts
wallhaven-cr --capture PATH        # render one frame to a PNG (--frames, --view)
wallhaven-cr --capture PNG --view browse --scroll 200 --click 300,90
                                   # render with the grid scrolled and a press at a
                                   # point, to check that a click goes where it should
wallhaven-cr --version             # version plus the build time of this binary

In the GUI: left click on a tile opens the whole image (the look view), right click toggles the favourite, the wheel scrolls (and zooms in the look view), Escape goes back / closes the picker and any dropdown, Ctrl+Q quits. In the look view: k keeps it, c opens the crop editor, t adds it to the theme, f favourites, u copies the url, ←/→ move through the listing, 0 fits.

Data

The API key is seeded from ~/.config/aether/wallhaven.json on first run, so an existing wallhaven key keeps working. NSFW purity needs a key.

Development

See AGENTS.md for the architecture, the invariants that must not be broken (GL thread pinning, posix_spawnp instead of fork, per-thread SQLite connections, atomic writes), and how to verify a change without a window.