#wallpaper #command-line #interval #swww

app caydence

a wallpaper switching utility with pomodoro capabilities

4 releases

0.2.1 May 4, 2024
0.2.0 Apr 14, 2024
0.1.1 Apr 14, 2024
0.1.0 Mar 2, 2024

#5 in #wallpaper

Download history 161/week @ 2024-03-02 11/week @ 2024-03-09 3/week @ 2024-03-16 16/week @ 2024-03-30 4/week @ 2024-04-06 227/week @ 2024-04-13 6/week @ 2024-04-20 186/week @ 2024-05-04 1/week @ 2024-05-11 5/week @ 2024-05-18 1/week @ 2024-05-25

193 downloads per month

MIT license

357 lines


caydence is a small utility built on top of swww. the main goal is to switch wallpapers at specific intervals. it switches the wallpapers in two manners:

  • at regular intervals. the default is every 20 minutes, which i use as a reminder to look away from the screen;
  • according to the pomodoro method.
    • wallpaper switches are announced via libnotify when in this mode.


the tool is best used when you have your wallpaper in sight as you work. for those that don't use gaps/blur, i suggest looking elsewhere for a dedicated timer app (might i suggest pogodoro? :P)



to get started, run caydence daemon <wallpaper directory>. this will prompt the daemon to switch wallpapers every 20 minutes. you may want to pipe stdout to a log file, e.g. caydence daemon &> /tmp/caydence.log.

run one of the query commands via caydence client, e.g., caydence client toggle to switch to pomodoro mode. caydence will respond to client commands via libnotify.

there are a number of customisation options available; run caydence help <command> to see more.

the idea is that the daemon is started in a launch script on your wm/dm, and the client commands are given keybinds. in my sway config, i have:

exec swww init
exec ~/.cargo/bin/caydence daemon ~/.config/sway/wallpapers/

bindsym $mod+p exec ~/.cargo/bin/caydence client toggle
bindsym $mod+x exec ~/.cargo/bin/caydence client skip
bindsym $mod+t exec ~/.cargo/bin/caydence client time


caydence requires swww to run (and hence, can only be run on wayland). an error message will be printed if it isn't found on the path when running the daemon.

to install, run cargo install caydence.

nix flake

caydence is a nix flake, so if you're running flakes on nixOS you can install it via adding it to your inputs:

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    caydence.url = "github:joshcbrown/caydence";

and then adding it to a list of packages via caydence.packages.${pkgs.system}.default.

i'm pretty sure this is total overkill, but i'm having fun so


~235K SLoC