🌟 Why FlowPilot?

Most Android automation tools force you to choose between steep complexity, heavy battery drain, or intrusive cloud logins. FlowPilot was built to fix this.

📸 Screenshots

Home Screen	Ready Presets	Rule Builder	Settings & Backup	About Dialog

💡 How FlowPilot Works

FlowPilot follows a clear, intuitive 3-step mental model:

┌───────────────────────────┐      ┌───────────────────────────┐      ┌───────────────────────────┐
│       1. TRIGGER          │      │       2. CONDITIONS       │      │        3. ACTIONS         │
│     "When this happens"   │ ───► │    "Only if all match"    │ ───► │    "Do this in order"     │
│   (e.g., Arrive at Work)  │      │     (e.g., Weekdays Only) │      │  (Silent + Turn on Wi-Fi) │
└───────────────────────────┘      └───────────────────────────┘      └───────────────────────────┘

Relatable Examples:

• 🌙 Bedtime Routine: When the clock strikes 23:30 ➔ Only if charging ➔ Turn on Silent Mode, enable Dark Theme, and dim brightness to 10%.
• 🔋 Full Charge Alert: When battery reaches 100% ➔ Speak "Phone is fully charged, please unplug" and show notification.
• 🔕 Flip to Silence: When phone is placed face-down on a desk ➔ Immediately enable Do Not Disturb with a subtle confirmation pulse.

⚡ 1-Tap Ready Presets

Start automating instantly with built-in recipes designed for everyday life:

🎛️ Feature Matrix

1. Triggers (Events)

FlowPilot listens to a rich spectrum of hardware, radio, and system events:

• 📱 App Lifecycle: App launched or closed (lightweight UsageStatsManager transitions).
• 🔌 Power & Battery: Charger plugged in / unplugged, battery level rises above or drops below custom percentage.
• 💡 Screen & State: Screen turned on/off, device unlocked.
• ⏰ Schedule & Time: Daily, weekdays, weekends, or specific days and exact times.
• 📶 Connectivity: Wi-Fi connected/disconnected (any or target SSID), Bluetooth device connected/disconnected.
• 🔄 Sensors & Motion:
  • Device Flip: Face-down on table or turned face-up (Proximity + Gravity Z-axis with 500ms debounce).
  • Shake: Firm shake detection with configurable sensitivity slider.
  • Ambient Light: Lux drops below or rises above target threshold.
• 📍 Hardware Geofencing: Enter or exit defined geographical zones using Google Play Services GeofencingClient. Uses no idle CPU wake-lock, keeps up to 50 queued events across engine restarts, and reuses transition coordinates for template variables.
• 🏷️ NFC Tags: Instant hex UID matching on physical scans. Foreground ReaderMode scans run matching rules automatically; background Android discovery opens FlowPilot and requires explicit confirmation before any matching NFC automation runs.
• 📞 Phone & SMS: Call ringing, answered, outgoing dialed, call ended; SMS received with keyword, prefix, regex, or exact sender matching.
• 🔔 Notifications: Incoming notifications from selected apps with keyword filtering.

2. Conditions (Logic Gates)

Rules execute only when all specified conditions (AND logic) are satisfied:

• ⏳ Time Window: Run only between specific hours (e.g., 23:00 to 07:00), with full midnight-crossing support.
• 📅 Days of the Week: Restrict to weekdays, weekends, or custom individual days.
• 🔋 Battery Level: Require battery to be \(\ge\) or \(\le\) a specific threshold.
• ⚡ Charging State: Require device to be currently charging or discharging.
• 📲 Screen State: Require screen to be on or off.
• 📶 Wi-Fi Network: Require connection to a specific Wi-Fi network (SSID).

3. Actions (Executors)

Chain multiple actions in any custom sequence with drag-and-drop ordering and individual delays (0–300s):

