Agent! is the result of 27 years of Mac automation experience — from FaceSpan and AppleScript on macOS 9 through AppleScript Studio, AppleScript-ObjC, and now Swift. It connects LLMs to Apple Events, ScriptingBridge, Accessibility APIs, and XPC services for native macOS control.
Now with Apple Intelligence supporting 10 LLM providers.
Apple Intelligence serves as a communication mediator between the LLM and the user, not as an LLM provider. It observes conversations and adds helpful context using on-device intelligence:
Annotations are tagged with [AI] prefixes to distinguish them from LLM responses.
Enable Apple Intelligence Mediator in Settings to enhance communication clarity. Requires Apple Intelligence-capable Mac running macOS 26+.
- 50+ App Automation via ScriptingBridge (Mail, Messages, Music, Safari, Xcode, etc.)
- 86 Tools for file ops, git, web, accessibility, Xcode, MCP integration
- AgentScripts — Swift Package-based automation scripts
- Apple Messages Monitor — Remote control via iMessage
- MCP Support — Model Context Protocol for extended functionality
- Getting Started
- Security Hardening
- Messages Monitor
- MCP Servers
- Architecture
- Available Tools
- AgentScripts
- Agent! vs. OpenClaw on Mac
- License
- macOS 26+ (Tahoe)
- Xcode Command Line Tools (Agent will prompt to install if missing)
- Apple Silicon recommended for local LLMs (minimum 32GB RAM, recommended 64-128GB)
- An API key for your preferred provider
- Open
Agent.xcodeprojin Xcode - Build and run the Agent! target (⌘R)
- If prompted, install Xcode Command Line Tools via the system check overlay
Click the Register button in the toolbar to install the background services:
This registers two background services using Apple's SMAppService framework:
- User Agent (
Agent.app.toddbruss.user) — Runs commands as your user account - Privileged Daemon (
Agent.app.toddbruss.helper) — Runs commands as root when needed
After clicking Register, macOS will prompt you to approve the background services:
- System Settings → General → Login Items
- Allow both Agent and AgentHelper (you may see two prompts)
The privileged daemon requires explicit approval because it runs with root privileges. Agent follows Apple's recommended XPC + SMAppService pattern for secure privilege separation.
Click the gear icon (⚙️) to open Settings and configure one of the 10 supported providers:
Supported Providers (Click to expand)
| Provider | Models | Notes |
|---|---|---|
| Claude | Sonnet 4, Opus 4, Haiku 3.5 | Recommended for complex tasks |
| OpenAI | GPT-4o, GPT-4 Turbo, GPT-3.5 | General-purpose option |
| DeepSeek | DeepSeek V2, DeepSeek Coder | Cost-effective |
| Hugging Face | Any model ID | Direct model access |
| Ollama Cloud | Various | Ollama Pro API |
| Local Ollama | Local models | Requires 32GB+ RAM |
| vLLM | OpenAI-compatible | Self-hosted |
| LM Studio | OpenAI/Anthropic | Local hosting |
Note: Local models require significant RAM (minimum 32GB, recommended 64-128GB). For Mac minis or devices with limited RAM, cloud-based LLMs are strongly recommended.
Click the folder icon in the toolbar to select a project folder or file. This sets a default working directory for file operations.
- Click Connect to test the XPC services
- Type a task in natural language
- Press Run (or ⌘Enter)
Agent will autonomously execute your task using the appropriate tools.
Agent! implements a comprehensive security model based on Apple's recommended patterns:
Privilege Model Details (Click to expand)
| Service | Identifier | Runs As | Purpose |
|---|---|---|---|
| User Agent | Agent.app.toddbruss.user |
User account | File editing, git, builds, scripts |
| Privileged Daemon | Agent.app.toddbruss.helper |
Root (via LaunchDaemon) | System packages, /Library, launchd, disk operations |
Full Entitlements & Security Details (Click to expand)
| Component | TCC Grants |
|---|---|
run_agent_script, applescript_tool, TCC shell commands |
ALL (Accessibility, Screen Recording, Automation) |
execute_user_command (LaunchAgent) |
None |
execute_command (root) |
Separate context |
Rule: Use run_agent_script or applescript_tool for Accessibility/Automation tasks, not shell commands.
| Entitlement | Purpose |
|---|---|
automation.apple-events |
AppleScript and ScriptingBridge automation |
cs.allow-unsigned-executable-memory |
Required for dlopen'd AgentScript dylibs |
cs.disable-library-validation |
Load user-compiled script dylibs at runtime |
assets.music.read-write |
Music library access via MusicBridge |
device.audio-input |
Microphone access for audio scripts |
device.bluetooth |
Bluetooth device interaction |
device.camera |
Camera capture (CapturePhoto script) |
device.usb |
USB device access |
files.downloads.read-write |
Read/write Downloads folder |
files.user-selected.read-write |
Read/write user-selected files |
network.client |
Outbound connections (API calls, web search) |
network.server |
Inbound connections (MCP HTTP/SSE transport) |
personal-information.addressbook |
Contacts access via ContactsBridge |
personal-information.calendars |
Calendar access via CalendarBridge |
personal-information.location |
Location services |
personal-information.photos-library |
Photos access via PhotosBridge |
keychain-access-groups |
Secure API key storage |
See SECURITY.md for complete XPC architecture details.
Agent! includes a built-in Apple Messages monitor that lets you control your Mac remotely via iMessage. Send a text message starting with Agent! from any approved contact and Agent will execute it as a task — then reply with the result.
Agent! now features a dedicated Messages tab (green) specifically for iMessage Agent! commands. This tab:
- Uses the main LLM for processing (not a separate model)
- Provides a focused interface for remote command execution
- Shows real-time message monitoring status
- Integrates seamlessly with the Messages Monitor popover
- Toggle Messages ON in the toolbar (green switch next to "Messages")
- Click the speech bubble icon to open the Messages Monitor popover
- Send a message starting with
Agent!from another device or contact (e.g.,Agent! Next Song) - The sender's handle (phone number or email) appears in the recipients list
- Toggle the recipient ON to approve them
- Future
Agent!messages from approved recipients will automatically run as tasks - When the task completes, Agent sends the result (up to 256 characters) back via iMessage
Agent! <your prompt here>
Examples:
Agent! What song is playing?Agent! Next SongAgent! Check my emailAgent! Build and run my Xcode project
The filter picker controls which messages are monitored:
Filter Options (Click to expand)
| Filter | Description |
|---|---|
| From Others | Only incoming messages from other people (default) |
| From Me | Only your own sent messages (useful for self-testing between your devices) |
| Both | All messages regardless of sender |
Every recipient must be explicitly approved before their Agent! commands trigger tasks:
- Recipients are auto-discovered when they send an
Agent!message - Unapproved messages are logged with a "not approved" note but not acted on
- Use All / None buttons to bulk-toggle recipients within the current filter
- Use Clear to remove all discovered recipients and start fresh
Agent reads the macOS Messages database (~/Library/Messages/chat.db) directly using the SQLite3 C API. It polls every 5 seconds for new messages. The attributedBody blob is decoded using the Objective-C runtime for messages where the text column is NULL (common with iMessage).
No external dependencies. No network requests. Everything runs locally on your Mac.
Agent! supports MCP (Model Context Protocol) servers for extended functionality.
MCP Server List (Click to expand)
| Server | Description | Link |
|---|---|---|
| internet-names-mcp | Domain and social handle availability | https://github.com/drewster99/InternetNamesMCP |
| xcode-mcp-server | Xcode project building, running, screenshots | https://github.com/drewster99/xcode-mcp-server |
| appstore-mcp-server | App Store search, rankings, keywords | https://github.com/drewster99/appstore-mcp-server |
| XCF | External MCP server | https://xcf.ai |
- Click the server icon in toolbar → + to add
- Configure: Name, Command, Arguments, Environment, Transport (stdio/HTTP/SSE)
- Enable Auto-start to connect on launch
- Enable/disable individual tools per server as needed
Agent.app (SwiftUI)
|-- AgentViewModel Task loop, screenshots, clipboard, project folder
|-- ClaudeService Anthropic Messages API (streaming)
|-- OllamaService Ollama native API
|-- ChatHistoryStore SwiftData task memory
|-- CodingService File operations
|-- MCPService MCP client for external tools
|-- ScriptService Swift Package for agent scripts
|-- XcodeService Xcode ScriptingBridge
|-- AppleEventService Dynamic Apple Events
|-- AccessibilityService AXUIElement API
|-- Messages Monitor iMessage remote control
Execution contexts:
|-- [In-Process] TCC commands (ALL grants)
|-- UserService XPC LaunchAgent (user)
|-- HelperService XPC LaunchDaemon (root)
Tool Priority Table (Click to expand)
| Priority | Tool | Best For |
|---|---|---|
| 1 | run_agent_script |
Complex automation (full TCC) |
| 2 | applescript_tool |
Reading app data and AppleScript automation |
| 3 | execute_shell_command (TCC) |
Quick one-off AppleScript commands |
| 4 | Accessibility tools | UI inspection and interaction |
Coding Tools Priority (Click to expand)
| Priority | Tool Type | Examples |
|---|---|---|
| 1 | Native tools | read_file, write_file, edit_file, git, xcode |
| 2 | MCP server tools | mcp_xcf_* |
| 3 | Shell commands | Last resort only |
For Xcode project builds, the AI follows this priority:
Xcode Build Priority (Click to expand)
| Priority | Tool | When to Use |
|---|---|---|
| 1 | xcode_build |
Native ScriptingBridge tool — ALWAYS PREFERRED |
| 2 | XCF MCP server (mcp_xcf_*) |
Backup if native tools unavailable |
| 3 | xcode-mcp-server (mcp_xcode-mcp-server_*) |
Third choice if XCF unavailable |
| 4 | xcodebuild via shell |
LAST RESORT only if no other options |
Agent! manages system prompts with automatic version tracking:
Version Headers Table (Click to expand)
| Header | Behavior |
|---|---|
// Agent! v{version} |
Default prompt — auto-updates when app version changes |
// Agent! custom v{version} |
User-edited prompt — auto-updates on version change (preserves custom edits) |
// Agent! READ ONLY v{version} |
Locked prompt — never auto-overwritten, even on version changes |
To lock a prompt: Add READ ONLY or // READ ONLY at the top of your custom prompt. This prevents automatic updates even when a new Agent! version is released.
Prompts are stored in ~/Documents/AgentScript/system/ as {provider}.txt files.
Agent! provides 86 tools across multiple categories for autonomous task execution.
| Category | Tools | Description |
|---|---|---|
| Core | 28 | File ops, git, web, text generation |
| Agent Scripts | 7 | Create, run, manage Swift scripts |
| AppleScript/JS | 11 | AppleScript and JXA automation |
| Accessibility | 12 | UI automation via AXUIElement API |
| Xcode | 7 | Build, run, manage Xcode projects |
| MCP — XCF | 21 | Xcode project automation via MCP |
| Tool | Description |
|---|---|
about_self |
Describe Agent's capabilities, features, and usage |
read_file |
Read file contents with line numbers |
write_file |
Create or overwrite a file |
edit_file |
Replace exact text in a file |
list_files |
Find files matching a glob pattern |
search_files |
Search file contents by regex pattern |
read_dir |
List directory contents |
create_diff |
Compare two text strings and return a pretty D1F diff with emoji markers |
apply_diff |
Apply a D1F ASCII diff to a file for precise multi-line edits |
diff_and_apply |
Edit a file by line range in one step |
undo_edit |
Undo a previous diff edit |
file_manager |
Unified file operations (read, write, edit, list, search, read_dir, if_to_switch, extract_function) |
git |
Git operations (status, diff, log, commit, diff_patch, branch) |
execute_agent_command |
Execute shell command as current user (no TCC) |
execute_daemon_command |
Execute shell command as ROOT via LaunchDaemon (no TCC) |
run_shell_script |
Run shell command or script (alias for execute_agent_command) |
batch_commands |
Run multiple shell commands sequentially in one call |
batch_tools |
Run multiple tool calls sequentially in one batch |
plan_mode |
Manage step-by-step plans (create, update, read, list, delete) |
task_complete |
Signal that a task has been completed |
write_text |
Generate well-structured prose on any topic |
transform_text |
Convert text into different formats (lists, outlines, summaries, tables) |
fix_text |
Correct spelling and grammar errors |
send_message |
Send message via iMessage, email, or other channels |
web |
Web browser automation (open, scan, click, type, execute_js, etc.) |
web_search |
Search the web for current information |
lookup_sdef |
Look up an app's AppleScript scripting dictionary |
list_tools |
List all enabled tools (built-in and MCP) |
| Tool | Description |
|---|---|
agent (list) |
List all Swift automation scripts |
agent (read) |
Read source code of a script |
agent (create) |
Create a new Swift script |
agent (update) |
Update an existing script |
agent (run) |
Compile and run a Swift dylib script |
agent (delete) |
Delete a script |
agent (combine) |
Merge two scripts together |
| Tool | Description |
|---|---|
applescript_tool (execute) |
Run inline AppleScript source with full TCC |
applescript_tool (list) |
List saved AppleScripts |
applescript_tool (run) |
Run saved AppleScript by name |
applescript_tool (save) |
Save AppleScript for reuse |
applescript_tool (delete) |
Delete saved AppleScript |
applescript_tool (lookup_sdef) |
Read app's scripting dictionary |
javascript_tool (execute) |
Run inline JXA source |
javascript_tool (list) |
List saved JXA scripts |
javascript_tool (run) |
Run saved JXA script |
javascript_tool (save) |
Save JXA for reuse |
javascript_tool (delete) |
Delete saved JXA |
| Tool | Description |
|---|---|
accessibility (list_windows) |
List all visible windows with positions and owner apps |
accessibility (get_properties) |
Get all properties of an accessibility element |
accessibility (perform_action) |
Perform an accessibility action (AXPress, AXConfirm, etc.) |
accessibility (type_text) |
Simulate keyboard typing |
accessibility (click) |
Simulate mouse clicks at coordinates |
accessibility (press_key) |
Simulate key presses with modifiers |
accessibility (screenshot) |
Capture screenshot of region or window |
accessibility (set_properties) |
Set accessibility property values |
accessibility (find_element) |
Find element by role/title/value with timeout |
accessibility (get_children) |
Get children of an accessibility element |
accessibility (check_permission) |
Check if Accessibility access is granted |
accessibility (request_permission) |
Request Accessibility permission |
| Tool | Description |
|---|---|
xcode (build) |
Build an Xcode project/workspace (auto-detects) |
xcode (run) |
Build and run an Xcode project |
xcode (list_projects) |
List all open Xcode projects |
xcode (select_project) |
Select a project by number |
xcode (add_file) |
Add a file to pbxproj |
xcode (remove_file) |
Remove a file from pbxproj |
xcode (grant_permission) |
Grant macOS Automation permission for Xcode |
| Tool | Description |
|---|---|
mcp_xcf_xcf |
Execute an xcf action or command |
mcp_xcf_list |
List all available tools on this server |
mcp_xcf_xcf_help |
Help for xcf actions only |
mcp_xcf_help |
Regular help with common examples |
mcp_xcf_snippet |
Extract code snippets from files |
mcp_xcf_analyzer |
Analyze Swift code for potential issues |
mcp_xcf_read_dir |
List contents of a directory |
mcp_xcf_read_file |
Read content from a file |
mcp_xcf_cd_dir |
Change current directory |
mcp_xcf_use_xcf |
Activate XCF mode |
mcp_xcf_tools |
Show detailed reference for all tools |
mcp_xcf_show_help |
Display help information |
mcp_xcf_grant_permission |
Grant Xcode automation permissions |
mcp_xcf_run_project |
Run the current Xcode project |
mcp_xcf_build_project |
Build the current Xcode project |
mcp_xcf_show_current_project |
Show information about the current project |
mcp_xcf_show_env |
Display all environment variables |
mcp_xcf_show_folder |
Display the current working folder |
mcp_xcf_list_projects |
List all open Xcode projects |
mcp_xcf_select_project |
Select an Xcode project by number |
mcp_xcf_analyze_swift_code |
Analyze Swift code for potential issues |
Agent! includes a built-in Swift scripting system. Scripts live in ~/Documents/Agent/agents/ as a Swift Package:
~/Documents/Agent/agents/
├── Package.swift
└── Sources/
├── Scripts/ ← one .swift file per script
│ ├── CheckMail.swift
│ ├── Hello.swift
│ └── ...
└── XCFScriptingBridges/ ← one .swift file per app bridge
├── ScriptingBridgeCommon.swift
├── MailBridge.swift
└── ...
29 scripts come pre-compiled in Agent.app/Contents/Resources/:
| Script | Description |
|---|---|
AccessibilityRecorder |
Record accessibility actions |
AXDemo |
Accessibility API demonstration |
CapturePhoto |
Capture photo from camera |
CheckMail |
Check for new email messages |
CreateDMG |
Create a DMG disk image |
EmailAccounts |
List email accounts |
ExtractAlbumArt |
Extract album artwork from Music |
GenerateBridge |
Generate ScriptingBridge for any app |
Hello |
Simple hello world script |
ListHomeContents |
List home directory contents |
ListNotes |
List Apple Notes |
ListReminders |
List Reminders |
MusicScriptingExamples |
Music app scripting examples |
NowPlaying |
Get currently playing track |
NowPlayingHTML |
Now playing info as HTML |
OrganizeEmails |
Organize email into folders |
PlayPlaylist |
Play a Music playlist |
PlayRandomFromCurrent |
Play random track from current playlist |
QuitApps |
Quit running applications |
RunningApps |
List running applications |
SDEFtoJSON |
Convert SDEF to JSON |
SafariSearch |
Search in Safari |
SaveImageFromClipboard |
Save image from clipboard |
Selenium |
WebDriver automation |
SendGroupMessage |
Send group iMessage |
SendMessage |
Send iMessage |
SystemInfo |
Get system information |
TodayEvents |
Get today's calendar events |
WebForm |
Web form automation |
WebNavigate |
Web navigation |
WebScrape |
Web scraping |
The AI can create, read, update, delete, compile, and run these scripts autonomously:
list_agent_scripts— list all scriptscreate_agent_script— write a new scriptread_agent_script— read source codeupdate_agent_script— modify an existing scriptrun_agent_script— compile withswift build --product <name>and executedelete_agent_script— remove a script
Agent includes the D1F (Diff 1 Format) package integrated as a local dependency for pretty diff output:
- create_diff — Compare two text strings and get a visual diff with emoji markers:
- 📎 Retained lines (unchanged)
- ❌ Deleted lines (removed)
- ✅ Inserted lines (added)
- apply_diff — Apply D1F ASCII diffs directly to files
- edit_file — Shows D1F diff preview when replacing text
The D1F package lives in the project folder as a local Swift package dependency, enabling clear visual diffs for file edits without external dependencies.
Agent includes an applescript_tool tool that lets the AI query any scriptable Mac app instantly — with zero compilation. It uses Objective-C dynamic dispatch to walk an app's Apple Event object graph at runtime.
| Operation | Description | Example |
|---|---|---|
get |
Access a property | {action: "get", key: "currentTrack"} |
iterate |
Read properties from array items | {action: "iterate", properties: ["name", "artist"], limit: 10} |
index |
Pick one item from array | {action: "index", index: 0} |
call |
Invoke a method | {action: "call", method: "playpause"} |
filter |
NSPredicate filter | {action: "filter", predicate: "name contains 'inbox'"} |
Agent ships with pre-generated Swift protocol definitions for 50 macOS applications:
| Category | Applications |
|---|---|
| Apple Apps | Automator, Calendar, Contacts, Finder, Mail, Messages, Music, Notes, Numbers, Pages, Photos, Preview, QuickTime Player, Reminders, Safari, Script Editor, Shortcuts, System Events, Terminal, TextEdit, TV |
| Developer Tools | Xcode, Developer Tools, Instruments, Simulator |
| Creative Apps | Keynote, Logic Pro, Final Cut Pro, Adobe Illustrator, Pixelmator Pro |
| Browsers | Google Chrome, Firefox, Microsoft Edge |
| System | System Settings, System Information, Screen Sharing, Bluetooth File Exchange, Console, Database Events, Folder Actions Setup, Voice Over, UTM |
| Legacy | Pages Creator Studio, Numbers Creator Studio, Logic Pro Creator Studio, Final Cut Pro Creator Studio |
Each bridge is its own Swift module. Scripts import only what they need (e.g. import MailBridge), keeping builds fast and isolated.
Agent streams responses token-by-token in real time. The activity log renders markdown inline: bold, italic, inline code, and fenced code blocks with syntax highlighting.
Attach screenshots or paste images directly into Agent. Images are encoded as base64 PNG and sent as vision content blocks. The AI can see what's on your screen and act on it.
Agent persists task history using SwiftData. Recent task messages and older task summaries are injected into the system prompt, giving the AI memory across sessions.
| Agent! | OpenClaw | |
|---|---|---|
| Focus | macOS-native depth | Cross-platform breadth |
| Runtime | Native Swift binary | Node.js server |
| UI | SwiftUI app | Web chat / Telegram / CLI |
| Privilege model | XPC + Launch Daemon (Apple's official pattern) | Shell commands |
| macOS integration | Apple Events, ScriptingBridge, AppleScript, SMAppService, Accessibility | Generic shell access |
| Xcode automation | Built-in: build, run, grant permissions | N/A |
| Accessibility | Full AXUIElement API integration | Limited |
| Scripting language | Swift Package-based AgentScripts | Python/JS scripts |
| MCP support | Yes (stdio, HTTP/SSE) | Yes |
| Messaging | Native Apple Messages (iMessage/SMS) with per-recipient approval | WhatsApp, Telegram, Slack, Discord, iMessage, and more |
| Message reply | Auto-replies task results via iMessage to approved senders | Platform-specific replies |
| App size | ~13 MB | ~90.5 MB unpacked (npm) |
| Installation | Run the .app, install Xcode Command Line Tools (xcode-select --install) |
openclaw onboard wizard |
| Dependencies | Xcode Command Line Tools | Node.js + npm ecosystem |
| Apple Silicon | Native ARM64 | Interpreted (Node.js) |
Both tools have their strengths. If you want a personal assistant across every messaging platform, OpenClaw is excellent. If you want an AI agent that reads Apple Messages natively, drives Xcode, compiles Swift, controls Mac apps through ScriptingBridge, and escalates to root through a proper Launch Daemon — Agent is built for that.
MIT