Documentation

Complete configuration guide for macBuddy — MDM actions, AI, and more.

Concept app. A working exploration of an idea, built and shared to show what's possible — not a supported commercial product. Expect rough edges, no SLA and no roadmap guarantees. It has been tested in a demo environment only, not in production. Try it on test Macs first; feedback is very welcome.

Overview

macBuddy is a macOS menu bar application that executes configurable actions deployed via MDM (Mobile Device Management) systems like Jamf or Intune.

Privacy-first: AI processing runs on-device by default. Data only leaves the Mac if IT adds an external IT support chatbot through MDM (see Chatbot Integration). MDM-managed preferences are read-only for users.

Installation

Copy macBuddy.app to /Applications/ and add it to Login Items for automatic startup:

osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/macBuddy.app", hidden:false}'

macBuddy auto-starts at login by default. This can be disabled via MDM.

Quick Start

# Build and run:
make dev

# Install test configuration:
make test-config

# View available commands:
make help

Action Types

macBuddy supports six action types:

1. Shell Script (ShellScript)

Execute inline shell script content. Written to a temp file and executed.

ScriptContent (required) · Arguments (optional) · RunAsRoot (optional)

2. Run Script (RunScript)

Execute an existing script file from the local filesystem.

ScriptPath (required) · Arguments (optional)

3. Open URL (OpenURL)

Open a URL in the default browser.

URL (required)

4. Restart Service (RestartService)

Restart a system service using launchctl.

ServiceName (required)

5. Run AppleScript (RunAppleScript)

Execute AppleScript code.

AppleScriptContent (required)

Action Chains

Execute multiple actions sequentially. If any action fails, the chain stops.

<dict>
    <key>Id</key>
    <string>full-system-check</string>
    <key>DisplayName</key>
    <string>Full System Check</string>
    <key>ActionType</key>
    <string>ActionChain</string>
    <key>Icon</key>
    <string>checklist</string>
    <key>ChainedActions</key>
    <array>
        <string>clear-dns-cache</string>
        <string>network-check</string>
        <string>update-software</string>
    </array>
</dict>

Action Timeouts

Set a maximum execution time. If exceeded, the action is automatically terminated.

<key>Timeout</key>
<integer>30</integer>

(value in seconds)

Custom Icons

Use SF Symbols or custom image paths:

<key>Icon</key>
<string>lock.shield</string>
<string>/usr/local/icons/custom.png</string>

SF Symbol name or custom file path

Popular SF Symbols: network · arrow.clockwise.circle · lock.shield · wrench.and.screwdriver · checklist · stethoscope

Configuration Format

Configuration is delivered as a Property List (`.plist`) or JSON file.

Property List Example

<?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>Actions</key>
    <array>
        <dict>
            <key>DisplayName</key>
            <string>Restart Network Proxy</string>
            <key>ActionType</key>
            <string>ShellScript</string>
            <key>Settings</key>
            <dict>
                <key>ScriptContent</key>
                <string>#!/bin/bash
networksetup -setwebproxystate Wi-Fi off
sleep 1
networksetup -setwebproxystate Wi-Fi on</string>
            </dict>
        </dict>
    </array>
</dict>
</plist>

Conditional Visibility

Show or hide actions based on system state. All conditions must be true (AND logic).

Type	Parameters
`FileExists`	`Path` (required), `Negate` (optional)
`ProcessRunning`	`ProcessName` (required), `Negate` (optional)
`NetworkConnected`	—
`CommandOutput`	`Command`, `ExpectedOutput`, `Negate`

<key>VisibilityConditions</key>
<array>
    <dict>
        <key>Type</key>
        <string>NetworkConnected</string>
    </dict>
    <dict>
        <key>Type</key>
        <string>FileExists</string>
        <key>Path</key>
        <string>/Library/Logs/troubleshooting.log</string>
    </dict>
</array>

Notification Settings

Add a NotificationSettings dictionary to control notification behavior:

Key	Type	Default	Description
`NotificationsEnabled`	Bool	true	Enable/disable all notifications
`ShowSuccessNotifications`	Bool	true	Show on success
`ShowFailureNotifications`	Bool	true	Show on failure
`ShowConfigReloadNotifications`	Bool	false	Show on config reload
`PlaySoundOnSuccess`	Bool	false	Play sound on success
`PlaySoundOnFailure`	Bool	true	Play sound on failure
`CriticalAlertOnFailure`	Bool	false	Bypass Do Not Disturb
`IncludeOutputInNotifications`	Bool	true	Include script output
`IncludeErrorDetailsInNotifications`	Bool	true	Include error details

