PhysiClaw: A Phone Agent That Taps the Screen With a Stylus

The apps PhysiClaw targets are the ones that refuse to be automated

Most of the errands PhysiClaw lists (ordering takeout, buying groceries, booking a ride, paying a bill) live in mobile apps that expose no public API. The README is direct about why: simulated input, whether desktop automation or Android's ADB, leaves software fingerprints that anti-bot systems flag. The project's answer is to stop simulating input at the software layer and act on the screen the way a person does. A camera watches the display, a stylus performs the taps and gestures, and the phone sees an ordinary finger. The intended user is someone who wants a closed app driven on their behalf without installing anything on the device, without OAuth flows, and without a cable. That is a narrower audience than 'anyone who wants an AI agent'. It is for people who already accept that the phone is a black box and are willing to put hardware around it.

Camera in, stylus out: the loop that replaces the API

The README describes the mechanism in one line: PhysiClaw watches a phone's screen with a camera and taps it with a stylus. There is no on-device agent, no accessibility service, and no ADB bridge. The screen is treated as the interface, which is why the project claims it reaches virtually any app. The runtime is a continuous loop. It wakes the agent when a scheduled task is due or when the screen lights up with a new message, unlocks the phone, reads the incoming message, performs the task, and pauses for confirmation when an action matters, with payments given as the example. It then replies with the result, saves its memory, and exits until the next wake. The conversational surface is a dedicated phone running its own WhatsApp account; you add it as a contact and send plain-language instructions such as 'Order a latte on DoorDash.' The repository does not document the vision model, the gesture planner, or how screen coordinates are mapped to stylus movement, so the internal architecture beyond this loop cannot be confirmed from the material. What is clear is the trade-off the README states outright: a few seconds per action, in exchange for universality and reliability.

Install commands and the hardware you must supply first

The README states you need the PhysiClaw hardware (arm, stylus, camera) plus an iPhone for it to operate, and that the CLI runs on macOS, Windows and Linux. Installation is a single script that pulls in uv, Python 3.12 and physiclaw:

curl -fsSL https://physiclaw.ai/install.sh | bash

On Windows the equivalent is:

iwr -useb https://physiclaw.ai/install.ps1 | iex

Configuration is done through the CLI. physiclaw models key <provider> registers an LLM API key, and physiclaw models use <provider/model> selects the model the agent runs on. physiclaw doctor checks the environment, which is the step to run before trusting anything else. Running physiclaw with no arguments starts the server, opens the hardware-setup wizard, and then runs the agent. The repository also publishes hardware releases named physiclaw-hardware-v0.17, v0.16 and v0.15, each described as an assembly manual, sourcing guide and printed parts in STEP format. The cadence of those releases (three within about five weeks in mid-2026) suggests the hardware design is still moving, so pinning a specific hardware version matters if you print parts yourself.

The failure modes are physical, and the README does not inventory them

Because the agent depends on a camera and a stylus, its failure modes are mechanical and environmental rather than purely software. The README does not describe what happens when the phone shifts on the desk, when ambient light changes, when a notification covers the target control, or when the stylus misses a tap. It also does not state which iPhone models or iOS versions are supported, only that an iPhone is required. Those are real gaps for anyone planning a deployment. The speed penalty is acknowledged in the README itself: a few seconds per action. That makes PhysiClaw a poor fit for anything time-sensitive, such as grabbing a limited-stock item or completing a checkout before a session expires. It is also the wrong tool if you control the target service and can build an API integration, because you would be adding a robot arm to solve a problem a token and an HTTP client already solve. And if the task requires reading data the screen does not display, the camera-first design gives you nothing to work with.

How it differs from Appium, ADB and GUI-agent frameworks

The closest alternatives are Android automation stacks such as ADB plus Appium, and GUI-agent projects that drive a device through simulated input. Both share PhysiClaw's premise that the screen is the interface, but they act through the operating system's input layer rather than through the air. ADB and Appium require developer mode, a host connection and, on Android, an automation driver installed on the device; PhysiClaw requires none of that and, per the README, leaves nothing for anti-bot systems to flag because there is no software input path at all. The cost is hardware: an arm, a stylus and a camera, plus a dedicated phone. The other difference is the target platform. ADB and Appium work on Android; PhysiClaw's README specifies an iPhone. If your fleet is Android, this project's approach does not map onto it without hardware you would have to design yourself. If your concern is that server-side bot detection blocks your automation, the physical route is the one thing these tools cannot offer.

Maintenance, hardware revisions and what the MIT licence actually covers

Two maintenance surfaces exist. The first is the software: the CLI installs Python 3.12 and physiclaw, and model selection is a CLI setting, so switching LLM providers is a command rather than a code change. The second is the hardware, which is versioned separately. The releases show v0.15, v0.16 and v0.17 published between late July and early August 2026, each bundling an assembly manual, a sourcing guide and STEP files. Anyone who prints the parts should expect to reprint when the design changes, and should check the sourcing guide for the current bill of materials rather than assuming an older version's parts still fit. The licence is MIT for both the CAD-as-code hardware and the agent software, which permits modification, redistribution and commercial use provided the licence notice is preserved. That is a permissive position, but it says nothing about the terms of the apps the agent operates; automating a third-party service can violate that service's own agreement, and the repository does not address this.

Who should build one, and what to check before you do

PhysiClaw is for someone who wants a specific closed app driven on a phone they own, who is comfortable assembling or sourcing mechanical hardware, and who values the absence of a software footprint over speed. It is not for teams that need throughput, headless operation, or Android support, and it is not a substitute for an API when the service you are targeting offers one. Before spending anything, run physiclaw doctor after configuring a provider with physiclaw models key and physiclaw models use, and read the latest physiclaw-hardware release notes and sourcing guide to see what the current build actually requires. The README's own framing is the fairest summary of the bet: a few seconds per action, in exchange for universality and reliability.

Editorial conclusion

Adopt PhysiClaw only if you are willing to build or buy the arm, stylus and camera, dedicate an iPhone to it, and accept a few seconds per action; anyone who needs fast, headless, high-volume automation should stay with API or ADB-based tooling, and anyone who will not run a separate phone with its own WhatsApp account is not the target user. Before committing, verify three things from the repository and docs: the current hardware release version and its sourcing guide, the supported iPhone models and iOS versions, and whether the physiclaw doctor check passes on your machine after physiclaw models key and physiclaw models use are configured. The MIT licence covers both the CAD-as-code hardware and the agent software, so forks and commercial derivatives are permitted, but you are responsible for checking that your use of the target apps complies with their terms.

Official sources

1. License: MIT
2. physiclaw/PhysiClaw on GitHub
3. Project website
4. README
5. Releases