Floodlight

Floodlight is a keyboard-first Spotlight alternative for macOS, written in SwiftUI and powered by the FFF Swift package.

It searches files and folders with FFF's fuzzy ranking, live filesystem watcher, query history, and frecency database. Native catalogs add applications and System Settings. Floodlight also evaluates arithmetic, provides a web-search fallback, supports Quick Look, and opens or reveals results without touching the mouse.

• Global ⌘Space invocation, with automatic ⌥Space fallback while Apple's Spotlight still owns the shortcut
• FFF fuzzy search across files and folders
• Relative, absolute, and ~/ path queries with directory-only trailing-slash search
• Time-budgeted FFF content search when filename matches are sparse
• Live file and folder index updates
• Persistent FFF frecency and query history
• FFF-ranked application search via a package-marker index
• Native System Settings search
• Searchable Floodlight settings for shortcuts, permissions, and scope
• Arithmetic with precedence, parentheses, powers, and percentages
• Web-search fallback in the default browser
• Open, Finder reveal, Quick Look, copy, and drag actions
• Configurable indexing scope and manual index rebuild
• Multi-display placement, full-screen space support, and menu-bar access
• Optional launch at login

• macOS 14 or newer
• Xcode command-line tools with Swift 5.10 or newer

make run

Swift Package Manager downloads the versioned FFFKit XCFramework automatically. Building Floodlight does not require Rust or a separate FFF checkout.

Create a signed ad-hoc application bundle:

make bundle
open .build/Floodlight.app

For normal use, install Floodlight at a stable app path:

make install

This installs to ~/Applications/Floodlight.app with a stable designated code requirement. Grant macOS file access to that installed copy once; the grant persists on later launches and development rebuilds. Set FLOODLIGHT_INSTALL_DIR to choose another install directory.

Run the test suite:

make test

Build the Astro documentation site:

npm --prefix docs install
make docs

Create a local development DMG:

make dmg

Local bundles and DMGs use ad-hoc signing. Tagged GitHub releases use the Developer ID signing and notarization workflow in .github/workflows/release.yml.

The Finder/DMG icon is generated from Sources/Floodlight/Resources/AppIcon.png with make icons. The menu bar uses the separate monochrome FloodlightMenuBar.svg vector as a template image so macOS supplies the correct foreground color for every appearance and state.

Floodlight tries ⌘Space first and falls back to ⌥Space when another macOS feature owns the shortcut. Follow the Replace Spotlight guide to use ⌘Space and restore Spotlight later if needed.

See the complete keyboard shortcut reference.

SwiftUI search panel
  └─ SearchCoordinator
      ├─ FFFKit → static XCFramework → vendored fff-search
      ├─ ApplicationCatalog → private app markers → a second FFFIndex
      ├─ SystemCatalog
      ├─ Calculator
      └─ QuickLookController / NSWorkspace

Each FFF instance serializes its own calls on a high-priority queue. Application and System Settings matches are published immediately; the asynchronous file and application-marker searches then run concurrently. File search waits 35 ms when there is no immediate app match, or 180 ms when an app is already visible, and stale generations are discarded.

macOS applications are directory packages, while FFF indexes regular files and derives directories from indexed file paths. Floodlight discovers apps in standard system, user, and CoreServices locations without descending into their packages. It writes one empty marker per app under its private Application Support directory and gives that marker tree to a dedicated FFF instance. The marker result maps back to the real bundle URL, so app fuzzy scoring, frecency, and query history use FFF without indexing every package file. .app bundles elsewhere inside the selected scope are also recognized by the main FFF index.

Floodlight indexes the current user's home directory by default. Change the scope with ⌘L, or from the menu-bar flashlight. The main file index is rebuilt in memory at launch. Persistent FFF history, frecency data, and private app markers stay on the Mac under ~/Library/Application Support/Floodlight.

macOS privacy rules still apply. To search protected locations, grant Floodlight Full Disk Access in System Settings → Privacy & Security.

Floodlight currently covers local apps, files, folders, settings, calculations, previews, and web handoff. See sources not yet integrated for the current Contacts, Photos, Mail, Messages, and Spotlight metadata boundaries.

Floodlight is available under the MIT License.