Beginner Setup (10 Min)

This guide gets apple-flow running fast on macOS with the safest default path.

What you need first

• macOS with iMessage signed in
• Python 3.11+ (python3 --version)
• At least one AI CLI installed:
  • Codex (default): codex binary — developers.openai.com/codex/cli
  • Claude Code CLI: claude binary — claude.ai/code
  • Gemini CLI: gemini binary — github.com/google-gemini/gemini-cli
  • Cline CLI: cline binary — supports multiple providers
  • Kilo CLI: kilo binary
  • Ollama: local Ollama server (http://127.0.0.1:11434) with model installed

10-minute quick path

Option A: Dashboard App (2 minutes, no terminal)

1. Download AppleFlowApp-macOS.zip from the latest release
2. Extract and open AppleFlowApp.app
3. Follow the setup wizard to configure and start the daemon

Done! Skip to step 6 to send your first message.

Option B: Terminal Setup (10 minutes)

1) Go to the project (30 sec)

cd <path-to-apple-flow>

2) Create your local env file (30 sec)

cp .env.example .env

3) Edit .env with your real values (2 min)

Open .env and confirm these at minimum:

• apple_flow_allowed_senders=+1YOURNUMBER
• apple_flow_allowed_workspaces=/Users/yourname/code
• apple_flow_default_workspace=/Users/yourname/code/my-project
• apple_flow_connector=codex-cli (default), apple_flow_connector=claude-cli, apple_flow_connector=gemini-cli, apple_flow_connector=cline, apple_flow_connector=kilo-cli, or apple_flow_connector=ollama

Important: your own phone number must be in apple_flow_allowed_senders or relay messages will be blocked.

4) Authenticate your AI backend once (1 min)

Run the command for whichever backend you set in .env:

# If using apple_flow_connector=codex-cli (default)
codex login

# If using apple_flow_connector=claude-cli
claude auth login

# If using apple_flow_connector=gemini-cli
gemini auth login

# If using apple_flow_connector=cline
# Usually uses its own provider auth (often configured by your Cline setup).

# If using apple_flow_connector=kilo-cli
# Configure Kilo auth with your usual Kilo auth flow (commonly `kilo auth login`).

5) Run beginner setup + tests + daemon (3-4 min)

./scripts/start_beginner.sh

What this script does for you:

• Creates .venv if needed
• Installs dependencies
• Validates .env safety fields
• Runs pytest -q
• Starts the relay daemon in foreground mode

6) Send your first iMessage command (1 min)

From your allowed sender number, text one of:

• relay: hello
• idea: build a tiny todo app
• plan: add login to my project
• task: create a README section

7) Stop when done (5 sec)

In the terminal running the daemon, press Ctrl+C.

Fast troubleshooting

• Safety stop: apple_flow_allowed_senders is empty
  • Set your number in .env (example: +15551234567).
• Messages DB not found
  • Check apple_flow_messages_db_path (default should be /Users/<you>/Library/Messages/chat.db).
• No responses to your texts
  • Confirm your sender number exactly matches apple_flow_allowed_senders.
  • If apple_flow_require_chat_prefix=true, confirm your message uses the relay: prefix.

Optional manual run (without helper script)

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -q
python -m apple_flow daemon