breadbox

A GTK4 app launcher for Hyprland / Wayland on Arch Linux.

breadbox-shared   shared types (DesktopEntry, IconCache, Config)
breadbox-sync     standalone icon resolution + caching binary
breadbox          GTK4 layer-shell launcher

Features

• Layer-shell window, centered 600 px wide, keyboard-exclusive
• Reads the active Hyprland workspace and sorts apps by context priority
• Fuzzy filtering as you type; Enter launches, Escape closes
• App icons loaded from the resolved icon cache (see breadbox-sync)
• Accent colors from bread-theme's palette cache; background/surface/overlay/foreground stay fixed BOS dark
• User CSS override at ~/.config/breadbox/style.css
• Toggle/dismiss: running a second instance kills the first

Build dependencies

gtk4                (pacman -S gtk4)
gtk4-layer-shell    (pacman -S gtk4-layer-shell)
librsvg             (pacman -S librsvg)   # for SVG icon support
rust (stable)       (rustup toolchain install stable)

Build

# debug
cargo build

# release (recommended: put both binaries on $PATH)
cargo build --release
# binaries are at target/release/breadbox and target/release/breadbox-sync

Install to ~/.cargo/bin (or anywhere on your PATH):

cargo install --path breadbox
cargo install --path breadbox-sync

Configuration

Copy and edit the example config:

mkdir -p ~/.config/breadbox
cp config.example.toml ~/.config/breadbox/config.toml

The [[context]] blocks map Hyprland workspace names to app priority lists. Workspace name "default" is the catch-all fallback.

[[context]]
name = "default"
priority = ["firefox", "code", "obsidian", "kitty"]

[[context]]
name = "2"
priority = ["slack", "discord"]

CSS theming

breadbox applies bread-theme's accent palette automatically. To override or extend the theme:

~/.config/breadbox/style.css

This file is loaded at the highest CSS priority level, so any rule here wins.

Icon sync

breadbox-sync resolves icons for all installed apps and writes them to ~/.cache/breadbox/. Run it once before first launch:

breadbox-sync

Icon resolution order:

1. System icon theme (~/.local/share/icons, /usr/share/icons, /usr/share/pixmaps): 64 px > 48 px PNG, then SVG
2. Flathub media server, for reverse-DNS app IDs (e.g. org.gnome.Gedit)
3. icon.horse, downloaded and cached
4. application-x-executable fallback from system theme

Systemd service (run on login)

cp packaging/breadbox-sync.service ~/.config/systemd/user/
systemctl --user enable --now breadbox-sync.service

The service runs breadbox-sync once at login (after network is up) and logs to journald. Re-run manually after installing new apps:

systemctl --user start breadbox-sync.service
# or just:
breadbox-sync

Hyprland keybind

Add to ~/.config/hypr/hyprland.conf:

bind = $mainMod, SPACE, exec, breadbox

Pressing the keybind again while the launcher is open dismisses it.

Diagnostics

breadbox keeps a bounded, private input and main-loop log at $XDG_STATE_HOME/breadbox/breadbox.log (or $HOME/.local/state/breadbox/breadbox.log when XDG_STATE_HOME is unset). The log records keycodes and modifier bits, search focus changes, query timing and result counts, and a 500 ms heartbeat while the window is open. It does not record typed characters or search text. One previous log is kept as breadbox.log.1.

Run breadbox --bug-report to print a copyable report with recent diagnostic events and a small allowlist of session details. Review the report before sharing it.

Licence

MIT, see LICENSE.