Apple Flow Project Reference

Module or component: Apple Flow core project Version: 0.6.0 Last updated: 2026-03-10 Maintainer: dkyazzentwatwa

Overview

Apple Flow is a local-first macOS daemon that bridges Apple apps to AI coding assistants. It accepts inbound work from iMessage by default and can optionally ingest work from Apple Mail, Reminders, Notes, Calendar, or the local Admin API, then routes that work through policy checks, orchestration, connector execution, and app-specific egress.

This reference is the canonical high-level guide for contributors who need to understand how the system fits together. Use it alongside setup-focused guides such as QUICKSTART.md, ENV_SETUP.md, AUTO_START_SETUP.md, and the operational safety details in SECURITY.md.

Architecture And Components

Runtime data flow

iMessage DB -> Ingress -> Policy -> Orchestrator -> Connector -> Egress -> AppleScript iMessage
                                        |
                                      Store (SQLite state + approvals)

Apple Mail -> MailIngress -> Orchestrator -> Connector -> MailEgress -> Apple Mail
Reminders.app -> RemindersIngress -> Orchestrator -> Connector -> RemindersEgress / iMessage approvals
Notes.app -> NotesIngress -> Orchestrator -> Connector -> NotesEgress / iMessage approvals
Calendar.app -> CalendarIngress -> Orchestrator -> Connector -> CalendarEgress / iMessage approvals
POST /task -> FastAPI Admin API -> Orchestrator -> Connector -> Egress

CompanionLoop -> proactive observations -> Connector -> iMessage egress
AmbientScanner -> passive context enrichment -> FileMemory / Memory v2
FollowUpScheduler -> scheduled nudges and follow-up actions

Core modules

State model

The SQLite store is the canonical runtime state layer. The main tables are:

Command Surface

User-facing command kinds

Workspace routing

Workspace aliases are configured with apple_flow_workspace_aliases in .env. Users can route a turn to a specific workspace with @alias, for example:

task: @web-app deploy to staging
plan: @logs summarize the latest daemon failures

Admin API

The Admin API is built with FastAPI and listens on apple_flow_admin_host:apple_flow_admin_port (default 127.0.0.1:8787).

If apple_flow_admin_api_token is set, all routes except /health require Authorization: Bearer <token>.

Configuration

Apple Flow uses .env or environment variables with the apple_flow_ prefix. The full field list lives in ENV_SETUP.md and .env.example.

Required baseline settings

Major configuration areas

Error Handling And Logging

• Runtime logging is written to stderr and is typically captured in logs/apple-flow.err.log.
• The events SQLite table is the canonical audit trail.
• CSV mirroring can be enabled for analytics via apple_flow_enable_csv_audit_log.
• Gateway health is surfaced through the Admin API and CLI health checks.
• Duplicate outbound suppression is used to reduce echo loops.

For security-specific failure modes and hardening guidance, see SECURITY.md.

Performance Considerations

• Connector turns are bounded by apple_flow_codex_turn_timeout_seconds.
• Polling cadence is controlled per channel to avoid excessive churn.
• Helper maintenance can soft-recycle long-lived helper processes when enabled.
• Attachment extraction is guarded by size and character-count limits.
• Ambient scanning and companion behavior are opt-in so the default path stays lightweight.

Security

Apple Flow’s main security controls are:

• sender allowlisting
• workspace restrictions
• approval gating for mutating work
• requester verification for approvals
• rate limiting
• read-only iMessage DB access
• optional Admin API bearer authentication

Use SECURITY.md as the canonical threat-model and hardening reference.

Testing

Test strategy

The project uses pytest and pytest-asyncio for async-heavy runtime coverage. Tests focus on orchestration, approval security, routing, connectors, ingress and egress modules, gateway integrations, companion behavior, memory, scheduling, and the admin API.

Core commands

pytest -q
pytest -v
pytest tests/test_orchestrator.py -v
pytest tests/test_admin_api.py -v

Contributor expectation

For behavior changes, run pytest -q before considering the change complete. Add or update tests alongside connector, orchestration, gateway, or security changes.

Contribution Notes

• Start with CONTRIBUTING.md for setup, branch, commit, and PR expectations.
• Use README.md for product-level overview and onboarding paths.
• Use AGENTS.md when working as an AI coding agent inside this repository.
• Keep documentation updates aligned across config.py, .env.example, README.md, and relevant docs pages when adding new settings or commands.

Related Documentation

• README.md
• QUICKSTART.md
• ENV_SETUP.md
• AUTO_START_SETUP.md
• BEGINNER_SETUP_10_MIN.md
• AI_INSTALL_MASTER_PROMPT.md
• SKILLS_AND_MCP.md
• SECURITY.md
• CONTRIBUTING.md
• CHANGELOG.md

Not Applicable To This Project

The generic documentation checklist includes some sections that are not first-class fits for Apple Flow:

• Graph database integration: not applicable.
• A single standalone public API reference for every internal class/function: only partially applicable because the project is primarily a daemon plus CLI, with the Admin API documented separately.
• A per-module changelog in this document: not applicable; the project-level changelog is maintained in CHANGELOG.md.