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:

| Path | Best for | Time | Entry point | |---|---|---:|---| | AI-guided setup (recommended) | Most users, safest onboarding | ~10 min | docs/AI_INSTALL_MASTER_PROMPT.md | | One-command script | Fast local install/autostart | ~5-10 min | ./scripts/setup_autostart.sh | | Manual setup | Advanced/custom environments | ~15+ min | docs/AUTO_START_SETUP.md, docs/ENV_SETUP.md |

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

| Command | What it does | |---|---| | <anything> | Natural chat | | idea: <prompt> | Brainstorming | | plan: <goal> | Plan only (no changes) | | task: <instruction> | Mutating task (approval required) | | project: <spec> | Multi-step task (approval required) | | approve <id> / deny <id> / deny all | Approval controls | | status / status <run_or_request_id> | Run/request status | | health | Daemon health | | history: [query] | Message history | | usage | Usage stats | | help | Help + practical tips | | system: mute / system: unmute | Companion controls | | system: stop / system: restart / system: recycle helpers / system: maintenance / system: kill provider | Runtime controls | | system: cancel run <run_id> | Cancel one run | | system: killswitch | Kill all active provider processes |

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