<img src="docs/assets/openring-logo.png" alt="OpenRing logo" width="128" height="128"> <h1>OpenRing</h1> <p><b>Android AccessibilityService RPA + Chat-Driven AI Agent (Gemini & optional on-device GGUF)</b></p> <p><i>Runs on the phone—no PC backend, no Root; cloud LLM is optional (BYOK)</i></p>

<br/>

繁體中文 | English

</div> <br/>

📖 Introduction

OpenRing helps teams searching for Android RPA, multiple device control, and AI-powered mobile automation deploy reliable, phone-first workflows with no root and no custom backend.

OpenRing is a local Android automation agent that moves across apps with AccessibilityService–driven semantics: it reads structured UI trees, runs scripts and schedules, and—through Chat‑Driven OS—uses Gemini function calling (ReAct) or on-device GGUF models to plan, call tools, and complete tasks.

Everything critical runs on the phone — scripts, schedules, accessibility, skill sandboxes (QuickJS), and optional local LLM inference. A Gemini API key (BYOK) unlocks cloud reasoning, vision (describe_screen), and the full tool loop; without it, you can still use downloaded GGUF models for text chat with streaming replies.

✨ Key Features

🚫 No Root Required: Built on Android's official AccessibilityService, no need to hack or root your phone.
📱 Phone-First: No PC or ADB required; no OpenRing backend — scripts, data, and skills stay on device unless you call a cloud API yourself (e.g. Gemini).
🤖 Chat-Driven Agent: ReAct loop with Gemini tools — get_view_tree, summarize_view_tree (compact UI), describe_screen (vision fallback when the tree is not enough), describe_ambient_audio (hearing: prefers device-internal playback capture via MediaProjection; microphone fallback), taps, input, memory, skills, and more.
🦙 Optional On-Device LLM: Curated GGUF catalog (LocalModelCatalog) with in-app download; token streaming in chat; chat templates for Qwen / Phi / Gemma / TinyLlama-style models (LocalLlmChatPrompt).
👁️ Semantic UI Parsing: View tree → JSON for scripts and automation; large trees can be compacted for LLM context (UiTreeCompact).
🖱️ Human-Like Actions: Clicks, swipes, long press, Back, Home, app launch.
⏰ Scheduling: WorkManager-based triggers for recurring scripts.
🧩 Skill Plugins (QuickJS): call_skill runs sandboxed JS for deterministic helpers (see docs/skill-templates/).
🛠️ Script Editor & Workflows: Create, edit, and run JSON workflows on device.

📈 Activity & Stars

🏗 Architecture & Tech Stack

OpenRing is built entirely in Kotlin and leverages modern Android development practices, including Jetpack Compose for the UI and Coroutines/Flow for asynchronous programming.

Core Components

| Module | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | View Tree Parser | Uses AccessibilityService to traverse the screen's UI node tree and converts it into structured JSON. | | Action Executor | Dispatches standard gestures (click, swipe, global actions) safely using the Accessibility API. | | Intent Router | Wakes up or navigates to target applications using Android Intents, Deep Links, or Package Names. | | Script Engine | Parses and executes predefined JSON/DSL scripts, integrating logic, variables, and conditions. | | Scheduler | Built on Android WorkManager for reliable, background execution of periodic or delayed tasks. | | Agent (ReAct + Tools) | ReActCoordinator + ToolDispatcher — Gemini function calling, tool results, optional UI compaction. | | Local LLM | LocalLlmEngine — GGUF load/inference via llama-kotlin-android, streaming generation for chat. |

Project Structure

OpenRing/
├── app/                  # The main Android Application module
│   └── src/main/
│       ├── core/         # AccessibilityService, Parser, Executor, IntentRouter, ScreenCapture, playback audio / MediaProjection
│       ├── agent/        # ReActCoordinator, ToolSchemas, ToolDispatcher, UiTreeCompact
│       ├── localmodel/   # GGUF catalog, downloader, LocalLlmEngine, chat prompts
│       ├── gemini/       # Gemini REST client & models
│       ├── data/         # Room, ChatRepository, MemoryRepository, ScriptStore
│       ├── domain/       # ScriptExecutor, Scheduler
│       ├── skills/       # QuickJS skill install & execution
│       └── ui/           # Jetpack Compose (Chat, Settings, Skills, Scripts, …)
├── docs/                 # Documentation
│   ├── product/          # PRD, Backlog, Project Plan
│   └── technical/        # Script format, CI/CD, AI agent, skills
└── gradle/               # Build configuration

For more detailed technical documentation, please refer to the files in the docs/ directory.

🚀 Getting Started

Ready to start contributing or build OpenRing yourself? Follow these steps:

1. Prerequisites

Android Studio Jellyfish or newer
Java Development Kit (JDK) 17+
Android SDK Platform 36 and Build-Tools 36.0.0
Android targetSdk 34 device/emulator for runtime validation

2. Clone the repo

git clone https://github.com/SunZhi-Will/OpenRing.git
cd OpenRing

3. Build & Run

You can open the project directly via Android Studio and click Run, or compile using the command line:

./gradlew assembleDebug

The debug APK is written to app/build/outputs/apk/debug/ (typically app-debug.apk).

4. Verification and test status

Current CI baseline is ./gradlew assembleDebug + security scans (CodeQL / dependency review).
The project currently has no committed app/src/test or app/src/androidTest suites.
For now, quality validation relies on successful build plus manual feature checks on device/emulator.
Lint tasks are temporarily disabled due to an AGP lint tool crash in some environments; see docs/technical/CI_CD.md.

Download prebuilt debug APK (CI)

Each successful run of Android CI uploads a debug APK as the workflow artifact openring-debug-apk (a ZIP containing the .apk file).

| Method | Link | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Direct download (ZIP, no GitHub login) | Latest openring-debug-apk.zip via nightly.link — unzip locally, then install the .apk inside. | | GitHub Actions UI | Android CI workflow runs (branch main) → open a green run → Artifacts → openring-debug-apk (GitHub may require login to download). |

Attach APK/AAB to GitHub Releases (recommended)

Release page: SunZhi-Will/OpenRing Releases

When creating a New release, upload installable/distributable files directly in Assets so users can download them without browsing CI runs:

app-release.apk (installable)
app-release.aab (for Play Console)
SHA256SUMS.txt (integrity checks)
`CHANGEL

OpenRing

Install / Use

README