A cross-platform image overlay for Linux and macOS, written in pure C. Fire it from a git pre-push hook when your checks fail — it slaps an image above every other window, centered on screen, until you click or press Escape.

Download latest release View on GitHub

What it does

When invoked, ysnp displays an image — at its own native size, centered on the screen — on top of all other windows. No arguments, no message, just the image. Animated GIFs loop until dismissed. Click the image or press Escape to close it.

It's built to be fired from a pre-push hook: when your tests or linters fail, the push is blocked and a wizard appears to tell you, in no uncertain terms, that you shall not pass. Out of the box it ships with the animated Gandalf "You shall not pass!" GIF compiled in, so it works with no external image at all.

Above everything

Renders centered, on top of every other window — using wlr-layer-shell on Wayland and a borderless Cocoa overlay on macOS.

Hook-driven

Designed to fire from a git pre-push hook when checks fail, so a failed push is impossible to miss.

Animated GIFs

PNG, JPEG, and animated GIF support. GIFs loop on schedule with no busy-looping until you dismiss them.

Pure C, tiny

Pure C with a single Objective-C file for macOS Cocoa. main.c contains zero #ifdef — every platform difference lives in its own overlay file.

Your own images

Drop your own .png, .jpg, or .gif files into a config directory; ysnp picks one at random on each invocation.

Diagnostics built in

Launched in the background from a hook, so every error is logged with a timestamp and surfaced as a desktop notification — you always see why nothing appeared.

Install

Prebuilt binary

Download the binary for your platform from the latest release — ysnp-linux-x86_64 or ysnp-macos-arm64 (Apple Silicon). Each release also ships a SHA256SUMS file you can verify against.

chmod +x ysnp-*                  # make it executable
mv ysnp-* ~/.local/bin/ysnp      # put it on your PATH
mkdir -p ~/.config/ysnp/images   # where ysnp looks for images

macOS: the binary is unsigned, so Gatekeeper quarantines it on first run. Clear the flag (or right-click → Open once):

xattr -d com.apple.quarantine ~/.local/bin/ysnp

From source

On Linux you'll need wayland-client, cairo, libjpeg, giflib, wayland-scanner, and a wlroots-based compositor (Sway, Hyprland, labwc, river, …) for the wlr-layer-shell protocol. On macOS you only need the Xcode command line tools.

make           # build ./ysnp
make install   # install to ~/.local/bin and create the images dir
make test      # run the unit tests (AddressSanitizer + UBSan)

Git hook

Copy the sample hook into your repo and make it executable, then edit it to run your actual tests or linters. When they fail, the hook launches ysnp and blocks the push.

cp hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Or let the Makefile drop it into the current repo for you:

make install-hook

Adding images

Drop .png, .jpg, .jpeg, or .gif files into ~/.config/ysnp/images/ (extension match is case-insensitive). On each invocation ysnp picks one at random. If the directory is empty or missing, it falls back to the compiled-in default — the animated Gandalf "You shall not pass!" GIF. The overlay is always shown at the image's native size, centered on the screen, never stretched to fill.

Supported platforms

Learn More

For full documentation and source, see the GitHub repository.