App Launcher Base

A minimal native macOS launcher base built with SwiftUI. Clone or fork it when you want a small, hackable launcher that you or a coding agent can customize into your own command palette.

Why This Exists

This repository is intended as a starting point, not a finished product with someone else's personal workflow baked in. The base app includes app discovery, search, settings shortcuts, system actions, calculator results, a global hotkey, tests, and packaging. Add your own app aliases, website commands, URL schemes, ranking tweaks, or custom actions on top.

The repo includes AGENTS.md and REQUIREMENTS.md so coding agents have a clear map of how to build, test, package, and keep product behavior documented while they modify the app.

Base Features

• Scans /Applications, /System/Applications, and ~/Applications for installed .app bundles.
• Includes currently running regular apps in launcher results.
• Watches application folders and refreshes results while the app is running.
• Searches app names, bundle identifiers, System Settings keywords, and system shortcut keywords.
• Ranks exact, prefix, substring, and fuzzy matches.
• Opens apps and selected System Settings panes.
• Includes Sleep, Dark Mode, and Light Mode system shortcuts.
• Evaluates arithmetic expressions and copies the result to the clipboard.
• Supports keyboard navigation with Up, Down, Return, Enter, and Escape.
• Shows a lightweight launcher panel over the active Space, including full-screen apps.
• Mirrors launcher panels across multiple connected displays.
• Runs in the background and toggles with Command + Space.
• Packages into a local App Launcher.app bundle with a generated icon.

Requirements

• macOS 26.5 or newer
• Xcode with Swift 6.3 or newer
• Swift 6.3 or newer

Check your Swift version:

swift --version

Clone Or Fork

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/YOUR-USER/app-launcher-base.git
cd app-launcher-base

Or clone this repository directly if you only want a local copy:

git clone REPOSITORY-URL
cd app-launcher-base

After cloning, ask your coding agent to read AGENTS.md and REQUIREMENTS.md before making behavior changes.

Run Locally

swift run AppLauncher

Build

swift build

Test

swift test

Create And Install The App

Build the Swift package first:

swift build

Create the local macOS app bundle:

scripts/setup-app-bundle.sh

This creates App Launcher.app in the repository root.

Install the locally built app into /Applications:

scripts/setup-app-bundle.sh --install

Build, install, and open it:

scripts/setup-app-bundle.sh --install --open

On first use, grant Accessibility permission in System Settings if you want Command + Space to override foreground apps that capture the same shortcut.

Customize With Coding Agents

Good first modifications:

• Rename the app, bundle identifier, version, and icon in scripts/setup-app-bundle.sh.
• Add custom result types in Sources/AppLauncher/LauncherResult.swift.
• Add launch behavior in Sources/AppLauncher/AppLauncher.swift.
• Adjust search and ranking in Sources/AppLauncher/AppLauncherViewModel.swift.
• Update the SwiftUI surface in Sources/AppLauncher/AppLauncherView.swift.
• Add or update focused tests in Tests/AppLauncherTests.
• Keep product behavior current in REQUIREMENTS.md.

When behavior changes, update tests and REQUIREMENTS.md, then run:

swift test
swift build
scripts/setup-app-bundle.sh

Project Layout

• Sources/AppLauncher/AppLauncherApp.swift defines the app entry point.
• Sources/AppLauncher/AppLauncherView.swift contains the main SwiftUI launcher UI.
• Sources/AppLauncher/AppLauncherViewModel.swift handles search, ranking, selection, and launch state.
• Sources/AppLauncher/AppScanner.swift discovers installed .app bundles.
• Sources/AppLauncher/AppLauncher.swift opens apps, settings, shortcuts, and calculator results.
• Sources/AppLauncher/LauncherResult.swift defines searchable launcher result types.
• Tests/AppLauncherTests contains focused scanner, view model, window, launcher, and packaging tests.

Product Requirements

See REQUIREMENTS.md for product behavior, platform constraints, and quality expectations.

License

MIT. See LICENSE.