Configuration Location

macBuddy reads configuration from managed preferences in priority order:

/Library/Managed Preferences/USERNAME/com.macbuddy.settings.plist (user-scoped)
/Library/Managed Preferences/com.macbuddy.settings.plist (device-scoped)
Built-in demo actions (if no configuration found)

Note: macBuddy uses /Library/Managed Preferences/ (MDM-managed), NOT ~/Library/Preferences/ (user preferences).

Jamf Pro Configuration

Create a new Configuration Profile
Add Application & Custom Settings payload
Set Preference Domain: com.macbuddy.settings
Upload the property list file with your actions
Scope to target computers

Microsoft Intune Configuration

Create a new Device Configuration Profile
Platform: macOS, Profile type: Custom
Upload a .mobileconfig file with the settings payload

Login Item Behavior

To disable auto-launch via MDM:

<key>LaunchAtLoginEnabled</key>
<false/>

Privileged Helper

For actions with RunAsRoot = true, macBuddy can use a privileged helper binary:

<key>PrivilegedHelperEnabled</key>
<true/>
<key>PrivilegedHelperPath</key>
<string>/Library/PrivilegedHelperTools/com.macbuddy.helper</string>

PrivilegedHelperEnabled defaults to false. When disabled, macBuddy falls back to AppleScript admin prompts for RunAsRoot actions.

Chatbot Integration

Enable the integrated IT support chatbot via MDM:

<key>ChatbotSettings</key>
<dict>
    <key>Enabled</key>
    <true/>
    <key>Endpoint</key>
    <string>https://your-chatbot-api.com/chat</string>
    <key>BotName</key>
    <string>IT Assistant</string>
    <key>MenuTitle</key>
    <string>Chat with IT Support</string>
</dict>

File Actions

Right-click any file → Services → macBuddy. All processing runs on-device with Gemma 4.

Menu Item	Output File
Summarize	`filename_summary.txt`
Translate to English	`filename_EN.txt`
Rewrite: Formal	`filename_formal.txt`
Rewrite: Concise	`filename_concise.txt`
Extract Key Points	`filename_keypoints.txt`
Find Action Items	`filename_actions.txt`

Supported File Types

.txt · .md · .rtf · .pdf · .docx · .doc · .csv · .json · .yaml · .log · .swift · .py · .js · .ts · .sh · .html

MDM Configuration

<key>FileActionsSettings</key>
<dict>
    <key>Enabled</key>
    <true/>
    <key>DisabledActions</key>
    <array>
        <string>RewriteFormal</string>
        <string>RewriteCasual</string>
    </array>
    <key>CustomActions</key>
    <array>
        <dict>
            <key>Id</key>
            <string>gdpr-check</string>
            <key>DisplayName</key>
            <string>GDPR Compliance Check</string>
            <key>SystemPrompt</key>
            <string>Analyse for PII and consent gaps.</string>
            <key>OutputSuffix</key>
            <string>_gdpr_check</string>
            <key>Icon</key>
            <string>lock.shield</string>
        </dict>
    </array>
</dict>

Meeting Transcription

On-device transcription powered by WhisperKit (distil-whisper on Apple Neural Engine). No audio sent to external servers.

Features

Dual capture: microphone (you) + system audio (remote participants)
Three modes: Live (3s), Fast (30s), Until Stop
Multilingual: auto-detects spoken language per chunk
AI Summarize & Translate: post-recording processing with Gemma 4

MDM Configuration

<key>TranscriptionSettings</key>
<dict>
    <key>Enabled</key>
    <false/>
    <key>WindowTitle</key>
    <string>Meeting Transcription</string>
</dict>

(set to false to disable transcription)

Building

Prerequisites

macOS 26.0+ (required by mlx-swift-lm)
Xcode 16+ / Swift 6.2+
Apple Silicon Mac with ≥ 3.5 GB free unified memory (for AI features)

Build Options

# One command:
make dev

# Swift Package Manager:
swift build -c release

# Application bundle:
./create-app-bundle.sh

Logging & Debug

# View logs in real-time:
./view-logs.sh

# Or manually:
log stream --predicate 'subsystem == "com.macbuddy.app"' --level debug

# Recent logs:
log show --predicate 'subsystem == "com.macbuddy.app"' --info --debug --last 1h

Logs show: application startup, configuration loading, actions loaded, menu updates, action execution, errors.