apple-flow

<div align="center">

# Apple Flow

**Your Apple-Native AI Assistant**

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos)
[![GitHub release](https://img.shields.io/github/v/release/dkyazzentwatwa/apple-flow?include_prereleases)](https://github.com/dkyazzentwatwa/apple-flow/releases)
**[apple-flow-site.vercel.app](https://apple-flow-site.vercel.app/)**

</div>

**Translated READMEs:**
- [日本語 (Japanese)](translations/README.jp.md)
- [Español (Spanish)](translations/README.es.md)
- [Français (French)](translations/README.fr.md)
- [Deutsch (German)](translations/README.de.md)
- [简体中文 (Simplified Chinese)](translations/README.zh-Hans.md)
- [العربية (Arabic)](translations/README.ar.md)
- [Русский (Russian)](translations/README.ru.md)
- [Kiswahili (Swahili)](translations/README.sw.md)
- [Yorùbá (Yoruba)](translations/README.yo.md)
- [Hausa (Hausa)](translations/README.ha.md)
- [አማርኛ (Amharic)](translations/README.am.md)

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](https://youtu.be/8qXBy1ylbmk)

## Screenshots

| Dashboard | Task Management |
|---|---|
| ![Apple Flow dashboard](docs/screenshots/dashboard.png) | ![Apple Flow task management](docs/screenshots/task-management.png) |

| AI Policy Log | Calendar Event |
|---|---|
| ![Apple Flow AI policy log](docs/screenshots/ai-policy-log.png) | ![Apple Flow calendar event](docs/screenshots/calendar-event.png) |

| Office Brainstorm |
|---|
| ![Apple Flow office brainstorm](docs/screenshots/office-brainstorm.png) |

### Dashboard App

| Onboarding 1 | Onboarding 2 |
|---|---|
| ![Apple Flow onboarding step 1](docs/screenshots/onboarding-apple-flow1.png) | ![Apple Flow onboarding step 2](docs/screenshots/onboarding-apple-flow2.png) |

| Onboarding 3 | Onboarding 4 |
|---|---|
| ![Apple Flow onboarding step 3](docs/screenshots/onboarding-apple-flow3.png) | ![Apple Flow onboarding step 4](docs/screenshots/onboarding-apple-flow4.png) |

| Setup Configuration | Onboarding Error |
|---|---|
| ![Apple Flow app setup configuration](docs/screenshots/AppleFlowApp-setup-configuration-screen..png) | ![Apple Flow onboarding error screen](docs/screenshots/apple-flow-onboarding-error..png) |

## 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](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/AUTO_START_SETUP.md), [docs/ENV_SETUP.md](docs/ENV_SETUP.md) |

## Quick Start (AI-Guided)

### 1) Prerequisites

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

```bash
# 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

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

- Codex CLI

```bash
npm install -g @openai/codex
codex login
```

- Gemini CLI

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

- Cline CLI

```bash
npm install -g cline
cline auth
```

- Kilo CLI (optional advanced connector)

```bash
npm install -g @kilocode/cli
kilo auth login
```

### 3) Clone + Bootstrap

```bash
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](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:

```text
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:

```bash
./scripts/setup_autostart.sh
```

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

### B) Manual setup

Edit `.env` directly:

```bash
nano .env
```

Minimum keys:

```env
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:

```bash
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:

```text
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 |
| `

[truncated…]