PhoneClaw: on-device Android automation with ClawScript and vision targeting

What PhoneClaw solves, and who ends up using it

Most phone automation stacks assume you can install a helper on a desktop, drive the device over ADB, or root it. PhoneClaw takes the opposite position: everything runs on the handset. The README describes it as an Android automation app that runs on-device workflows and lets you generate automation logic at runtime using ClawScript, a JavaScript-based scripting language built into the app. The stated inspiration is Claude Bot and Claude Code, with the goal of rebuilding the agent loop natively for Android so the phone acts as a personal assistant with access to all your apps.

The intended user is someone with a spare handset. The setup instructions name a $30 Moto G Play bought at Walmart in the US as the cheapest option and the phone used in the demos. That framing matters: PhoneClaw is aimed at people who can dedicate a device to automation, leave it plugged in, and let recurring tasks run. The topics list on the repository (agents, automation, harness, personal-ai, phone, phonefarm) points the same way. If your only phone is the one in your pocket, the permission prompts and app switching in a multi-step flow are a poor fit for daily use.

The agent loop: Accessibility service, screenshots, and ClawScript

Three pieces do the work. First, the Android Accessibility service performs the taps; the README states you do not need to root the device, only developer mode. Second, vision supplies targeting. magicClicker takes a screenshot plus vision to locate a target described in plain language and taps the best-matching element, which is how flows survive layout shifts between devices. magicScraper takes the same screenshot and answers a targeted question about what is visible, returning a concise string you can parse or branch on. Third, ClawScript glues it together: an embedded JS engine exposes helper functions for automation, scheduling, and screen understanding, and the README frames it as built for fast iteration, so you write or generate small scripts at runtime, execute them immediately, and adjust based on UI feedback.

The helper surface is small and worth reading closely. speakText(text) reads out text through on-device TTS. delay(ms) pauses. schedule(task, cronExpression) registers a task string on a cron-like schedule, and clearSchedule() removes all scheduled tasks. sendAgentEmail(to, subject, message) sends mail from the device for notifications or handoffs. safeInt(value, defaultVal) parses to an integer with a fallback. Notice what is absent: there is no documented selector API, no retry primitive, and no wait-for-condition helper beyond delay. That pushes timing logic into fixed sleeps and vision calls, which is the main design trade-off in the project.

Installing PhoneClaw and running a first automation

There is no published APK in the README. You build it. The setup instructions say to download Android Studio, download the repository, open it, and use Build > Generate Bundles or APKs > Generate APKs. The top-level layout matches a standard Gradle Android project: app/, build.gradle.kts, settings.gradle.kts, gradle/, and the gradlew wrapper. Before building, supply your Moondream auth token, which the README says to keep out of git via Gradle properties.

# local.properties (project root) OR ~/.gradle/gradle.properties
MOONDREAM_AUTH=YOUR_TOKEN_HERE

After the APK is generated, transfer it to the phone, tap install, and allow the permissions it requests. The README's step five describes the first real use: open the app and use voice commands to generate a simple automation, with the example "open twitter and click the blue post button every hour". The app runs the agent, schedules it, and outputs a file you can edit in simple language. What you should see is a ClawScript file on the device describing the flow, which you then edit rather than re-record.

That file is where the API becomes concrete. The README's example shows the shape of a generated flow:

magicClicker("Create account")
delay(1500)
magicClicker("Email address field")
// ... type text via your own input helpers
magicClicker("Next")
const otp = magicScraper("The 2FA code shown in the SMS notification")
// ... submit otp

Two details in that snippet are worth pausing on. The comment about typing text says the input helpers are your own, so text entry is not covered by the documented API. And the OTP line shows the intended pattern for magicScraper: ask a narrow question about the screen, get a string back, branch on it. If you schedule this flow, remember that schedule() takes a cron-like expression and clearSchedule() wipes every registered task at once, not one of them.

Where PhoneClaw breaks: timing, permissions, and the missing recovery story

