1# Haven23Haven is a macOS menu bar app for browsing [Wallhaven](https://wallhaven.cc)4and setting your desktop wallpaper. You can also browse images in local5folders, save favorites, and return to wallpapers you've used before.67## Using Haven89Click Haven's menu bar icon to open it. The app has no Dock icon.1011| Tab | What you can do |12| --- | --- |13| Explore | Search Wallhaven or browse Latest, Toplist, and Random. Open the slider controls to filter by category, purity, resolution, or aspect ratio. More results load as you scroll. |14| Local | Browse images from your source folders, including when you're offline. Haven skips files it can't read as images. |15| Favorites | Revisit wallpapers you've marked with a heart. |16| History | Find wallpapers you've recently set. |17| Settings | Choose storage and source folders, turn local saving on or off, and enable launch at login. |1819Click a wallpaper to set it on your active display. Haven uses Wallhaven's20public search API, so you don't need an API key. Browsing is limited to SFW21and Sketchy content, with General, Anime, and People category filters.2223When local saving is enabled, downloaded wallpapers go to `~/Pictures/Haven`24by default. Choose another folder in Settings → Storage → Location. Use25Source folders in Settings to add other folders to the Local tab.2627If Wallhaven is unavailable, Explore explains the outage and gives you a28link to its status page and a retry button.2930## Building and running3132You'll need macOS 13 (Ventura) or later and a Swift 6.1+ toolchain, provided33by Xcode or the Swift command-line tools.3435Build an ad-hoc signed `.app` bundle and launch it:3637```sh38./bundle_app.sh39open Haven.app40```4142To run during development:4344```sh45swift build46swift run47```4849## Tests and coverage5051Run the test suite and the checked-in coverage check:5253```sh54bash coverage.sh55```5657The script runs `swift test --enable-code-coverage` and a smoke run of the58executable to measure the entry point. It requires 100% coverage of physical59source lines, excluding blank lines, comment-only lines, and structural60brace lines. The LLVM aggregate report also counts compiler-generated61SwiftUI mappings, so its percentage can be lower.6263The last recorded coverage run left 27 UI lines uncovered. The coverage64check requires those lines to be covered even when the tests pass.6566## Source layout6768```69Sources/Haven/70 API/ Wallhaven client and response models71 Managers/ Wallpaper, local library, favorites, history, autostart, cache72 UI/ AppState, menu bar controller, and SwiftUI views73 main.swift Entry point74```7576## License7778Haven is licensed under the GNU General Public License, version 3 or any79later version. You may redistribute and modify it under those terms.80See [`LICENSE`](LICENSE) for the full text.8182```83Haven — a macOS menu bar app for browsing, setting, and managing wallpapers.84Copyright (C) 2026 Asha Software85```