• 🌐 Connectivity (via Shizuku): Toggle Wi-Fi, Mobile Data, Airplane Mode, Bluetooth, and GPS Location.
• 🖥️ Display & Device: Toggle Flashlight (Torch), Dark Theme (Shizuku), Auto-rotate, Brightness level, Lock Screen (Shizuku), and Force Stop App (Shizuku).
• 🔊 Sound & Alerts: Do Not Disturb (DND) toggle, Sound Profiles (Normal / Vibrate / Silent), Media Volume (0–100%), Custom Audio playback (1–60s duration), Haptic Patterns (Pulse, Double Tap, Alert, Heartbeat, Triple Tap, SOS), and Rich Notifications.
• 🗣️ Offline Speech (TTS): Speak custom voice alerts using Android's on-device TTS engine with speech rate control.
• ⏱️ Clock & Timers: Set system alarm or start a background timer (1s–24h).
• 🚀 Apps & Web: Launch installed app or open web URL.
• 💬 Phone & SMS: Open dialer, place direct phone call, send automated background SMS, or prepare SMS draft.
• 🔗 HTTPS Webhook: Send outbound HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD) with custom headers, JSON body, AES-256-GCM Keystore encrypted secrets, and dynamic template variables:
  • ${trigger}, ${batteryPercent}, ${isCharging}, ${wifiSsid}, ${time}, ${timestamp}, ${location.lat}, ${location.lng}, ${location.coords}, ${location.maps_url}

4. Smart Productivity & Controls

• Quick Settings Tile & Engine Notification: Toggle the automation engine or inspect live status directly from Android's notification shade. Engine status and startup-failure notifications follow FlowPilot's English, Turkish, or system-language setting even after a background restart.
• Material 3 Home Screen Widget: Glance-powered widget displaying active rule counts with a one-tap pause/resume button.
• In-App Live Test Run: Test any rule action directly inside the editor before saving to verify parameters.
• Safe Rule Duplication: Clone any rule into an immediately editable disabled copy with freshly encrypted webhook credentials.
• Execution Run History: Local persistent audit trail of the last 100 executions with masked sensitive details. Raw provider errors, private URIs, local paths, credentials, and phone numbers are not persisted.
• Conflict Warnings: Automatic non-blocking analysis warning you when opposite state actions target the same trigger.

🛡️ Shizuku Setup Guide

FlowPilot uses Shizuku to perform elevated actions (Mobile Data, Airplane Mode, GPS, Dark Mode, App Killing) safely without needing root.

1. Install Shizuku: Get it from Google Play or GitHub.
2. Start Shizuku Service:
   • On Android 11+ (Wireless Debugging): Start directly on your phone using Developer Options > Wireless Debugging (no PC required).
   • Via PC (ADB): Run the following command:

     adb shell sh /sdcard/Android/data/moe.shizuku.privileged.api/start.sh
     

3. Authorize FlowPilot: Open FlowPilot and tap Grant when prompted for Shizuku access.
4. All elevated actions will now be unlocked and execute instantly!

🔒 Privacy & Zero-Trust Promise

FlowPilot is engineered with an uncompromised commitment to user privacy:

• 🚫 Zero Telemetry: No Firebase Analytics, no Sentry, no remote crash reporters, and zero tracking SDKs.
• 📵 No Cloud Synchronization: Your automations, logs, and secrets never touch any third-party cloud.
• 🛡️ Android Keystore Protection: Webhook secrets, tokens, and sensitive headers are encrypted with AES-256-GCM using Android Keystore keys, hardware-backed when supported by the device.
• 🙈 Strict Log Sanitization: Phone numbers, webhook credentials, and sensitive headers are masked across all UI screens and audit logs.

Transparent Permission Disclosures

FlowPilot declares sensitive permissions solely to power explicit automation features:

