MacFlyv0.5.0

Hands-on cookbook · configs, prompts & castwright demos

Use Cases

Concrete workflows you can copy and run directly on macOS — including the exact input files,config.json policies, MCP client configs, ready-to-use AI prompts, and animated castwright terminal sessions.

Tip

How every workflow stays safe: Read commands and context packs never modify your apps. Every write (moving notes, importing files, creating mail drafts) produces a SHA-256 hash-locked plan that you explicitly approve in your own terminal.

Use Case 1 · Hygiene & Reorganization

Clean up a sprawling Apple Notes library safely

Run macfly notes audit to surface empty folders, single-note folders, and duplicate titles. Either write a small JSON plan file yourself — or let an AI agent propose it over MCP — then inspect, approve with the 6-character SHA-256 code, and apply. Notes containing attachments, tables, or checklists are moved losslessly via the built-in Note Fidelity Guard.

What you provide
~/.config/macfly/config.json (created once viamacfly config init) + a plan JSON file (written manually or generated by an AI agent via MCP plan_create).
What MacFly produces
A hash-locked plan in ~/.local/share/macfly/plans/, lossless folder moves in Apple Notes after TTY approval, and an audit entry in journal.jsonl.
macfly notes audit → plan create → approve → apply
$ macfly notes audit
⚠ Notes Hygiene Audit (profile: default)

  Total notes: 825   Folders: 105   Empty: 3   Single-note: 24

  Single-note folders (consolidation candidates):
    ! 'Q1 Taxes' (1 note) -> move to '10 · Work / Finance'
    ! 'Rust Ideas' (1 note) -> move to '20 · Engineering'
    …and 22 more single-note folders

$ macfly plan create --input reorganize-notes.json
! Plan Created & Hash-Locked
  Plan ID: plan-1795370000-a1b2c3d4
  Operations: 27   SHA-256: a1b2c3d4e5f60718   Approval code: A1B2C3
  Fidelity Guard: ✔ 19 notes with attachments/tables moved losslessly

$ macfly plan approve plan-1795370000-a1b2c3d4 --confirm-code A1B2C3
✔ Plan Approved (interactive TTY verified · SHA-256 intact)

$ macfly plan apply plan-1795370000-a1b2c3d4
✔ Plan Applied
  Succeeded: 27   Failed: 0   Journal: ~/.local/share/macfly/journal.jsonl
reorganize-notes.json
{
  "schema_version": "1.0",
  "summary": "Consolidate single-note folders into 00–90 taxonomy",
  "operations": [
    {
      "action": "notes_move",
      "note_id": "x-coredata://.../ICNote/p1042",
      "destination_folder": "10 · Work/Finance",
      "expected_revision": "sha256:9f84b2c1..."
    },
    {
      "action": "notes_move",
      "note_id": "x-coredata://.../ICNote/p1088",
      "destination_folder": "20 · Engineering",
      "expected_revision": "sha256:4a71e0d9..."
    },
    {
      "action": "notes_delete_empty_folder",
      "folder_id": "x-coredata://.../ICFolder/p45",
      "folder_name": "Q1 Taxes"
    }
  ]
}
~/.config/macfly/config.json
{
  "schema_version": "1.0",
  "default_profile": "default",
  "script_timeout_secs": 45,
  "profiles": {
    "default": {
      "notes": {
        "allow_accounts": ["iCloud"],
        "allow_folders": [],
        "deny_folders": ["Passwords", "Recently Deleted", "Health"],
        "skip_password_protected": true
      },
      "mail": {
        "allow_accounts": ["Exchange", "iCloud"],
        "deny_mailboxes": ["Trash", "Junk", "Banking"],
        "signature": {
          "source": "apple-mail",
          "name": null
        }
      },
      "shortcuts": {
        "allow": ["Work Focus On", "Morning Lights"]
      },
      "dlp": {
        "enabled": true,
        "redact": ["private_key", "api_key", "iban", "credit_card", "otp_code"],
        "max_body_chars": 12000
      }
    }
  }
}

Use Case 2 · Two-Way Migrations

