macfly
Local, deterministic macOS automation CLI, migration toolkit, and stdio MCP server in pure Rust — with a read-side data firewall and cryptographic plan approval between AI agents and your personal apps.
Documentation: casoon.github.io/macfly
What it does
- Apple Notes — hierarchical folder overview, cleanup audit (empty folders, single-note folders, duplicate titles, oldest notes), search, cleaned reading with a fidelity guard (protects attachments, tables, checklists, and
applenotes://links), lossless folder/note moves, Markdown export, and multi-format import (.md,.txt,.html,.json,.jsonl,.csvwith--recursive) - Apple Mail — account and mailbox overview, direct signature lookup from Apple Mail (single source of truth), search, quote-trimmed reading with
untrusted_externalframing, safe draft creation (never sends unattended), and Markdown email archiving (mail export) - Apple Contacts — fast batched contact search, duplicate & empty-contact audit (
contacts audit), and Markdown contact card export (contacts export) - Apple Calendar & Reminders — upcoming events, open/overdue reminders, unified 4-app
daily-briefcontext pack, Calendar/Reminders Markdown export, and multi-format Reminders import (.md,.txt,.json,.jsonl,.csv) - Apple Safari — inspect open browser tabs (
safari tabs), export tabs to Markdown (safari export), or migrate open research tabs directly into an Apple Note via plan (safari to-note) - Apple Shortcuts — allowlist-gated bridge to
shortcuts listandshortcuts run(Focus modes, HomeKit scenes, modern App Intents) - Cross-app Context Packs & Typst/PDF Dossiers —
context daily-brief,context person "<Name/Email>"(360° dossier across 5 apps),context meeting-prep [--create-note],context weekly-review, plusmacfly reportfor Typst (.typ/renderreport), Markdown (.md), or PDF (.pdf) dossiers - Agent Skill Exporter &
launchdScheduler —macfly skill exportgenerates a ready-to-useSKILL.mdfor Claude Code, Codex, Cursor, or Antigravity;macfly schedulemanages native macOSLaunchAgentswithout a custom background daemon - Read-side Data Firewall (DLP) — profile-based allowlists/denylists (
deny_folders,deny_mailboxes) plus automatic linear-time regex redaction of private keys, API keys, IBANs, credit cards, and 6-digit OTP codes before output reaches any LLM - Transactional change plans &
runemarkterminal UI — every write goes throughplan create → inspect → approve → applywith canonical SHA-256 plan hashing, tamper detection, expiry TTL, interactive TTY confirmation, a local JSONL audit journal, and semantic terminal reports powered byrunemark - Built-in
stdioMCP server — exposes 19 read, context-pack &plan_create/plan_inspecttools;plan_approveandplan_applyare intentionally excluded from MCP so agents can propose changes but never self-approve them
Why Rust + AppleScript/JXA
- Deterministic core: Policy evaluation, DLP redaction, HTML/email normalization, multi-format import parsers, fidelity checks, plan hashing, and audit journaling live in pure, memory-safe Rust and run offline in milliseconds via
cargo test. - Zero SDK / Xcode drift: No Swift toolchain, no Xcode project, no Node.js runtime, and no fragile private SQLite assumptions in the default path.
- Safe, batched JXA edge: All scripts are statically embedded (
include_str!), receive parameters strictly as JSON overstdin(noargvleakage inps aux), use batched property fetches, and enforce hard timeouts with typed TCC error hints.
Requirements
- macOS (Apple Silicon or Intel)
- Rust toolchain (
cargo, Edition 2024) - macOS Automation (TCC) permission for the apps you use (prompted automatically on first run; verified via
macfly doctor)
Installation & quick start
Everyday commands (all support --format pretty, --format json, and --format agent, plus --color auto|always|never):
# Apple Notes (inspect, audit, export & multi-format import)
# Apple Mail (inspect, signatures, read & Markdown export)
# Apple Contacts (search, audit & Markdown export)
# Apple Calendar & Reminders (events, tasks, export & multi-format import)
# Apple Safari & Apple Shortcuts
# Multi-app context packs & Typst / PDF dossiers
# Agent SKILL.md export & macOS launchd routines
Configuration
MacFly uses a single configuration file at ~/.config/macfly/config.json (override with --config or $MACFLY_CONFIG). Email accounts stay in Apple Mail, and signatures default to {"source": "apple-mail"} so your email footer has a single source of truth.
See Getting Started and Migrations & Backups for the full configuration schema and migration workflows.
Plans & audit journal
Plans are stored at ~/.local/share/macfly/plans/ (0600) and executions are logged to ~/.local/share/macfly/journal.jsonl (0600). See Plans & Workflows for all supported operations.
MCP server
Point any MCP-compatible client (Claude Desktop, Cursor, Antigravity, or local LLM runners) to the same binary:
See MCP & AI Agents and Security Model for details.
License
Dual-licensed under MIT or Apache-2.0, at your option.