<2-3 sentences summarising what the project addresses and solves, the target audience, and the benefit.> MobileClaw is an experimental Android runtime for LLM agents, enabling on-device phone control, app automation, and VLM screen reading. It targets developers and power users seeking a flexible, observable platform for complex mobile AI workflows, offering benefits like advanced automation and extensibility.

How It Works

This project functions as an "operating layer" for AI agents on Android. It translates user goals into scoped tasks, managed by a scheduler, planner, and a curated set of skills. The core employs a ReAct-style loop, integrating both AccessibilityService-based (XML) and vision-first (VLM screen reading) screen observation. This structured approach, with task-specific tool scoping, enhances phone automation reliability compared to systems with universally available tools.

Quick Start & Requirements

• Install: Clone the repository (git clone https://github.com/eggbrid2/mobileClaw.git), navigate into the directory, and build the debug APK using ./gradlew :app:assembleDebug. The APK is located at app/build/outputs/apk/debug/app-debug.apk.
• Prerequisites: Android Studio Ladybug+, JDK 21, and an Android 11+ device or emulator are required. An OpenAI-compatible chat endpoint and API key are necessary for cloud model interaction.
• Dependencies: Key technologies include Kotlin 2.2, Jetpack Compose, Chaquopy Python 3.11, LiteRT-LM, mihomo, and hev-socks5-tunnel.
• Links: README_zh.md, WeChat Group (QR code valid until June 12, 2026), CONTRIBUTING.md.

Highlighted Details

• VLM Screen Reading: Offers dual screen reading capabilities: AccessibilityService-based XML parsing and vision-first (see_screen) analysis for interactive elements, with raw screenshot fallback for complex UIs.
• Multi-Agent & Group Chat: Facilitates multi-agent collaboration with long-running, interruptible tasks and customizable chat bubble styles for agents.
• AI App Generation: Supports creating interactive HTML mini-apps within WebViews and native Android "AI Pages" using Compose, with persistent editing context.
• On-Device LLMs: Integrates LiteRT-LM for running local models (e.g., Gemma), with support for multimodal packages and fallback to cloud endpoints.
• VPN & Proxy Runtime: Features a comprehensive VPN stack for agent use, including Clash/Mihomo subscription import, support for various proxy protocols, and Android VpnService integration.
• Embedded Python: Leverages Chaquopy for on-device Python execution, enabling dynamic skill creation and package installation.

Maintenance & Community

A WeChat group serves as the primary community hub for discussions on usage, development, local models, skills, and ROM compatibility. The project's open-source nature encourages community contributions to address device-specific challenges.

Licensing & Compatibility

• License: MIT.
• Compatibility: Requires Android 11+. Certain background features may necessitate ROM-specific configurations, root access, or ADB activation for privileged services.

Limitations & Caveats

MobileClaw is an experimental agent lab, not a polished product, exhibiting "sharp edges" around permissions, ROM policies, VPN configurations, and long-running automation. Some components are research-grade, requiring device-specific fixes, and areas like UI automation on non-standard views and VLM grounding need further development.