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
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 MCPplan_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 injournal.jsonl.
$ 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
{
"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"
}
]
}{
"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 --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
---
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 Silicontitle,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 firstUse 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.pdffor a ready-to-share PDF in one step,--output dossier.typif you want to tweak the Typst layout or pass it torenderreport, or--output dossier.mdfor plain Markdown.
$ 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
# 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// 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 aftermacfly config init) and amail.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 --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
{
"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) orcargo install macfly, then add the 4-linemcpServersblock 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 runmacfly plan inspect,approve, andapplyin your terminal.
$ 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
# 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# 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// ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"macfly": {
"command": "/Users/<you>/.cargo/bin/macfly",
"args": ["mcp", "--profile", "default"]
}
}
}// .cursor/mcp.json (or ~/.cursor/mcp.json)
{
"mcpServers": {
"macfly": {
"command": "macfly",
"args": ["mcp", "--profile", "default"]
}
}
}# 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."# 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."<!-- 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/<you>/.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>