Haven

A lightweight macOS menu bar app for finding, setting, and managing desktop wallpapers. Browse Wallhaven without leaving the menu bar, set any image as your wallpaper with a click, and keep a local library of the ones you download.

Features

• Explore — search Wallhaven with live filtering by category (General / Anime / People), purity (SFW / Sketchy), resolution, and aspect ratio. Infinite scroll loads more as you go.
• Outage aware — when Wallhaven's own servers are down, the Explore tab explains that where the grid would be, links to Wallhaven's status page, and offers a retry, so an upstream outage never reads as Haven failing.
• Set instantly — click a wallpaper to set it on your active display.
• Local library — wallpapers you download are saved to a folder of your choice and browsable offline. Unreadable or broken image files are skipped automatically so they never clutter the view.
• Favorites & History — keep the ones you love and revisit anything you've set recently.
• Launch at login — optionally start Haven automatically.

Requirements

• macOS 13 (Ventura) or later
• Swift 6.1+ toolchain (Xcode or the Swift command-line tools)

No Wallhaven API key is required — Haven uses the public search API and browses SFW and Sketchy content only.

Build & Run

Build a signed .app bundle and launch it:

./bundle_app.sh
open Haven.app

Or run directly during development:

swift build
swift run

Run the full test suite and the checked-in 100% physical source-line coverage gate:

bash coverage.sh

The coverage command combines swift test --enable-code-coverage with a smoke run of the executable so the real entry point is measured. Its physical source-line gate excludes blank, comment-only, and structural brace lines; the LLVM aggregate report printed above it also includes compiler-generated SwiftUI mappings and can therefore be lower.

Haven lives in the menu bar (it has no Dock icon). Click the menu bar icon to open the popover.

Usage

Tab	What it does
Explore	Search and browse Wallhaven. Use the slider icon to filter.
Local	Browse wallpapers saved to your local folder.
Favorites	Wallpapers you've hearted.
History	Recently set wallpapers.
Settings	Launch at login, local-save toggle, and save-folder location.

By default, downloaded wallpapers are saved to ~/Pictures/Haven. Change this in Settings → Storage → Location.

Project Layout

Sources/Haven/
  API/          Wallhaven client and response models
  Managers/     Wallpaper, local library, favorites, history, autostart, cache
  UI/           AppState, menu bar controller, and SwiftUI views
  main.swift    Entry point

License

Haven is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for the full text.

Haven — a macOS menu bar app for browsing, setting, and managing wallpapers.
Copyright (C) 2026 Asha Software