# F4

> F4 is a free, open-source meme launcher for macOS: a Spotlight-like floating panel that searches a local folder of memes, GIFs and stickers and copies one to the clipboard in a keystroke. Native Swift app (SwiftUI and AppKit), macOS 14 Sonoma or later, Apple Silicon and Intel, MIT license, no special permissions, no tracking, no account. The interface is English, with an Italian translation when macOS runs in Italian.

Key facts:

- The default shortcut is the F4 key alone, from any app; it can be changed in Settings (a function key works alone, any other key needs Command, Option or Control). On a Mac keyboard F4 is a media key (Spotlight or Launchpad) unless the user holds fn (fn-F4) or turns on "Use F1, F2, etc. keys as standard function keys" in System Settings > Keyboard > Keyboard Shortcuts > Function Keys. The panel floats above everything, including full-screen apps, and has no Dock icon (the app lives in the menu bar).
- It reads one folder, `~/Pictures/Memes` by default or any folder picked in Settings, and watches it with FSEvents so new files appear without a restart. Subfolders become categories you can search.
- Supported files today: GIF, PNG, JPEG, WebP (WhatsApp and Telegram stickers). HEIC and short videos are planned.
- Type to search (fuzzy, on file names), arrow keys to move in the grid, Tab or ⌘1–⌘3 to switch between the All, GIFs and Stickers tabs, Enter to copy, Escape to close. Favourites and recently used memes are ranked first.
- Copying writes the file URL (`public.file-url`) and the raw file bytes under the file's UTI, never a decoded `NSImage`, so GIFs stay animated when pasted into Slack, Discord or Telegram.
- Auto-paste (a simulated Command-V into the frontmost app) is optional and the only feature that needs the Accessibility permission; everything else works without any permission, because the global shortcut uses Carbon `RegisterEventHotKey`.
- The empty state draws the "F4, basito" face from the Italian series Boris in code; a `.basito.png`, `.gif` or `.jpg` in the meme folder replaces it. The app ships with no images of its own. Typing some Boris or The Office lines, or the Konami code, in the search field triggers easter eggs.
- A Raycast extension in the same repository searches the same folder.
- A starter pack is built in, so the panel is never empty: animated emoji GIFs (Google Noto Emoji, CC BY 4.0) and F4's own stickers, listed after the user's memes, never copied into the folder. Settings → Starter pack hides it.
- Add memes from the panel: ⌘V adds a copied image, sticker, file or image link (WhatsApp/Telegram: right-click a sticker → Copy, then ⌘V in F4), files can be dropped on the panel, and Add opens a file picker. They are saved in `GIFs/` or `Stickers/` in the meme folder.
- In the GIFs and Stickers tabs, GIPHY results follow the local ones (trending when the search is empty). Enter copies one; ⌘D pins it into the meme folder as a favourite.
- F4 updates itself with Sparkle, checking the appcast on this site. Besides that it only talks to GIPHY while the user is in the GIFs or Stickers tab, and downloads image links the user pastes or drops: no analytics, no account, no server.

## Install

- Download the latest DMG from https://github.com/kkratterf/f4/releases/latest/download/F4.dmg and drag F4 to Applications.
- Or one line in Terminal: `curl -fsSL https://raw.githubusercontent.com/kkratterf/f4/main/install.sh | sh`
- Or Homebrew: `brew tap kkratterf/f4 https://github.com/kkratterf/f4 && brew install --cask f4`
- The app is not notarized by Apple yet. If macOS blocks the first launch, open System Settings > Privacy & Security and click "Open Anyway" next to the F4 message, or run `xattr -dr com.apple.quarantine /Applications/F4.app`. The install script does this for you.
- Uninstall: `curl -fsSL https://raw.githubusercontent.com/kkratterf/f4/main/install.sh | sh -s -- --uninstall`, or `brew uninstall --zap --cask f4`.

## Docs

- [Full reference](https://f4.kkratter.com/llms-full.txt): every setting, key, default, file location, install option and troubleshooting step, in one plain-text file
- [README](https://github.com/kkratterf/f4/blob/main/README.md): every feature, settings, shortcuts, install, privacy, FAQ, build from source
- [Releases](https://github.com/kkratterf/f4/releases): downloads and release notes
- [Issues](https://github.com/kkratterf/f4/issues): bugs, ideas and the roadmap (labels mark area, priority and version)

## Optional

- [AGENTS.md](https://github.com/kkratterf/f4/blob/main/AGENTS.md): for agents that change F4. The code map, build and test, CI, the rules a change must respect, commit and PR format, how a release is cut. Written for AI agents and humans alike.
- [Raycast extension](https://github.com/kkratterf/f4/tree/main/raycast)