ShizuStore

Zafiro

niki914

1.11.0 · GitHub

Download APK
AI agents Android 8.0+ 1 day ago MIT
371 ShizuStore
12.1k GitHub
375 Stars
30 MB Size

More about this app

Bring-your-own-key AI agent that reads the screen and controls the device through Shizuku, without root.

中文 | English

zafiro

stars Ask DeepWiki release downloads kotlin lines Codacy

What is Zafiro?

Zafiro is an open-source intelligent Agent running on Android devices, with 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.

Phone-Use HTML Generation External Agents Multimodal
Autonomous mobile GUI navigation and device control via screen pointer Dynamic code generation and instant local browser preview Android MCP server exposing system capabilities to external agents On-device multimodal vision and image understanding
Model Providers Termux Safety Guard Session Management
Custom LLM API keys and multi-provider configuration Integrate remote dev machines via SSH and Termux Human-in-the-loop permission guard and safety interception for sensitive Shell actions Local conversation history management and session branching

Important

For native apps, Zafiro controls the phone via Accessibility Service; for non-native apps, it can also operate via Shizuku without Root. Root users get the full experience.

You can download a release from Releases, or choose to build from source.

Core Capabilities

Modern UI Design Language

  • Material 3 Expressive & 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 pointer 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
  • Context Management - inspect context window usage at any time and compress it
  • Conversation Management - branch, rewind, and regenerate any turn; 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 - use Linux commands and tools on your Android device
  • SSH - connect to a dev machine or server to execute remote tasks
  • Claude Code - issue dev tasks from your phone, executed by a remote Coding Agent

Voice Assistant Takeover

Through the 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.

Demos
Breeno XiaoAi
ColorOS Breeno voice assistant takeover demo HyperOS XiaoAi voice assistant takeover demo

Tech Stack

Category Technology
Language Kotlin
UI Framework Jetpack Compose
Design Language Material Design 3 Expressive
Liquid Glass Android Liquid Glass
Agent Runtime Okia
Python Runtime Chaquopy
System Takeover LSPosed + Xposed API
Terminal / SSH libterm
SVG Rendering coil-resvg (resvg)
G2 Rounded Corners Capsule

Getting Started

Build from Source

./gradlew assembleDebug

Requirements

  • Android Studio (or Android SDK + JDK 17)
  • An Android 11 or above device
Release Signing

To build a Release version yourself, use your own signing key:

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

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
│   ├── files/           # File attachments, document path resolution
│   ├── 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!

Steps

  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)
  4. Push to the branch (git push origin feat/your-feature)
  5. Open a Pull Request

Using Your Coding Agent

Before contributing using coding agents like Codex, make sure they have read the project's AGENTS.md.

Community

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.

Sponsorship

We welcome sponsorships through the following channels:

  • Afdian
  • Tip in Crypto - 0x5f1469519c87edf2245ea04fbb54284c9b76ad3d

License

MIT — see LICENSE.

Made with ✨️ by niki914

Close

How Shizuku is used

Can run shell commands, tap and swipe, launch apps and use isolated displays via `sh`, `input`, `am start` and display APIs through Shizuku.

This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.

How this app uses Shizuku

Zafiro uses Shizuku to let its on device agent run privileged shell operations, control input, launch apps and operate isolated displays.

  • Run agent shell commands: The agent shell tool runs the requested command in a persistent Shizuku shell session and returns output and status.
  • Tap, swipe and press keys: Screen operations perform taps, swipes, scrolls and key presses with the input tap, input swipe and input keyevent shell commands through Shizuku, including targeting a specific display.
  • Launch installed apps: The app launcher starts the selected package with the am start shell command through Shizuku.
  • Grant app permissions: Setup automation grants notification and storage access with the pm grant and appops set shell commands through Shizuku.
  • Enable access features: Setup automation turns on the accessibility service with settings shell commands and allows overlay, storage and notification access with appops set commands through Shizuku.
  • Use isolated virtual displays: The agent can create an isolated virtual display, launch apps on that display and send touch input there through privileged display and input injection.

Android APIs or commands used

  • sh
  • pm grant
  • appops set
  • settings get secure enabled_accessibility_services
  • settings put secure enabled_accessibility_services
  • settings put secure accessibility_enabled
  • input tap
  • input swipe
  • input keyevent
  • am start
  • DisplayManager.createVirtualDisplay
  • ActivityOptions.setLaunchDisplayId
  • ActivityTaskManager.startActivityAsUser
  • InputManager.injectInputEvent
  • setDisplayImePolicy

Notable details

App launching falls back to a normal launch intent without Shizuku.

Close

Changelog

What's new for version 1.11.0

  1. Phone Use now supports virtual displays, allowing tasks to run seamlessly in the background
  2. Add backup and restore support to easily export and import app data
  3. Automatically provide time, device status, and environmental context during conversations
  4. Add comprehensive RTL layout support and new language options (Arabic & Persian); feedback and language contributions are welcome via issues or PRs
  5. Refine Material 3 styling and layout for a cleaner, more consistent look and feel
  6. Fixed several issues and improved overall interaction experience

  1. Phone Use 支持虚拟屏幕,可在后台静默执行自动化操作
  2. 新增数据备份与恢复功能,支持配置与数据的一键导出及恢复
  3. 支持在对话中自动感知时间与设备状态,提供更精准的上下文回答
  4. 优化 Material 设计风格与卡片细节,视觉更贴合原生规范
  5. 修复了一些问题,优化整体交互体验
Close

Permissions

15 permissions requested

  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE
  • android.permission.SYSTEM_ALERT_WINDOW
  • android.permission.FOREGROUND_SERVICE
  • android.permission.FOREGROUND_SERVICE_SPECIAL_USE
  • android.permission.READ_EXTERNAL_STORAGE
  • android.permission.WRITE_EXTERNAL_STORAGE
  • android.permission.READ_MEDIA_IMAGES
  • android.permission.READ_MEDIA_VIDEO
  • android.permission.READ_MEDIA_VISUAL_USER_SELECTED
  • android.permission.MANAGE_EXTERNAL_STORAGE
  • android.permission.WAKE_LOCK
  • android.permission.POST_NOTIFICATIONS
  • com.niki914.zafiro.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION
  • moe.shizuku.manager.permission.API_V23
Close