zafiro

<div align="right"> **[中文](README_CN.md)** | English </div> <p align="center"> <img src="https://socialify.git.ci/niki914/zafiro/image?custom_description=Android+%C2%B7+Native+Agent+%C2%B7+Skills+%C2%B7+MCP%0APython+%2F+Phone-Use+%2F+Shell&description=1&font=Raleway&language=1&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjE4IDE4IDcyIDcyIiB3aWR0aD0iNTEyIiBoZWlnaHQ9IjUxMiI%2BCiAgPCEtLSDog4zmma%2FvvJrlrp3nn7Pok50gLS0%2BCiAgPHJlY3QgeD0iMCIgeT0iMCIgd2lkdGg9IjEwOCIgaGVpZ2h0PSIxMDgiIGZpbGw9IiMwRjUyQkEiLz4KCiAgPGcgc3Ryb2tlPSIjRkZGRkZGIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGZpbGw9Im5vbmUiPgogICAgPCEtLSDlt6bkvqflpJbova7lu5Pnur8gLS0%2BCiAgICA8cGF0aCBkPSJNNTQsMzQgTDQ0LDUyLjMgQzQ1LjQsNTMuNyA0NS40LDU1LjMgNDQsNTYuNyBMNTQsNzQiIHN0cm9rZS13aWR0aD0iMiIvPgogICAgPCEtLSDlt6bkvqflhoXmo7Hnur8gLS0%2BCiAgICA8cGF0aCBkPSJNNTQsMzQgTDQ5LDUyLjMgQzQ5LjQsNTMuNyA0OS40LDU1LjMgNDksNTYuNyBMNTQsNzQiIHN0cm9rZS13aWR0aD0iMS41Ii8%2BCiAgICA8IS0tIOWPs%2BS%2Bp%2BWGheajsee6vyAtLT4KICAgIDxwYXRoIGQ9Ik01NCwzNCBMNTksNTIuMyBDNTguNiw1My43IDU4LjYsNTUuMyA1OSw1Ni43IEw1NCw3NCIgc3Ryb2tlLXdpZHRoPSIxLjUiLz4KICAgIDwhLS0g5Y%2Bz5L6n5aSW6L2u5buT57q%2FIC0tPgogICAgPHBhdGggZD0iTTU0LDM0IEw2NCw1Mi4zIEM2Mi42LDUzLjcgNjIuNiw1NS4zIDY0LDU2LjcgTDU0LDc0IiBzdHJva2Utd2lkdGg9IjIiLz4KICAgIDwhLS0g5Ye56Zm35bGC5LiK5LiL55WM6Z2i55qE5rC05bmz5qiq57q%2FIC0tPgogICAgPHBhdGggZD0iTTQ0LDUyLjMgTDY0LDUyLjMiIHN0cm9rZS13aWR0aD0iMS41Ii8%2BCiAgICA8cGF0aCBkPSJNNDQsNTYuNyBMNjQsNTYuNyIgc3Ryb2tlLXdpZHRoPSIxLjUiLz4KICA8L2c%2BCjwvc3ZnPgo%3D&name=1&owner=1&pattern=Diagonal+Stripes&theme=Auto" alt="zafiro"/> </p> <p align="center"> <a href="https://github.com/niki914/zafiro"><img src="https://img.shields.io/github/stars/niki914/zafiro?label=stars" alt="stars"/></a> <a href="https://deepwiki.com/niki914/zafiro"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"/></a> <a href="https://github.com/niki914/zafiro/releases/latest"><img src="https://img.shields.io/github/v/release/niki914/zafiro?include_prereleases" alt="release"/></a> <a href="https://github.com/niki914/zafiro/releases/latest"><img src="https://img.shields.io/github/downloads/niki914/zafiro/total" alt="downloads"/></a> <img src="https://img.shields.io/badge/kotlin-68.1k-blue" alt="kotlin lines"/> <a href="https://app.codacy.com/gh/niki914/zafiro/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/b4cadbe5d2d74e3885106562cbd9715b" alt="Codacy"/></a> </p> ## What is Zafiro? Zafiro is an open-source intelligent Agent running on Android devices, with [BYOK](https://www.ibm.com/think/topics/byok) support. It understands your screen, controls your device, and carries out operations across apps — with full support for Skills, MCP, and memory. It can also run Shell and Python 3 natively and wrap tools on its own to perform tasks such as web search and file downloads, or connect to a remote dev machine via SSH. <table align="center"> <tr> <tr> <td align="center"><img src="https://github.com/niki914/zafiro/blob/main/res/zafiro__phone_use.gif?raw=true" alt="Zafiro picks and plays music in Spotify via Phone-Use" width="135" height="300"/></td> <td align="center"><img src="https://github.com/niki914/zafiro/blob/main/res/zafiro__net_research.gif?raw=true" alt="Zafiro completes web research with headless web search and article reading via Python scripts" width="135" height="300"/></td> <td align="center"><img src="https://github.com/niki914/zafiro/blob/main/res/zafiro__native.gif?raw=true" alt="Zafiro downloads an APK from the web via Python and installs it with Root" width="135" height="300"/></td> <td align="center"><img src="https://github.com/niki914/zafiro/blob/main/res/zafiro__settings_screen.png?raw=true" alt="Zafiro settings screen" width="142" height="300"/></td> </tr> <tr> <td align="center">Device Control</td> <td align="center">Research</td> <td align="center">Install Apps from the Web</td> <td align="center">Settings</td> </tr> </tr> </table> > [!IMPORTANT] > Zafiro runs via [Shizuku](https://github.com/RikkaApps/Shizuku) — no Root required; Root users get the full experience. > > You can download a release from [Releases](https://github.com/niki914/zafiro/releases/latest), or choose to [build from source](#from-source). ## Core Capabilities ### Modern UI Design Language - **[Material 3 Expressive](https://m3.material.io/) & Apple Liquid Glass** - a modern, polished interface - **Personalized Theming** - multiple theme colors with dark mode and dynamic color extraction - **Multilingual Support** - English, 中文, 日本語, Español - **Background Interaction** - sleek floating ball and notification tray UI to follow and interact with the Agent in real time ### Device Control - **Screen Interaction** - open apps, pick music, order food — all done for you - **Fully Visible** - an on-screen mouse shows every step the Agent takes ### Agent System - **Out-of-the-Box** - built-in support for OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, Kimi, Alibaba Bailian, SiliconFlow, and more - **Extend as Needed** - full support for Skills and MCP, plus memory and a workspace — extend it your way - **Permission Management** - with configurable rules, every command and piece of code is under your control - **Conversation Control** - rewind, edit, and regenerate any turn at will; all conversation data stays strictly local, and models can be switched on the fly within the same session ### Python Tools - **Run Code Directly** - run Python 3 natively on the device - **Meta-Tooling** - wrap your own Python tools; the Agent reuses and maintains the tools it creates - **Built-in Scenarios** - web search, web page reading, and APK installation work out of the box ### Remote Environments - **[Termux](https://github.com/termux/termux-app)** - use Linux commands and tools on your Android device - **SSH** - connect to a dev machine or server to execute remote tasks - **[Claude Code](https://github.com/anthropics/claude-code)** - issue dev tasks from your phone, executed by a remote Coding Agent ## Voice Assistant Takeover Through the [LSPosed](https://github.com/lsposed/lsposed) framework, Zafiro can take over your system voice assistant — wake Breeno or XiaoAi, and the one actually answering is your own Agent. You can decide, based on keywords, which requests go to Zafiro and which pass through to the native assistant. After takeover, the assistant retains full Agent capabilities including device control. > [!NOTE] > Taking over the system voice assistant requires **Root + LSPosed**, and currently supports: OPPO - Breeno > > Voice takeover availability may be affected by phone model, system version, voice assistant version, and vendor system restrictions. When your device does not yet support system assistant takeover, you can still use Zafiro's chat interface with all Agent capabilities. <details> <summary>Demos</summary> <table align="center"> <tr> <td align="center" valign="middle"><img src="https://github.com/niki914/zafiro/blob/main/res/breeno__github_mcp.gif?raw=true" alt="Zafiro voice assistant takeover demo" width="200"/></td> <td align="center" valign="middle"><img src="https://github.com/niki914/zafiro/blob/main/res/hyper__intro.gif?raw=true" alt="Zafiro voice assistant takeover demo" width="200"/></td> <td align="center" valign="middle"><img src="https://github.com/niki914/zafiro/blob/main/res/breeno__magisk.gif?raw=true" alt="Zafiro voice assistant takeover demo" width="200"/></td> </tr> </table> </details> ## Tech Stack | Category | Technology | |------------|----------------------------------------------------------------------| | Language | [Kotlin](https://kotlinlang.org/) | | UI Framework | [Jetpack Compose](https://developer.android.com/jetpack/compose) | | Design Language | [Material Design 3 Expressive](https://m3.material.io/) | | Liquid Glass | [Android Liquid Glass](https://github.com/Kyant0/AndroidLiquidGlass) | | Agent Runtime | [Okia](https://github.com/niki914/okia) | | Python Runtime | [Chaquopy](https://chaquo.com/chaquopy/) | | System Takeover | [LSPosed](https://github.com/lsposed/lsposed) + Xposed API | | Terminal / SSH | [libterm](https://github.com/niki914/libterm) | | SVG Rendering | [coil-resvg](https://github.com/hash-sequence/coil-resvg) (resvg) | | G2 Rounded Corners | [Capsule](https://github.com/Kyant0/Capsule) | ## Getting Started ### Build from Source ```bash ./gradlew assembleDebug ``` ### Requirements - Android Studio (or Android SDK + JDK 17) - An Android 11 or above device <details> <summary>Release Signing</summary> To build a Release version yourself, use your own signing key: ```bash keytool -genkeypair -v -keystore my-release.jks \ -keyalg RSA -keysize 2048 -validity 10000 -alias my_key ./gradlew assembleRelease \ -PRELEASE_STORE_FILE=/absolute/path/to/my-release.jks \ -PRELEASE_STORE_PASSWORD=yourStorePassword \ -PRELEASE_KEY_ALIAS=my_key \ -PRELEASE_KEY_PASSWORD=yourKeyPassword ``` </details> ## Project Structure ``` ./ ├── app/ # Main app: Compose UI, AgentRuntimeService, Xposed hooks ├── business/ # Core business layer (separation of contracts and implementations) │ ├── api/ # Public business contract interfaces │ ├── agent/ # Agent core logic, conversation orchestration & state flow │ ├── notification/ # Resident notification, foreground service & channel management │ ├── permission/ # Unified permission manager (Root / Shizuku auto-granting, tool approval) │ └── application/ # Application management & lifecycle ├── agent-runtime/ # Agent runtime: LLM invocation, Tool/Skill/MCP execution, Python runtime ├── xsettings/ # Lightweight configuration module (depended on by modules as needed) ├── store/ # Store persistence, IPC bridge (XIpcBridge) ├── ui-kit/ # Shared Compose components, LiquidScreen shell, navigation ├── remote-view/ # Cross-process / floating RemoteView components ├── xposed-api/ # Xposed event types, shared constants (shared by main app and host process) ├── xposed-runtime/ # Xposed runtime, hook base classes └── libs/ ├── logging/ # Logging library ├── okia/ # Okia Agent runtime base library └── libterm/ # Terminal library (multiple backends: libsu, shizuku, ssh, etc.) ``` ## Roadmap - System voice assistant integration (non-Xposed takeover) - File import / sharing from outside the app - Built-in skills like Termux, `/skill` hints, and cloud skill imports ## Contributing Pull requests are welcome! 1. Fork this project 2. Create a feature branch (`git checkout -b feat/your-feature`) 3. Commit your changes (`git commit -m 'feat: add your feature'`, following [Conventional Commits](https://www.conventionalcommits.org/en/)) 4. Push to the branch (`git push origin feat/your-feature`) 5. Open a Pull Request ## Community - [Telegram](https://t.me/+ZPX2xtSl6RwyZGNl) — discuss, ask questions, give feedback - [GitHub Issues](https://github.com/niki914/zafiro/issues) — report bugs or request features - [Afdian](https://afdian.com/a/niki914) — support the developer When reporting an issue, please include as much detail as possible: phone model and Android version, system voice assistant and its version, Zafiro version, steps to reproduce, and screenshots or screen recordings. ## License MIT — see [LICENSE](LICENSE). <p align="center"> Made with ✨️ by <a href="https://github.com/niki914">niki914</a> </p>