Migrate between Obsidian, Notion, CSV and Apple Notes & Reminders

Point macfly notes import at any folder of .md,.txt, .html, .json, .jsonl, or.csv files (with --recursive) — or feed a Todoist/spreadsheet CSV straight into macfly reminders import. Going the other direction,notes export, mail export, contacts export, andsafari export write clean Markdown with YAML frontmatter for Git backups.

What you provide
Any existing export folder (Obsidian vault, Notion HTML/Markdown export, Evernote files, or a standard RFC-4180 CSV). No custom MacFly wrapper format required.
What MacFly produces
For imports: a reviewable SHA-256 import plan before anything is written. For exports: clean UTF-8 Markdown files with YAML frontmatter (id,folder, revision).
macfly notes import · reminders import · notes export
$ macfly notes import --input ./obsidian-vault --folder "00 · Inbox" --recursive
! Multi-Format Notes Import Plan Created
  Parsed files: 42 (.md: 34, .html: 4, .json: 2, .csv: 2)
  Target folder: 00 · Inbox   Plan ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
  Approval code: 8f4e2a

$ macfly reminders import --input ./todoist-tasks.csv --list "Work"
! Reminders Import Plan Created
  Tasks parsed: 18 (RFC-4180 CSV with due_date, priority, notes)
  Target list: Work         Approval code: 3d9c1b

$ macfly notes export --output ./git-knowledge-base --folder "10 · Work"
✔ Notes Export Completed
  Exported: 64 Markdown files with YAML frontmatter (id, folder, revision)
  Output: ./git-knowledge-base
obsidian-vault/q4-checklist.md
---
title: Q4 Architecture Checklist
folder: 20 · Engineering
tags: [rust, macos]
---

# Q4 Architecture Checklist

- Migrate remaining CSV task exports into Apple Reminders
- Verify SHA-256 plan approval flow on Apple Silicon
todoist-tasks.csv
title,due_date,priority,notes
Send Q4 SLA review to Acme,2026-11-28,high,Attach updated PDF dossier
Renew Apple Developer certificate,2026-12-05,medium,Check notarization key
Archive 2025 project notes,2026-12-15,low,Export to Git backup first

Use Case 3 · 360° Cross-App Context & PDF Reports

Generate a 360° client dossier and compile a PDF directly

You do not need to supply any .typ or JSON input file.macfly context person "Acme" reads Contacts, Apple Notes, Apple Mail (all accounts), Calendar, and Reminders live on your Mac and correlates everything in one DLP-filtered dossier. Pass --output ./dossier-acme.pdf tomacfly report and MacFly generates the Typst source automatically and compiles the final PDF for you (requires typst inPATH, e.g. brew install typst).

What you provide
Only a search term (person name, company, or email) — no input filerequired.
Why .pdf, .typ, and .md are all supported
Use --output dossier.pdf for a ready-to-share PDF in one step,--output dossier.typ if you want to tweak the Typst layout or pass it torenderreport, or --output dossier.md for plain Markdown.
macfly context person "Acme" → macfly report person --output .pdf
$ macfly context person "Acme"
✔ 360° Person & Project Dossier: 'Acme'

  Total hits: 14   Contacts: 2   Notes: 5   Mail: 4   Calendar: 2   Tasks: 1

  Matching Contacts (2):
    ℹ Alex Rivera (Acme GmbH) · alex@acme.example · +49 30 5550192
  Matching Apple Notes (5):
    ℹ [10 · Work] Acme Architecture & SLA Review (2026-11-18)
  Recent Emails (4):
    ℹ [Exchange] Q4 Contract & Billing IBAN [REDACTED:IBAN] (2026-11-20)

$ macfly report person "Acme" --output ./dossier-acme.pdf
✔ PDF Dossier Compiled (via Typst)
  PDF: ./dossier-acme.pdf   Source: ./dossier-acme.typ
  Tip: Use --output .typ for renderreport or --output .md for Markdown
Direct PDF, Typst, or Markdown output
# 1. Direct PDF output (requires 'typst' in PATH — no manual .typ file needed!)
macfly report person "Acme" --output ./dossier-acme.pdf

