agentleFS
jaskirat1616jaskirat1616/grok-skills/skills/macos-menubar-app/SKILL.md

macos-menubar-app

Skill22 starsChanged 3 months agoMITView on GitHub

Build a production-quality macOS menubar or notch app in SwiftUI, covering MenuBarExtra setup, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and /critique-driven polish cycles. Use when starting or extending a macOS agent app that lives in the status bar or Mac notch area.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create a new macOS App target in Xcode:

    line 38
  2. Very specific:

    Use .menuBarExtraStyle(.window) for a popover-style panel.

    line 71
  3. Distinctive:

    Call this on first launch and prompt the user to grant access in System Settings → Privacy → Accessibility.

    line 136
  4. Distinctive:

    Add sound files to the Xcode target (check Target Membership in file inspector).

    line 154
  5. Distinctive:

    After each implementation slice:

    line 193
  6. Very specific:

    Run /critique: evaluate against Apple HIG, WCAG contrast, interaction consistency

    line 197
  7. Very specific:

    Run /whimsy-injector on completion screens and idle states

    line 199
  8. Distinctive:

    Test on a machine without a notch to verify layout

    line 200

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

🤖 Auto-generated by weekly-pattern-learner · SwiftUI macOS menubar app pattern observed in FocusNotch session, Jun 2026 (364 user turns, ~48 MB transcript covering idea → spec → impl → critique cycles → App Store)

macOS Menubar / Notch App (SwiftUI)

Overview

Build a macOS app that lives in the menu bar or notch using SwiftUI's MenuBarExtra. Covers the full lifecycle: project setup, window management, entitlements, user interaction (keyboard shortcuts, sound), and App Store preparation.

When to Use

  • User asks to build an app for the macOS menubar, status bar, or notch
  • Adding a menubar presence to an existing macOS app
  • Debugging sandbox rejections or entitlement errors in a SwiftUI app

Workflow

1. Project Setup

Create a new macOS App target in Xcode:

  • Interface: SwiftUI
  • App Sandbox: Enabled (required for App Store)
  • Bundle ID: com.yourname.AppName
  • Deployment target: macOS 13+ (for MenuBarExtra)

In Info.plist, set:

<key>LSUIElement</key>
<true/>

This hides the app from the Dock: the menu bar becomes the only entry point.

2. MenuBarExtra (SwiftUI native)

@main
struct FocusApp: App {
    var body: some Scene {
        MenuBarExtra {
            ContentView()
                .frame(width: 320, height: 480)
        } label: {
            Label("Focus", systemImage: "timer")
        }
        .menuBarExtraStyle(.window)
    }
}

Use .menuBarExtraStyle(.window) for a popover-style panel. Use .menuBarExtraStyle(.menu) for a dropdown menu.

3. Notch Detection

On MacBooks with a notch, the safe area changes. Detect and adapt:

func isNotchPresent() -> Bool {
    guard let screen = NSScreen.main else { return false }
    // The notch area is excluded from visibleFrame top
    let screenHeight = screen.frame.height
    let visibleTop = screen.visibleFrame.maxY
    return visibleTop < screenHeight
}

Position windows below the notch:

window.setFrameOrigin(NSPoint(
    x: window.frame.origin.x,
    y: NSScreen.main!.frame.height - window.frame.height - notchOffset
))

4. Sandbox Entitlements

Minimum .entitlements for a sandboxed menubar app:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <!-- Add only what the app actually uses: -->
    <!-- <key>com.apple.security.network.client</key> -->
    <!-- <true/> -->
</dict>
</plist>

For focus/blocking features that need accessibility:

<key>com.apple.security.temporary-exception.apple-events</key>
<array>
    <string>com.apple.systemevents</string>
</array>

5. Accessibility Permission (Focus Detection)

To detect which app is in focus (required for distraction blocking):

import ApplicationServices

func requestAccessibilityPermission() -> Bool {
    let options: NSDictionary = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true]
    return AXIsProcessTrustedWithOptions(options)
}

Call this on first launch and prompt the user to grant access in System Settings → Privacy → Accessibility.

6. Sound Effects

import AVFoundation

class SoundPlayer {
    private var player: AVAudioPlayer?

    func play(_ filename: String, extension ext: String = "mp3") {
        guard let url = Bundle.main.url(forResource: filename, withExtension: ext) else { return }
        player = try? AVAudioPlayer(contentsOf: url)
        player?.play()
    }
}

Add sound files to the Xcode target (check Target Membership in file inspector).

For system sounds (no file needed):

NSSound.beep()
// or
NSSound(named: .init("Hero"))?.play()

7. Keyboard Shortcuts

Global shortcuts (work when app is not focused); requires Accessibility permission:

NSEvent.addGlobalMonitorForEvents(matching: .keyDown) { event in
    if event.modifierFlags.contains([.command, .shift]) && event.keyCode == 36 { // ⌘⇧↩
        // Handle shortcut
    }
}

Local shortcuts (SwiftUI):

.keyboardShortcut("s", modifiers: [.command, .shift])

8. Persistent State (AppStorage)

@AppStorage("timerDuration") private var timerDuration: Double = 25 * 60
@AppStorage("soundEnabled") private var soundEnabled: Bool = true

For complex state, use UserDefaults with a suite name to share across extensions.

9. Polish Cycle

After each implementation slice:

Optional skills: Steps 1 and 3 require /critique and /whimsy-injector from the agent-skills catalog. Install them via skillshare if not already available; skip these steps if not installed.

  1. Run /critique: evaluate against Apple HIG, WCAG contrast, interaction consistency
  2. Fix all P0/P1 findings
  3. Run /whimsy-injector on completion screens and idle states
  4. Test on a machine without a notch to verify layout

10. App Store Preparation

See olko:apple-store-submit for the full submission and rejection-handling workflow.

Pre-submission checklist:

# Validate archive
xcodebuild archive -scheme <AppName> -archivePath build/<AppName>.xcarchive

# Check sandbox
codesign --verify --deep --strict build/<AppName>.xcarchive/Products/Applications/<AppName>.app

# Verify entitlements
codesign -d --entitlements :- build/<AppName>.xcarchive/Products/Applications/<AppName>.app

Key Pitfalls

SymptomCauseFix
App appears in DockLSUIElement missingAdd to Info.plist
Menubar icon missing after buildAsset catalog misconfiguredUse PDF or SVG template image, tick Template Image
Crash on clickView not loaded in popover windowAdd .frame() to MenuBarExtra content
Sound not playingFile not in targetCheck Target Membership in file inspector
Accessibility prompt not shownMissing entitlementAdd temporary-exception.apple-events or use XPC
Notch overlapHardcoded y-positionDetect visibleFrame vs frame delta

Verification

  • App does not appear in Dock (LSUIElement = true)
  • MenuBarExtra icon renders as template image (respects dark/light mode)
  • Sound plays on timer events
  • Keyboard shortcuts respond both globally and locally
  • App passes codesign --verify --deep --strict
  • Layout correct on M1 MacBook (no notch) and M3 MacBook Pro (notch)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.