MacMenuBarCommandKit

Production-oriented SwiftUI menu bar command shell for macOS.

Part of the Apple Design Templates collection.

MacMenuBarCommandKit is a reusable starter kit for building native menu bar utilities: desktop tools, timers, clipboard workflows, quick notes, system monitors, and productivity apps. It combines a MenuBarExtra, a real main window, command palette, keyboard shortcuts, native Settings, Launch at Login support, deterministic local data, and a clean Swift Package API.

Included

• MacMenuBarCommandKit, a zero-dependency Swift Package.
• A runnable macOS demo app: Examples/CommandKitDemo/CommandKitDemo.xcodeproj.
• Dock-visible launch behavior with a menu bar extra.
• Keyboard-first CommandPalette with search, arrow navigation, Return, Escape, and focus restoration.
• CommandRegistry, CommandStore, DashboardStore, SettingsStore, and LaunchAtLoginService.
• Native SwiftUI Settings scene with General, Appearance, Commands, and About tabs.
• SMAppService Launch at Login wrapper with enabled, disabled, approval, unsupported, and error states.
• Loading, empty, error, and loaded dashboard states.
• Unit tests, GitHub Actions, issue templates, changelog, and release checklist.
• English and Russian documentation.

Demo commands

The demo ships with eight commands. They are intentionally practical and small enough for a menu bar app:

Command	What it demonstrates	Visible result
New Note	Fast local capture	Adds an inbox item and activity entry
Start Timer	Focus/timer workflow	Starts focus state and increases protected time
Capture Clipboard	Pasteboard-driven workflow	Saves copied text into local demo state
Copy Status Report	System clipboard output	Copies a text report to the macOS pasteboard
Clear Inbox	Batch cleanup action	Resets the inbox metric
Toggle Focus Mode	Stateful toggle	Updates focus state and status badges
Open Dashboard	Window navigation	Opens the main workspace
Open Settings	Native preferences	Opens the SwiftUI Settings scene

Preview

Main window	Menu dashboard

Command palette	Settings

Requirements

• Xcode 26 or newer.
• Swift 6.
• macOS 14 or newer.

Run the demo

Open the checked-in Xcode project:

open Examples/CommandKitDemo/CommandKitDemo.xcodeproj

Select the CommandKitDemo scheme and run on My Mac.

Or use the local run script:

./script/build_and_run.sh
./script/build_and_run.sh --verify

Optional: regenerate the Xcode project with XcodeGen:

cd Examples/CommandKitDemo
xcodegen generate
open CommandKitDemo.xcodeproj

Add a command

Add the package in Xcode or declare the released dependency in Package.swift:

.package(
    url: "https://github.com/mikonyaa/MacMenuBarCommandKit.git",
    from: "0.2.0"
)

Commands are metadata first. Define a stable app-owned identifier, add a CommandItem, and register synchronous behavior where your app owns platform actions:

extension CommandID {
    static let exportSummary: CommandID = "export.summary"
}

let command = CommandItem(
    id: .exportSummary,
    title: "Export Summary",
    subtitle: "Save today's local status as Markdown.",
    systemImage: "square.and.arrow.down",
    category: .productivity,
    shortcut: CommandShortcut(modifiers: [.command, .shift], key: "E")
)

registry.replaceCommands(registry.commands + [command])
registry.register(.exportSummary) { command in
    try exportSummary()
    return .success("Exported \(command.title).")
}

See Commands for extension patterns.

Replace demo data

Demo command IDs, fixtures, clipboard storage, and sample side effects live under Examples/CommandKitDemo. The package starts with empty registries and dashboard data, so adopters do not inherit sample business behavior.

Project structure

MacMenuBarCommandKit/
├── Sources/MacMenuBarCommandKit/   Reusable package
├── Tests/MacMenuBarCommandKitTests/
├── Examples/CommandKitDemo/        Runnable macOS app
├── Docs/
├── Assets/
├── Tools/
└── script/build_and_run.sh

Documentation

• Getting started
• Architecture
• Commands
• Migration from 0.1.0 to 0.2.0
• Customization
• Accessibility
• Release checklist

Verification

swift test

xcodebuild \
  -project Examples/CommandKitDemo/CommandKitDemo.xcodeproj \
  -scheme CommandKitDemo \
  -destination 'platform=macOS' \
  CODE_SIGNING_ALLOWED=NO \
  build

Roadmap

The 0.2.0 scope is intentionally focused. Future releases should stay optional:

• App Intents sample commands.
• Optional no-Dock accessory mode recipe.
• Notification authorization recipe.
• Real app icon and signed helper documentation.

License

MIT. Use it in personal, commercial, and open-source projects.