# 2. Editable Typst source (for custom styling or casoon/renderreport)
macfly report person "Acme" --output ./dossier-acme.typ
typst compile ./dossier-acme.typ ./dossier-acme.pdf

# 3. Pure Markdown (for Git, Obsidian, or Notion)
macfly report person "Acme" --output ./dossier-acme.md

# Same three output formats work for daily-brief and weekly-review:
macfly report daily-brief --output ./brief-today.pdf
macfly report weekly-review --output ./weekly-review.pdf
dossier-acme.typ (auto-generated)
// Auto-generated by: macfly report person "Acme" --output ./dossier-acme.pdf
#set page(paper: "a4", margin: 22mm)
#set text(font: "Inter", size: 10pt)

= 360° Dossier: Acme
#text(fill: luma(100))[Generated locally by MacFly · DLP firewall active]

== Matching Contacts (2)
- *Alex Rivera* (Acme GmbH) — alex@acme.example · +49 30 5550192

== Apple Notes (5)
- *[10 · Work]* Acme Architecture & SLA Review (2026-11-18)

== Recent Emails (4)
- *[Exchange]* Q4 Contract & Billing IBAN [REDACTED:IBAN] (2026-11-20)

== Upcoming Calendar & Open Tasks
- Kickoff Q4 Review (Tomorrow, 10:00–11:00)
- [ ] Send Q4 SLA review to Acme (due 2026-11-28)

Use Case 4 · Privacy-First Mail Triage & DLP Firewall

Triage Apple Mail with automatic secret redaction and safe drafts

MacFly reads across every account already signed into Apple Mail (Exchange, iCloud, Gmail, custom IMAP) without cloud OAuth tokens. Before any text reaches a model, the Rust DLP engine redacts IBANs, API keys, private keys, credit cards, and OTP codes and tags incoming mail as untrusted_external. Signatures are fetched straight from Apple Mail (Single Point of Truth), and replies are created as drafts only.

What you provide
Your DLP & denylist rules in ~/.config/macfly/config.json (active by default after macfly config init) and a mail.create_draftplan (created manually or by your AI agent).
What MacFly produces
Redacted search/read results and — only after your TTY approval — a ready-to-review draft in Apple Mail with your native signature attached.
macfly mail search (DLP) → signatures → safe draft plan
$ macfly mail search --query "Invoice" --limit 2
✔ Mail Search: 'Invoice' (2 matches · DLP active · untrusted_external)

  1. Invoice #2026-114 · Wire Transfer Details
     From: billing@acme.example   Account: Exchange
     Body: Wire EUR 4,200 to [REDACTED:IBAN] · key [REDACTED:API_KEY]

$ macfly mail signatures
Signatures from Apple Mail (Single Point of Truth):
  • 'Corporate Standard' (native Apple Mail signature · 0.24s)

$ macfly plan create --input draft-reply.json
! Plan Created & Hash-Locked (mail_create_draft · drafts only)
  Signature: Corporate Standard (from Apple Mail)   Approval code: 9C4A1E
draft-reply.json (mail_create_draft plan)
{
  "schema_version": "1.0",
  "summary": "Create reply draft for Acme invoice inquiry (never auto-sends)",
  "operations": [
    {
      "action": "mail_create_draft",
      "account": "Exchange",
      "to": ["billing@acme.example"],
      "cc": [],
      "subject": "Re: Invoice #2026-114 · Wire Transfer Details",
      "signature_name": "Corporate Standard",
      "body": "Hi Alex,\n\nthanks for sending invoice #2026-114. Our finance team has received it and scheduled payment for Friday.\n\nBest regards,"
    }
  ]
}

Use Case 5 · MCP Setup, Ready-to-Use AI Prompts & launchd

Connect Claude, Cursor, Codex, or Ollama — plus local schedules

MacFly ships a built-in stdio MCP server (macfly mcp) exposing 19 read, context-pack, and plan_create tools — while intentionally omittingplan_approve and plan_apply so no agent can self-approve writes. Export a ready-to-use SKILL.md with macfly skill export, or schedule recurring local briefings with native macOS launchd agents.