• QUERY_ALL_PACKAGES: Required to list installed apps in the App Trigger and App Launcher pickers on Android 11+.
• RECEIVE_SMS & SEND_SMS: Used exclusively by the SMS trigger and direct SMS responder actions.
• ACCESS_BACKGROUND_LOCATION: Powers zero-battery hardware geofencing (GeofencingClient) and injects coordinates only into user-configured automations.
• FOREGROUND_SERVICE_LOCATION: Required by Android 14+ to keep geofencing and active location tasks compliant while running in the background.

Note: FlowPilot does not seek Google Play approval because these uncompromised permissions are essential for core automation functionality. Download verified APKs directly from GitHub Releases.

📦 Backup & Recovery

Restoring is effortless: choose your file, enter your password, and select Merge or Replace. Secrets are automatically re-encrypted with your new device's local Android Keystore.

🛠️ Tech Stack & Architecture

FlowPilot follows modern Android architecture guidelines:

FlowPilot
├── app/src/main/java/com/flowpilot/app/
│   ├── actions/          # Executors: Shizuku, Audio, TTS, Webhook, SMS, System
│   ├── analysis/         # AutomationConflictAnalyzer and logic checks
│   ├── data/             # Models, JSON Serialization, DataStore Repositories, Backups
│   ├── engine/           # Foreground AutomationService, Receivers, Sensor Trackers
│   ├── glance/           # Jetpack Glance Home Screen Widget
│   ├── quicksettings/    # System Quick Settings Tile Service
│   ├── shizuku/          # Shizuku AIDL IPC client bridge
│   └── ui/               # Jetpack Compose UI (Material 3 Theme, Screens, Components)
└── app/src/test/         # Deterministic JUnit unit test suites

• Language: Kotlin 2.2.10
• UI Toolkit: Jetpack Compose & Material 3
• Async Runtime: Kotlin Coroutines & StateFlow
• Storage: Jetpack DataStore (Preferences & JSON)
• Encryption: Android Keystore (AES-256-GCM)
• Privileged Bridge: Shizuku AIDL IPC
• Widgets: Jetpack Glance
• Target SDK: Android 16 (API 36) • Min SDK: Android 8.0 (API 26)

📥 Build from Source

Prerequisites

• JDK 17 (OpenJDK or Eclipse Temurin)
• Android SDK (Platform 36, Build-Tools 36.0.0+)
• Git

# Clone the repository
git clone https://github.com/emi-ran/flowpilot.git
cd flowpilot

# Run unit tests
./gradlew testDebugUnitTest

# Assemble debug APK
./gradlew assembleDebug

Compiled APK output:

app/build/outputs/apk/debug/app-debug.apk

Install directly to your connected device:

adb install -r app/build/outputs/apk/debug/app-debug.apk

🤝 Contributing

Contributions, bug reports, and ideas are welcome!

• Check out CONTRIBUTING.md to get started.
• Found a bug? Open a Bug Report.
• Want to propose a new trigger or action? Submit a Feature Request.

📄 License

FlowPilot is free and open-source software licensed under the GNU General Public License v3.0 (GPL-3.0).

This release adds safer rule management, strengthens automation trust boundaries, and improves privacy-safe English and Turkish background behavior.

✨ Safer Rule Management

• Duplicate any rule from Home into a disabled, immediately editable copy with a new identity and reset runtime state.
• Duplicated webhook secrets receive fresh Android Keystore ciphertext; cached TTS audio is copied independently with failure-safe cleanup.
• Conflict warnings detect opposing state actions before saving or enabling a rule.
• Warnings distinguish likely and possible conflicts, preserve the pending operation, allow inspection of the conflicting rule, and require deliberate override.

🛡️ Automation Security

• Background NFC discovery now requires visible confirmation before a matching automation can run; trusted foreground ReaderMode scans remain automatic.
• Webhook connections pin initial delivery to prevalidated public IP addresses while preserving TLS hostname verification.
• Rendered webhook headers reject unsafe input, and HTTP/1.1 response parsing is bounded.
• SMS and notification events are accepted only while the engine is enabled, freshness-limited, bounded, and reauthorized immediately before execution.
• Durable execution leases and rule-revision checks prevent cooldown races and revoke queued work after a rule changes.

