Installing

Snag is built from source. Linux only.

System packages

Three of the Rust dependencies link C libraries that must be installed first.

Distribution	Command
Arch, Omarchy	`sudo pacman -S --needed gtk3 webkit2gtk-4.1 libsoup3 libdbusmenu-gtk3`
Debian, Ubuntu	`sudo apt install build-essential pkg-config libdbus-1-dev libgtk-3-dev libwebkit2gtk-4.1-dev libx11-dev`
Fedora	`sudo dnf install gtk3-devel webkit2gtk4.1-devel dbus-devel libX11-devel`

Library	Used for
WebKitGTK 4.1	the three windows are web views
GTK 3	windowing
libsoup 3	WebKitGTK's HTTP stack
libdbusmenu-gtk3	the tray icon's menu

The sign-in token is kept in the desktop secret service (org.freedesktop.secrets). A desktop install normally has one already (GNOME Keyring, KWallet). A minimal install may not, and snag login says so.

Rust 1.90 or later is required.

Build and install

cargo build --release
install -Dm755 target/release/snag ~/.local/bin/snag

Use a release build for daily use. A debug build is large and noticeably slower.

snag login

Enter the server address of your Snag account, or press Enter to keep the one shown.
Snag prints the page where a personal access token is created, and opens it in the browser when a display is available.
Create a token and paste it.

The token is checked straight away. It needs these abilities:

Ability	For
`tasks:read`, `tasks:write`	capture, the task picker
`time:read`, `time:write`	the timer, time logs
`knowledge:write`	notes (optional; without it only notes are refused)

A token missing one of the first four is refused at login, with the missing ability named.

snag login also reads a token from standard input when it is not a terminal, and then prompts for nothing:

pass show snag | snag login

snag whoami shows the account, the abilities, the expiry and which store holds the token. snag logout removes it.

Start the daemon

snag run is the background process: tray icon, timer window, idle detection. One runs per session.

To start it at login, use the systemd user unit in contrib/systemd/snag.service:

mkdir -p ~/.config/systemd/user
cp contrib/systemd/snag.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now snag.service

The unit runs snag run --tray (no window on start), restarts on failure and logs to the journal (journalctl --user -u snag -f).

Without uwsm, a user unit may not see the compositor's environment. Add this to the compositor's startup:

systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP

Desktop setup

The app cannot set its own keybinds or window sizes on a tiling compositor, so contrib/ ships config to paste in.

File	For
`contrib/hypr/snag.conf`	Hyprland (and Omarchy 3): window rules and keybinds
`contrib/hypr/snag.lua`	Omarchy 4's Lua Hyprland config: the same rules and keybinds
`contrib/waybar/README.md`	Waybar: the `custom/timer` module that shows the running time
`contrib/quickshell/`	Omarchy 4's bar: the same module in QML
`contrib/systemd/snag.service`	autostart

On a tiler the window rules are required. Without them each window opens at half the workspace. Every Snag window shares one app id, so every rule matches on the window title as well as the class. The three titles are Snag (timer window), Quick Capture and Idle time.

On GNOME, KDE or another stacking desktop, skip the window rules and set the keybinds in the desktop's keyboard settings. See Keyboard shortcuts for the commands to bind.

Snag has no global shortcuts of its own. Wayland does not let an ordinary app grab keys, so the compositor runs snag commands instead.

Check it worked

snag --version
snag status
snag doctor

snag --version prints one line, such as snag 0.7.0. Quote it in any bug report.

Not available

macOS and Windows.
Prebuilt packages or signed binaries.

Next: Quick capture