wayper

Features

Install

paru -S wayper     # or: yay -S wayper

# Download the latest Windows installer from GitHub Releases
# Or install from source:
git clone https://github.com/yuukidach/wayper.git
cd wayper
uv venv
uv pip install -e .

# 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 dislike              # teach model, blacklist + switch
wayper ban                  # exact-image block only + switch
wayper unban                # undo last dislike or ban
wayper mode                 # toggle sfw↔nsfw (preserves sketchy)
wayper mode sketchy         # toggle sketchy on/off
wayper mode sfw,sketchy     # set exact purity combination
wayper model train         # train the lightweight local metadata ranking model
wayper model score --tags "tag1,tag2"  # explain a local dislike score
wayper model status        # inspect local model validation
wayper status               # show current state
wayper-gui                  # GUI app
wayper setup                # install .desktop entry (Linux)
wayper --json status        # machine-readable output

wayper model train reads only local Wallhaven metadata (normalized tags and compact color/category/purity context); it never opens image files or inspects pixels. The base model uses the standard library. Install uv pip install -e '.[semantic]' to enable the optional FastEmbed BAAI/bge-small-en-v1.5 text head, which encodes metadata only and keeps a persistent local embedding cache. Before any Review decisions exist, an installation may temporarily bootstrap from its older blacklist/favorite data. Once a Review decision or manual Dislike is recorded, only explicit Keep/Dislike decisions become new training labels; ordinary Ban remains outside the label stream. The semantic head learns related metadata patterns from those examples, without a manually configured person or region rule. Tag pairs remain opt-in with --max-combos. Live pool images are background controls unless explicitly kept. Wayper reserves the most recent part of each explicit Keep/Dislike class to learn an accuracy-first Review boundary that weights precision more than recall. Recommended and Auto-held use the same binary decision: scores below the learned boundary are omitted, and the page size is a maximum rather than a target to fill. Exact and semantic evidence only rank images that have already crossed the boundary. Open the dedicated Review view to control this loop. The sidebar chooses Rules, Model, or Rules + model for new downloads without disabling recommendations. Two explicit card lanes keep automatically quarantined downloads (Auto-held) separate from likely blocks already in the pool (Recommended); pending Auto-held cards open first. Drag, scroll, or use the side arrows to move through the full-window card stack. Press Enter/Space for the full preview, A to keep, or D to dislike and teach the model. An Auto-held Keep releases the file into the pool, while a recommendation Keep records a positive correction without moving it. Because Auto-held files are recoverable and require a human decision, a current trained model can quarantine likely blocks without the separate validation gate used for unattended deletion. Wayper refreshes the model locally after enough new feedback.

GUI

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

Grid view

Lightbox preview

MCP

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

# Codex (~/.codex/config.toml)
[mcp_servers.wayper]
command = "/path/to/wayper/.venv/bin/wayper-mcp"

# Claude Code (~/.claude/.mcp.json)
{
  "mcpServers": {
    "wayper": {
      "command": "/path/to/wayper/.venv/bin/wayper-mcp"
    }
  }
}

Tools: status next_wallpaper prev_wallpaper fav unfav dislike ban unban set_mode delete_wallpaper wallpaper_info tag_stats_top tag_stats_lookup tag_stats_combo uploader_stats_lookup

Keybindings

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

bind = $mod, F9,       exec, wayper ban
bind = $mod CTRL, F9,  exec, wayper dislike
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

• Python 3.12+
• Wallhaven API key
• Linux: awww, Hyprland
• macOS: Python 3.12+, Node.js
• Windows: Windows 10/11, Python 3.12+, Node.js