---

[!NOTE] 📱 Device Compatibility & Community Testing Notice FlowPilot is an independent open-source project, actively developed and primary-tested on Xiaomi HyperOS (Xiaomi 15T Pro). Strict adherence to standard Android Jetpack and system APIs is maintained throughout the codebase, and CI verifies runtime contracts against an API 35 Android Emulator.

Because OEM skins (Samsung One UI, Google Pixel, Motorola, OxygenOS, etc.) implement background process limits differently, your test reports, feedback, and pull requests are warmly welcomed!

---

🌟 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

---

💡 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.