20-20-20

Disclaimer: every file in this repository — scripts, configs, and this README — was generated by Claude Code through a guided conversation. Review before running on your system.

Every 20 minutes, look at something 20 meters away for 20 seconds.

A tiny break reminder for sway/Wayland on Linux. Fires a warm-yellow kitty popup on the laptop screen (eDP-1 / $display_laptop) that plays a short video as ASCII art via tplay for 20 seconds. Esc or Q skips early.

The video is downloaded once with yt-dlp into ~/.cache/20-20-20/eye.mp4 and reused on every tick.

What it does

• systemd --user timer fires every 20 min while the user session is up (pauses during suspend; doesn't catch up after resume).
• 20-20-20-tick is the per-fire wrapper. It exits silently when:
  • the user has paused 20-20-20 (waybar toggle → ~/.cache/20-20-20/disabled flag);
  • sway isn't running;
  • eDP-1 is disabled;
  • any window is fullscreen on eDP-1 (mirrors idle_inhibitor behaviour).
• 20-20-20-popup runs timeout 20s tplay -x -l ~/.cache/20-20-20/eye.mp4 inside the warm #f5c971 kitty window. tplay's own keys apply — press q to skip early.
• 20-20-20-fetch-video downloads the YouTube clip once via yt-dlp into ~/.cache/20-20-20/eye.mp4. 20-20-20-tick calls it lazily if the file is missing.
• Sway for_window rule pins app_id="20-20-20-popup" to $display_laptop and fullscreens it.
• Waybar custom module custom/eyebreak shows the eye-open / eye-closed icons that used to live on idle_inhibitor. Click to toggle. The existing idle_inhibitor module gets re-skinned with Zzz icons.

Layout

bin/
  20-20-20-popup.sh        # tplay launcher (20s ASCII video)
  20-20-20-tick.sh         # wrapper invoked by systemd
  20-20-20-toggle.sh       # waybar on-click handler
  20-20-20-fetch-video.sh  # one-shot yt-dlp downloader
waybar/
  20-20-20-status       # custom module's exec script
  config.snippet.jsonc  # waybar config snippets to merge by hand
  style.snippet.css     # optional css for the new module
systemd/
  20-20-20.service
  20-20-20.timer
sway/
  20-20-20              # for_window rule, copied to config.d/
install.sh              # idempotent installer

Porting to your system

This was written against one specific setup (sway + waybar + kitty + cargo tplay, with eDP-1 as the laptop output and $display_laptop defined in sway's config.d/outputs). If that matches you, ./install.sh is basically all there is. If it doesn't, two places need attention:

• Wayland / sway: the tick script hardcodes eDP-1 (the standard name for an internal laptop panel) in two swaymsg queries, and the sway rule references $display_laptop. Change both to match your output names (swaymsg -t get_outputs will list them). Non-sway compositors won't work as-is — swaymsg IPC is sway-specific.
• Waybar: the config snippet has to be merged by hand into your existing config.jsonc. The custom module name is custom/eyebreak. The eye glyphs assume a Nerd Font is loaded for the waybar font stack.

Everything else (systemd unit, scripts, tplay/yt-dlp invocations) is distro-agnostic.

Install

./install.sh

Then do the manual waybar edits the script prints (waybar's config can't be safely merged by sed, so it's left to you — snippets are in waybar/config.snippet.jsonc).

Usage

• Pause/resume: click the eye in waybar, or run 20-20-20-toggle.
• Fire immediately for testing: ~/.local/bin/20-20-20-tick.
• Inspect timer: systemctl --user list-timers 20-20-20.timer.

Dependencies

kitty, python3, swaymsg, jq, waybar, systemd. All already present on the target machine.