wayper

The wallpaper manager that learns what you like. Wallhaven integration, AI-native, keyboard-driven.

GitHub stars License AUR Release
Download View on GitHub
wallpaper transitions

Features

Learns from you

Ban a wallpaper and wayper analyzes the pattern. AI suggests what to exclude next, with iterative feedback tracking.

AI-native (MCP)

Tell Claude "switch to something with mountains" — it just works. First wallpaper manager with native AI assistant integration.

Keyboard-driven

Every action has a shortcut. Grid navigation, lightbox, favorites, settings — fully operable without a mouse.

Wallhaven client

Auto-downloads wallpapers based on your preferences. Browse and search Wallhaven directly from the GUI.

Auto orientation

Portrait monitors get portrait wallpapers. No manual sorting needed.

Three-tier purity

SFW, Sketchy, NSFW — independently toggleable. Persistent across sessions.

Cross-platform

macOS and Linux (Hyprland/Sway). CLI + GUI + MCP — pick your interface.

Pool management

Validates, resizes, rotates. Favorites, blacklist, history navigation — all built in.

JSON output

--json flag on every command for scripting and automation.

Install

Arch (AUR)
macOS
From source
paru -S wayper     # or: yay -S wayper
# Download the latest .dmg from GitHub Releases
curl -LO https://github.com/yuukidach/wayper/releases/latest/download/wayper.dmg
open wayper.dmg
# Drag wayper.app to Applications, then run from Launchpad or:
wayper-gui
git clone https://github.com/yuukidach/wayper.git
cd wayper
uv venv && uv pip install -e .

Usage

wayper daemon               # start background rotation + downloads
wayper next                 # next wallpaper (forward or new random)
wayper prev                 # previous wallpaper from history
wayper fav [--open]         # favorite current wallpaper
wayper unfav                # remove from favorites
wayper ban                  # blacklist + switch
wayper unban                # undo last ban
wayper mode                 # toggle sfw↔nsfw (preserves sketchy)
wayper mode sketchy         # toggle sketchy on/off
wayper mode sfw,sketchy     # set exact purity combination
wayper status               # show current state
wayper-gui                  # GUI app
wayper setup                # install .desktop entry (Linux)
wayper --json status        # machine-readable output

GUI

browse window

wayper-gui — browse your pool, favorites, and banned wallpapers. Quick actions, daemon control, settings. Designed to be fully operable without a mouse.

Grid view

1 2 3 pool / fav / blocklist
Enter / Space preview (lightbox)
h / l prev / next wallpaper
f favorite
x / Del ban / remove
z undo ban
o open on Wallhaven
F1 F2 F3 toggle SFW / Sketchy / NSFW
s settings
/ focus search bar
Esc clear search / unfocus
Arrow keys navigate grid
[ / ] blocklist: recoverable / all
4–9 switch monitor

Lightbox preview

← / → previous / next image
Enter set as wallpaper
f favorite
x / Del ban
o open on Wallhaven
Space / Esc close lightbox

MCP

Built-in MCP server lets AI assistants control your wallpapers. Ask Claude to "favorite this wallpaper" or "switch to something with mountains" — it just works.

{
  "mcpServers": {
    "wayper": {
      "command": "/path/to/.venv/bin/wayper-mcp"
    }
  }
}

Tools: status next_wallpaper prev_wallpaper fav unfav ban unban set_mode delete_wallpaper

Keybindings

Bind wayper commands to your compositor shortcuts for instant wallpaper control.

Hyprland
AeroSpace (macOS)
bind = $mod, F9,       exec, wayper ban
bind = $mod SHIFT, F9, exec, wayper unban
bind = $mod, F10,      exec, wayper fav
bind = $mod SHIFT, F10,exec, wayper unfav
bind = $mod CTRL, F10, exec, wayper fav --open
bind = $mod, F11,      exec, wayper next
bind = $mod SHIFT, F11,exec, wayper prev
bind = $mod, F12,      exec, wayper mode
bind = $mod SHIFT, F12,exec, wayper mode sketchy
exec-once = wayper daemon
cmd-shift-n = 'exec-and-forget wayper next'
cmd-shift-b = 'exec-and-forget wayper ban'
cmd-shift-f = 'exec-and-forget wayper fav'

Requirements