Git branches
Start with the current Handsy AI app experience. The app runs on your iPhone, with a small ESP32 board to see the screen and carry out taps, swipes, and typing. Once the board is set up, you can put the computer away.
The open-source project also keeps its original computer-based setup on legacy. This page is for people exploring that earlier version or working with the source code.
What changed?
Section titled “What changed?”Current · main |
Earlier · legacy |
|
|---|---|---|
| Where the agent runs | App on your iPhone, connected to your chosen model | Python service and web interface on a computer |
| How it sees the screen | AirPlay receiver on the ESP32 board | UxPlay on the computer |
| How it acts | Board connected to the phone as a USB mouse and keyboard | Board controlled by the computer over Wi-Fi |
| Computer during a task | Not needed | Stays running |
| Screen Mirroring name | ESP32 Agent | iPhone Agent |
| On the phone | Handsy app | No app installed |
For the current experience, follow Getting started. The browser installer prepares the board for this version. Legacy uses different firmware; the two are not interchangeable.
Where does the new CLI fit?
Section titled “Where does the new CLI fit?”The upcoming Handsy CLI connects a computer agent directly to the board over Bluetooth. Screen Mirroring is received by the board, as in the current app architecture. It is a separate tool from the Python CLI / MCP bridge on legacy; the legacy tags do not identify the new CLI release.
Watch the original version
Section titled “Watch the original version”This is the original Linux-computer demo. It shows the roots of the project: an AI looking at a real iPhone and using a physical pointer to act.
Original Handsy computer-based demo
Exploring legacy
Section titled “Exploring legacy”Legacy runs UxPlay and a Python server on a computer. The phone and computer share a network; the ESP32 connects to the server over Wi-Fi. The branch also documents Bluetooth HID board variants and an optional CLI / stdio MCP bridge.
To try it:
- Check out the
legacybranch and flash its board firmware withhardware/flash.sh. - Install UxPlay on the computer. On macOS, use
brew install uxplay; Linux and Windows instructions are in the branch README. - From
server/, install the Python package, configure your model endpoint and key, and runpython -m hidagent. - On the phone, turn on AssistiveTouch and mirror to iPhone Agent. Open
http://127.0.0.1:8890on the computer and use Manual controls → Calibrate.
The legacy README contains the platform-specific commands and hardware variants. The CLI bridge belongs to this computer-based setup.
Version history
Section titled “Version history”Legacy has the v0.1.0 and v0.1.1 tags. v0.1.0 is the first formal GitHub Release; v0.1.1 is a later tag. The legacy branch has continued beyond both.
The current main app architecture has no corresponding public version tag or formal Release yet. Board firmware uses its own version numbers. See Changelog for these separate histories.