🔒 History Privacy

• Execution-history rule names, trigger snapshots, action arguments, and failure messages are sanitized before persistence and during legacy migration.
• Raw provider errors, private URIs, local paths, credentials, phone numbers, and embedded synthetic markers are not retained in history.
• Executors and dispatcher failures use stable privacy-safe outcomes instead of persisting raw exception text.

🌐 Language & Background Notifications

• Engine and startup-failure notifications follow saved English, Turkish, or system-language selection across boot, service restart, process recreation, and task removal.
• Changing language refreshes active notification text, channel metadata, and widget state immediately.
• System-language mode no longer remains stuck on a previously selected app language.

🌍 Project Site & Release Integrity

• Project site gains improved mobile layout, browser-language selection, accessible brand navigation, honest network/runtime claims, and v1.1.0 installation guidance.
• Release automation requires exact version/tag alignment, current main, successful Build & Test for exact release commit, prepared notes, verified APK identity/signature, and signed APK output.

🧪 Verification

• Required GitHub Build & Test completed successfully for exact release commit 98f10b1763911378ef6ff1a5cfd51ce4c8532efa.
• Release workflow completed resource contracts, debug unit tests, Android lint, debug APK assembly, and signed release APK assembly.
• Physical-device checks passed for safe rule duplication, conflict warnings, background NFC confirmation, and language switching.
• Release workflow verified APK SHA-256 before publication.

📥 Installation

1. Download FlowPilot-v1.1.0.apk from Assets below.
2. Download FlowPilot-v1.1.0.apk.sha256 or copy checksum below.
3. Verify APK checksum before installation.
4. Install on Android 8.0+ (API 26–36). Configure Shizuku only for privileged system actions.

SHA-256 Checksum

SHA256 (FlowPilot-v1.1.0.apk) = a5d8c1d2a036b9c588cc02857f0245528721d6a15baf18df25b9db389dd89efd

📱 Compatibility

Developed and tested primarily on Xiaomi HyperOS (Xiaomi 15T Pro). Android OEM background restrictions can differ. Background NFC discovery requires explicit confirmation; foreground ReaderMode scans remain automatic. Privileged system actions require active Shizuku permission.

🇹🇷 Türkçe Özet

• Ana ekrandan kurallar güvenli biçimde çoğaltılabilir; kopya devre dışı oluşturulur, hemen düzenlemeye açılır ve çalışma durumu sıfırlanır.
• Kural kaydedilirken veya etkinleştirilirken karşıt işlemler için olası çakışma uyarıları gösterilir.
• Arka plan NFC keşfi otomasyonu çalıştırmadan önce görünür kullanıcı onayı ister; ön plandaki ReaderMode taramaları otomatik çalışmaya devam eder.
• Webhook bağlantıları doğrulanmış genel IP adreslerine sabitlenir; TLS ana makine doğrulaması korunur ve güvenli olmayan başlıklar reddedilir.
• SMS ve bildirim olayları yalnız motor etkinken, süre ve boyut sınırlarıyla kabul edilir; çalıştırmadan hemen önce yeniden yetkilendirilir.
• Çalıştırma geçmişindeki hata, argüman, kural adı ve tetikleyici verileri kaydedilmeden önce gizlilik için temizlenir.
• Motor bildirimleri, başlangıç hata bildirimleri ve kanal bilgileri seçilen uygulama dilini kullanır; dil değişikliği etkin bildirimlere hemen uygulanır.
• Kural çoğaltma, çakışma uyarısı, NFC onayı ve dil değişikliği fiziksel cihazda doğrulandı.
• Kurulumdan önce FlowPilot-v1.1.0.apk dosyasının SHA-256 değerini doğrulayın.