Apple Flow

Your Apple-Native AI Assistant

Control AI from iMessage, Mail, Reminders, Notes, and Calendar on macOS.

apple-flow-site.vercel.app

Translated READMEs:

• 日本語 (Japanese)
• Español (Spanish)
• Français (French)
• Deutsch (German)
• 简体中文 (Simplified Chinese)
• العربية (Arabic)
• Русский (Russian)
• Kiswahili (Swahili)
• Yorùbá (Yoruba)
• Hausa (Hausa)
• አማርኛ (Amharic)

Apple Flow is a local-first macOS daemon that bridges Apple apps to AI CLIs (Codex, Claude, Gemini, Cline, and Kilo). It enforces sender allowlists, approval gates for mutating work, and workspace restrictions by default.

Video Demo

Watch the walkthrough on YouTube:

• Apple Flow demo

Screenshots

Dashboard	Task Management

AI Policy Log	Calendar Event

Office Brainstorm

Dashboard App

Onboarding 1	Onboarding 2

Onboarding 3	Onboarding 4

Setup Configuration	Onboarding Error

Highlights (Quick Read)

• Local-first Apple-native AI automation with strong safety defaults (allowlist + approval gates + workspace boundaries).
• Multi-gateway operations across iMessage, Mail, Reminders, Notes, and Calendar with deterministic tool flows.
• New Apple Pages support for high-quality document generation from Markdown, including themes, TOC, citations, exports, and section updates.
• New Apple Numbers support for workbook creation, sheet management, row insertion semantics, and styling automation.
• Global skill packs for Codex/Claude-style workflows, including dedicated apple-flow-pages, apple-flow-numbers, apple-flow-mail, and apple-flow-gateways skills.
• Production-friendly operations with service controls, health/status tooling, and comprehensive test coverage.

Start Here

Choose one setup path:

Quick Start (AI-Guided)

1) Prerequisites

• macOS with iMessage signed in
• 10 minutes
• Homebrew + Python 3.11 + Node

# Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python + Node
brew install python@3.11 node

2) Install One AI CLI Connector

Pick one:

• Claude CLI

curl -fsSL https://claude.ai/install.sh | bash
claude auth login

• Codex CLI

npm install -g @openai/codex
codex login

• Gemini CLI

npm install -g @google/gemini-cli
gemini auth login

• Cline CLI

npm install -g cline
cline auth

• Kilo CLI (optional advanced connector)

npm install -g @kilocode/cli
kilo auth login

3) Clone + Bootstrap

git clone https://github.com/dkyazzentwatwa/apple-flow.git
cd apple-flow
./scripts/setup_autostart.sh

4) Finalize Config with the Master Prompt

Open your AI CLI and paste:

• docs/AI_INSTALL_MASTER_PROMPT.md

That flow handles:

• health checks (wizard doctor --json)
• full .env generation from .env.example
• explicit confirmation gates before writes/restarts
• gateway resource setup (Reminders/Notes/Calendar)
• validation + service status verification

5) Grant Full Disk Access

1. Open System Settings -> Privacy & Security -> Full Disk Access
2. Add the Python binary used by Apple Flow (the setup output shows the path)
3. Enable the toggle

6) Smoke Test

Text yourself in iMessage:

what files are in my home directory?

You should receive a reply within seconds.

Setup Paths (Detailed)

A) One-command script only

If you do not want AI-guided setup:

./scripts/setup_autostart.sh

If .env is missing, it launches python -m apple_flow setup to generate one.

B) Manual setup

Edit .env directly:

nano .env

Minimum keys:

apple_flow_allowed_senders=+15551234567
apple_flow_allowed_workspaces=/Users/you/code
apple_flow_default_workspace=/Users/you/code
apple_flow_connector=claude-cli
apple_flow_admin_api_token=<long-random-secret>

For Reminders-backed workflows, apple_flow_reminders_list_name and apple_flow_reminders_archive_list_name must be plain top-level list names such as agent-task and agent-archive. Sectioned lists, grouped lists, nested paths, and Accessibility-backed fallbacks are not supported.

Then validate and restart:

python -m apple_flow config validate --json --env-file .env
python -m apple_flow service restart --json
python -m apple_flow service status --json

Browser Dashboard

The admin service also serves a lightweight Agent Office dashboard for phone and browser access.

Open:

http://localhost:8787/dashboard

If apple_flow_admin_api_token is set, the first visit shows a small dashboard login form. Enter the same admin token there once and the browser receives a dashboard-only HttpOnly cookie scoped to /dashboard.

Practical notes:

• The dashboard is read-heavy and focused on agent-office, companion state, inbox, memory, and logs.
• Mute / Unmute companion are the only built-in dashboard actions in v1.
• The dashboard cookie is scoped to /dashboard, so it does not unlock the broader admin API surface.
• Over Tailscale, use your Mac's Tailscale IP or MagicDNS hostname with port 8787, for example http://your-mac-name.tailnet.ts.net:8787/dashboard.

Core Commands

Multi-workspace routing

Prefix with @alias:

task: @healer run the test suite
task: @web-app deploy to staging
@api show recent errors

File references with aliases

Define file aliases in .env via apple_flow_file_aliases and reference them in prompts with @f:<alias>.

plan: summarize @f:context-bank
task: review @f:runbook and propose updates

Optional Integrations

All optional gateways are off by default.

Trigger behavior:

• Default trigger tag is !!agent
• For Mail/Reminders/Notes/Calendar, only items containing that tag are processed
• Tag is stripped before prompt execution
• Configure via apple_flow_trigger_tag

Enable examples:

apple_flow_enable_mail_polling=true
apple_flow_enable_reminders_polling=true
apple_flow_enable_notes_polling=true
apple_flow_enable_calendar_polling=true

Voice message examples:

apple_flow_phone_owner_number=+15551234567
apple_flow_imessage_auto_send_image_results=owner-only
apple_flow_phone_tts_voice=
apple_flow_phone_tts_rate=180
apple_flow_phone_tts_engine=auto
apple_flow_phone_piper_model_path=/Users/you/models/en_US-amy-medium.onnx

Then trigger with:

voice: standup starts in 10 minutes
voice-task: analyze my workspace

voice: speaks the exact text you send. voice-task: runs the task first, then sends both the text result and a synthesized audio copy over iMessage to the configured owner number. apple_flow_imessage_auto_send_image_results=owner-only also makes outbound replies auto-attach intentional local image results for the owner ins