English | 正體中文
MoonClicker is an Android automation tool driven by Lua scripts. Through Shizuku, it creates virtual displays where target apps run in the background without taking over your screen, injects touch and key events, and recognizes the screen with on-device template matching and OCR. Scripts are written and debugged from VS Code.
- Background virtual displays: run apps on their own virtual display while you keep using the phone; open any display fullscreen to watch or touch it.
- Lua scripting: an embedded Lua 5.5 runtime with a linear execution model;
sleepandvision.waitreturn immediately when you stop a script. - Concurrent scripts: each display runs its own script, so scripts on different displays run side by side; each one has its own notification, logs, and data, and can be stopped from the app, its notification, or VS Code.
- On-device vision: OpenCV template matching and OCR (ONNX Runtime + PP-OCR), both running locally.
- View tree: find buttons by text, resource id, or class from the on-screen view hierarchy (Android 11 or later).
- MCP server: AI agents can tap, swipe, take screenshots, read the view tree, run Lua in a REPL, and start or stop scripts over the Workbench connection (docs/mcp.md).
- VS Code Script Workbench: low-latency H.264 screen mirroring, F5 to run on the device with live logs per script, PIN pairing, and LuaLS type stubs for completion and checking.
- Android 8.0 (API 27) or later; Android 10 (API 29) or later is recommended, as some features are limited on older versions.
- On Android 17, virtual displays sleep with the main screen. While the screen is off, apps on them stop and ignore input, so a running script keeps going but can't get anything done. Turning on Settings → Experimental → Create virtual displays through VirtualDevice (Android 13 or later) keeps new virtual displays awake.
- Shizuku installed and running.
- For writing scripts: VS Code 1.90.0 or later, or an editor using Open VSX such as VSCodium or Cursor, with the MoonClicker Script Workbench extension.
- Download and install the APK from Releases.
- Make sure Shizuku is running, then open MoonClicker and grant it Shizuku permission.
- To write scripts, install MoonClicker Script Workbench from the Visual Studio Marketplace (VS Code) or Open VSX (VSCodium, Cursor), then follow its README to connect. The app and the extension must share the same major and minor version (x.y).
- Wiki: setup and first-script guides.
- Lua API reference (in Traditional Chinese)
- Example script
- VS Code extension: usage and source
- Roadmap