How MCP is installed
Install the binary once via the direct shell installer (curl -fsSL https://raw.githubusercontent.com/casoon/macfly/main/install.sh | bash) or cargo install macfly, then add the 4-line mcpServersblock below to Claude Code, Claude Desktop, or Cursor.
How AI workflows run in practice
Ask your agent using one of the prompts below → the agent reads via MCP (DLP-filtered) and proposes a plan_id → you run macfly plan inspect,approve, and apply in your terminal.
macfly context daily-brief · schedule install · skill export
$ macfly context daily-brief
✔ Executive Daily Brief
  Calendar (48h): 4   Open Tasks: 7   Unread Mail: 3   Recent Notes: 12

$ macfly schedule install --name morning-brief --task daily-brief --hour 7 --minute 30
✔ LaunchAgent Installed & Loaded
  Label: com.casoon.macfly.morning-brief   Schedule: 07:30 daily
  Plist: ~/Library/LaunchAgents/com.casoon.macfly.morning-brief.plist

$ macfly skill export --output ./.claude/skills/macfly
✔ Agent Skill Exported
  Path: ./.claude/skills/macfly/SKILL.md
Register MCP + export SKILL.md
# One-liner: register MacFly as a local stdio MCP server in Claude Code
claude mcp add macfly -- macfly mcp --profile default

# Optional: also export the ready-to-use SKILL.md into your workspace
macfly skill export --output ./.claude/skills/macfly
Codex CLI MCP + ~/.codex/config.toml
# Register MacFly in OpenAI Codex CLI
codex mcp add macfly -- macfly mcp --profile default

# Or add manually to ~/.codex/config.toml:
# [mcp_servers.macfly]
# command = "macfly"
# args = ["mcp", "--profile", "default"]

# Optional: export SKILL.md for Codex instructions
macfly skill export --output ./.codex/skills/macfly
claude_desktop_config.json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "macfly": {
      "command": "/Users/<you>/.cargo/bin/macfly",
      "args": ["mcp", "--profile", "default"]
    }
  }
}
.cursor/mcp.json
// .cursor/mcp.json (or ~/.cursor/mcp.json)
{
  "mcpServers": {
    "macfly": {
      "command": "macfly",
      "args": ["mcp", "--profile", "default"]
    }
  }
}
Local Apple Silicon LLM pipe
# Zero-cloud pipeline with Ollama / MLX (no MCP server needed):
macfly context daily-brief --format agent | ollama run qwen2.5:14b \
  "Summarize my top 3 priorities today and list any overdue reminders."
Copy-paste prompts for MCP & local agents
# Prompt 1 · Meeting preparation (via MCP)
"Use MacFly to run context_meeting_prep for my next meeting with Acme.
Summarize open topics from recent emails and notes, then propose a
plan_create operation to save a preparation note in '10 · Work'."

# Prompt 2 · Safe inbox triage (via MCP)
"Search my Exchange inbox with MacFly for unread emails from this week
about invoices or contracts. Summarize each one and propose draft replies
via plan_create using my native Apple Mail signature. Do not send anything."

# Prompt 3 · Apple Notes cleanup (via MCP)
"Run notes_audit with MacFly. Group all single-note folders into my
00–90 folder structure and propose a single reorganization plan via
plan_create so I can review and approve it in my terminal."

# Prompt 4 · Weekly review & PDF dossier
"Run context_weekly_review with MacFly, highlight overdue reminders and
unanswered threads, and tell me the exact 'macfly report' command to
compile a PDF summary."
~/Library/LaunchAgents/com.casoon.macfly.morning-brief.plist
<!-- Generated by: macfly schedule install --name morning-brief --task daily-brief --hour 7 --minute 30 -->
<!-- Saved to: ~/Library/LaunchAgents/com.casoon.macfly.morning-brief.plist -->
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.casoon.macfly.morning-brief</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/&lt;you&gt;/.local/bin/macfly</string>
      <string>context</string>
      <string>daily-brief</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
      <key>Hour</key><integer>7</integer>
      <key>Minute</key><integer>30</integer>
    </dict>
  </dict>
</plist>