promptlm-macos

Native macOS menubar app for promptLM.

Lives in your menu bar, opens a Spotlight-style picker via configurable global shortcut, and inserts prompts from local prompt repositories at the cursor position. Prompts with placeholders trigger a small form first.

Status: early scaffold. Menu bar icon only. Picker, hotkey, repository loading, render and paste are tracked in issues.

Requirements

• macOS 13 (Ventura) or later
• Xcode 15+ / Swift 5.9+ (for development)

Build & install

./install.sh             # build, wrap into .app, install to ~/Applications
./install.sh --launch    # also start the app
./install.sh --system    # install to /Applications instead (uses sudo)
./install.sh --uninstall # remove the installed bundle

After install you should see a small chat-bubble icon in the menu bar. Click it to see your prompts, or hit ⌃⌥⌘P anywhere to open the menu without reaching for the menu bar.

Settings

Open with the menu bar icon → Settings… (⌘,):

• Prompt repository — pick the folder the app scans for *.yaml, *.yml, *.json prompt specs.
• Global hotkey — click Record, press your combo (must include ⌘, ⌥, or ⌃). ⎋ cancels.
• Launch at login — uses SMAppService (macOS 13+).

Seeding prompts

By default the app reads from ~/.promptlm/prompts. To try the bundled samples:

mkdir -p ~/.promptlm/prompts
cp docs/sample-prompts/* ~/.promptlm/prompts/

Then click the menu bar icon — the prompts should appear, grouped by their group field. Selecting a prompt:

• with no placeholders → its text is pasted at your cursor
• with placeholders → a form opens with a field per placeholder (defaults pre-filled, required fields marked *); on submit the rendered text is pasted at your cursor

The original clipboard contents are restored ~400 ms after the paste.

Accessibility permission

The first time you select a prompt, macOS will block the synthesized ⌘V. The app shows an alert and offers to open System Settings — flip the toggle for promptLM under Privacy & Security → Accessibility, then try again.

Ad-hoc build caveat: because the install script signs the app ad-hoc (no Developer ID), macOS may treat each rebuild as a different binary and revoke the permission. If pasting silently stops working after ./install.sh, re-grant the toggle. Real signing + notarization will fix this; it is on the roadmap.

If pasting fails for any other reason, the rendered prompt is still copied to your clipboard so you can paste manually.

Prompt file format

YAML or JSON. Minimum:

id: my-prompt
name: My Prompt
text: Hello {{audience}}!
placeholders:
  audience:
    default: world

The app is ad-hoc signed; on first launch macOS may show a Gatekeeper prompt — right-click the app in Finder and choose Open to confirm. Real Developer ID signing + notarization comes later in the roadmap.

For development without bundling:

swift build
swift run PromptLMMac

Or open Package.swift in Xcode and run.

Architecture

See docs/architecture.md for the planned module layout and decisions.

The PromptSpec format is defined by promptlm-app; this client reads a compatible subset (id, name, group, description, request, placeholders).

Roadmap

• Repo scaffold + menu bar icon
• Local folder prompt repository (YAML/JSON) — prompts listed in menu
• Native {{key}} renderer
• Placeholder form (dynamic from PromptSpec)
• Paste-at-cursor insertion with pasteboard restore
• Global hotkey opens the menu (default ⌃⌥⌘P)
• Settings window — repo path picker, hotkey recorder, launch at login
• Spotlight-style quick picker with fuzzy search
• Settings window (repo path, hotkey recorder, autostart)
• Code signing + notarization + DMG release

Sister clients planned for Windows, Linux, iOS, Android — each in its own repo.

License

Apache License 2.0 — see LICENSE.