macOS GIF Wallpaper

Purpose

Use the bundled native Swift/AppKit template to create a real animated GIF desktop layer on macOS. macOS Finder cannot natively use animated GIFs as wallpapers, so this skill uses a click-through desktop-level app that draws GIF frames with ImageIO and keeps desktop icons/apps usable.

Quick Commands

Install or rebuild the app, point it at a GIF, and launch it:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh \
  --gif "/path/to/wallpaper.gif" \
  --fit cover \
  --install \
  --system-wallpaper \
  --launch

Check current status:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh --status

Use a different GIF without rebuilding:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh \
  --gif "/path/to/new.gif" \
  --fit cover \
  --system-wallpaper \
  --launch

Make it open at login:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh --login

Stop it:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh --quit

Remove launch-at-login:

bash /Users/tec/.codex/skills/macos-gif-wallpaper/scripts/install_gif_wallpaper.sh --remove-login

Workflow

1. Find or confirm the target .gif file. If the user does not provide one, search likely local folders such as ~/Downloads and ~/Desktop with find ... -iname '*.gif'.
2. Run the install script with --gif, --fit cover, --install, --system-wallpaper, and --launch for first-time setup or after template changes.
3. For simple GIF swaps, run the script with --gif, --system-wallpaper, and --launch; rebuilding is not required.
4. If the user wants it to persist after reboot, run --login after the app is installed.
5. Verify with --status; if visual confirmation is needed, use screencapture and compare two screenshots a second apart. A nonzero cmp result usually means the frames changed.

Implementation Notes

• App name: GIF Wallpaper
• Installed path: /Applications/GIF Wallpaper.app
• Preferences domain: local.delilah.gifwallpaper
• Saved GIF key: gifPath
• Fit key: fitMode with cover or contain
• Menu bar controller: ⛧
• Launch agent: ~/Library/LaunchAgents/local.delilah.gifwallpaper.plist

The app intentionally uses native ImageIO frame decoding rather than WebKit because WebKit may display a still frame or throttle animation when placed below desktop icons.

Use --system-wallpaper whenever the user says "make it my wallpaper/background." This extracts a still PNG frame from the GIF and applies it to every macOS desktop via System Events, while the app supplies the motion layer. Without this, the GIF layer can animate, but System Settings will not show the GIF as the native wallpaper.

Troubleshooting

• If the GIF appears still, rebuild and reinstall from this skill. The native animator should be used; older WebKit builds can freeze.
• If nothing appears, run --status, confirm the app is installed/running, and confirm the GIF path exists.
• If the GIF is cropped, switch to --fit contain; if it has black bars, switch back to --fit cover.
• If desktop icons cannot be clicked, the window is not ignoring mouse events; inspect the Swift template in assets/gif-wallpaper-template/Sources/GifWallpaper/main.swift.
• If macOS blocks the app, run xattr -cr "/Applications/GIF Wallpaper.app" and ad-hoc sign with codesign --force --deep --sign - "/Applications/GIF Wallpaper.app".