The clearest limitation is that the loop is vision-first and sleep-based. magicClicker and magicScraper each require a screenshot and a vision call, so every step costs a round trip and a token against your Moondream account. The README documents delay(ms) as the pause primitive but documents no wait-until-element-appears helper. On a slow screen, a fixed 1500 ms delay either wastes time or fires too early, and the README does not describe what happens when a target is not found at all. There is no documented return value for a failed magicClicker call, and no error-handling section.

Permissions are the second boundary. The app depends on the Accessibility service, which Android treats as a privileged capability, and the README's only guidance is to click allow when prompted. A flow that spans browser, email, media, and messaging will cross app boundaries, and each app can present its own dialogs, updates, or consent screens that the script has to handle in-band. The README does not document how PhoneClaw responds to a system dialog it was not written for.

Finally, there is no rollback story. The README describes scheduling tasks and clearing all of them, but it does not document pausing a single schedule, undoing a partially completed multi-step flow, or recovering state after the phone reboots. If your automation creates accounts, posts content, or sends email, a half-finished run is a real outcome and the documentation does not tell you how to detect or repair it.

PhoneClaw versus ADB-driven and cloud-device automation

The obvious alternative for Android automation is driving the device from a host over ADB, using something like Appium or a UiAutomator-based harness. The difference in approach is where the decision-making lives. An ADB harness runs the test or script on a computer, sends input events over the wire, and keeps state, logs, and retries on the host. PhoneClaw inverts this: the agent loop, the JS engine, the scheduler, and the vision calls all live on the phone. That means no host machine has to stay connected, which is why the README can pitch a $30 handset as a self-contained automation node. The cost is that debugging happens on the device, and the README points to a Mintlify docs site rather than describing an on-device log viewer.

A second alternative is a cloud device farm, where the phone is remote and you script against a hosted session. PhoneClaw's topic list includes phonefarm, but the README does not describe any fleet management, device enrollment, or remote control plane. As documented, PhoneClaw is one app on one phone. If you need to run the same flow across fifty devices with centralized logs, none of the helpers listed (speakText, delay, schedule, clearSchedule, magicClicker, magicScraper, sendAgentEmail, safeInt) provide that, and sendAgentEmail is the only outbound channel mentioned.

There is also the iOS side. The README links an iOS App, an Apple Vision Pro demo, and what it calls the world's first software-only iPhone Automation, but the repository itself is a Kotlin Android project with an app/ module. The iOS material points at a separate product surface, not at this codebase.

Licence, maintenance, and what upgrading actually costs

The repository is MIT licensed, with a LICENSE file at the top level. MIT is permissive: you can modify and redistribute, and the main practical obligation is preserving the copyright and licence notice. That matters here because the README's setup path asks you to build your own APK, which is a redistribution-adjacent act if you pass the build to anyone else. This is not legal advice; read the LICENSE file for the exact terms.

The maintenance picture is more concrete than the licence. The repository is not archived, and the last push to main was on 2026-08-14. No releases were retrieved, so there is no versioned artifact to pin and no changelog to diff. The README's only dated update entry is from 2/19/26, noting that the app was updated to allow selecting the openrouter model. Upgrading therefore means pulling main and rebuilding, and your local.properties token setup survives that because it lives outside the repository. What does not survive cleanly is anything you changed inside the app/ module, since there is no documented migration path and no version numbers to compare against.

The other cost is external and recurring: Moondream vision calls. Every magicClicker and magicScraper invocation consumes a request against the token you supply. A cron-scheduled flow that runs hourly multiplies that, and the README gives no guidance on rate limits or cost per call.

Editorial conclusion

PhoneClaw fits engineers who already own a spare Android phone and are comfortable building an APK in Android Studio, because the README gives no prebuilt download and no release artifacts were retrieved. It does not fit anyone who needs a supported SDK, a versioned dependency, or a documented rollback path: the README is silent on failure recovery, and the last push to main was on 2026-08-14. Before adopting it, verify two things on your own device: that the Accessibility service plus your Moondream token actually resolve the controls you care about, and that ClawScript's schedule and clearSchedule helpers behave the way your recurring task needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. rohanarun/phoneclaw on GitHub