macfly-core 0.4.0

Core data model, config, DLP redaction, HTML fidelity analysis, and plan engine for MacFly
Documentation

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, .csv with --recursive)
  • Apple Mail — account and mailbox overview, direct signature lookup from Apple Mail (single source of truth), search, quote-trimmed reading with untrusted_external framing, 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-brief context 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 list and shortcuts 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, plus macfly report for Typst (.typ / renderreport), Markdown (.md), or PDF (.pdf) dossiers
  • Agent Skill Exporter & launchd Scheduler — macfly skill export generates a ready-to-use SKILL.md for Claude Code, Codex, Cursor, or Antigravity; macfly schedule manages native macOS LaunchAgents without 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 & runemark terminal UI — every write goes through plan create → inspect → approve → apply with canonical SHA-256 plan hashing, tamper detection, expiry TTL, interactive TTY confirmation, a local JSONL audit journal, and semantic terminal reports powered by runemark
  • Built-in stdio MCP server — exposes 19 read, context-pack & plan_create/plan_inspect tools; plan_approve and plan_apply are 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 over stdin (no argv leakage in ps 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

cargo install macfly
macfly doctor
macfly config init

Everyday commands (all support --format pretty, --format json, and --format agent, plus --color auto|always|never):

# Apple Notes (inspect, audit, export & multi-format import)
macfly notes overview
macfly notes audit
macfly notes list --limit 20
macfly notes search "Roadmap"
macfly notes read "<note-id>"
macfly notes export --output ./notes-backup --folder "10 · Work"
macfly notes import --input ./evernote-or-notion --folder "00 · Inbox" --recursive

# Apple Mail (inspect, signatures, read & Markdown export)
macfly mail overview
macfly mail signatures
macfly mail list --unread --limit 15
macfly mail read "<local-id>"
macfly mail export --output ./mail-archive --query "Invoice" --limit 20

# Apple Contacts (search, audit & Markdown export)
macfly contacts list --limit 50
macfly contacts search "Acme"
macfly contacts audit
macfly contacts export --output ./contacts-backup

# Apple Calendar & Reminders (events, tasks, export & multi-format import)
macfly calendar events --days 7
macfly calendar export --output ./upcoming-events.md --days 14
macfly reminders list --overdue
macfly reminders export --output ./open-tasks.md
macfly reminders import --input ./tasks.csv --list "Work"

# Apple Safari & Apple Shortcuts
macfly safari tabs
macfly safari export --output ./research-tabs.md
macfly safari to-note --folder "00 · Inbox" --title "Research Links"
macfly shortcuts list

# Multi-app context packs & Typst / PDF dossiers
macfly context daily-brief --format agent
macfly context person "Acme"
macfly context meeting-prep --query "Kickoff" --create-note --folder "00 · Inbox"
macfly context weekly-review
macfly report person "Acme" --output ./dossier-acme.typ

# Agent SKILL.md export & macOS launchd routines
macfly skill export --output ./.claude/skills/macfly
macfly schedule install --name morning-brief --task daily-brief --hour 7 --minute 30 --dry-run

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

macfly plan create --input plan.json
macfly plan inspect <plan-id>
macfly plan approve <plan-id>
macfly plan apply <plan-id>
macfly history

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:

{
  "mcpServers": {
    "macfly": {
      "command": "macfly",
      "args": ["mcp", "--profile", "default"]
    }
  }
}

See MCP & AI Agents and Security Model for details.

License

Dual-licensed under MIT or Apache-2.0, at your option.