lxe/phoneuse

What it does

phoneuse lets a Linux desktop see and operate an unmodified iPhone. The phone screen is received over AirPlay with UxPlay and shown as a desktop window, while the PC acts as a Bluetooth HID mouse and keyboard for the phone. Clicking the mirror taps, dragging swipes, and typing on the keyboard enters text on the device. The same interface is also served in a browser at http://localhost:8777.

The phone needs no jailbreak, developer account, cable or installed app. It relies on iOS Screen Mirroring and AssistiveTouch, which every iPhone already has. Beyond manual use, every action is exposed as a subcommand, so scripts and agents can take a screenshot, read the screen as positioned text, tap, swipe, type, or open apps. An MCP server and a Claude Code skill are included for agent-driven use.

Requirements and install

The documented setup is tightly scoped: it was developed on Arch Linux with Hyprland and an NVIDIA GPU, against an iPhone 17 Pro running iOS 26. It needs BlueZ, Hyprland (window geometry and cursor come from its IPC), UxPlay, GStreamer with GTK 4 and gtk4paintablesink, Python 3.11+ with several packages, and grim for screenshots. uv is only needed for the optional screen-reading models. The phone and PC must share a network for AirPlay, and the PC's Bluetooth must reach the phone.

1. Clone the repository and put the command on your path (setup steps):

   git clone https://github.com/lxe/phoneuse.git ~/phoneuse
   ln -s ~/phoneuse/bin/phoneuse ~/.local/bin/phoneuse
   

2. Run the installer with sudo, which configures bluetoothd for HID output and starts the phoneuse-hid service: phoneuse install. The README warns this disables bluetoothd's own input and hostname plugins, so the PC stops accepting Bluetooth keyboards and mice of its own.
3. Open TCP 7000, 7001, 7100 and UDP 6000, 6001, 7011 if a firewall is in use.
4. On the iPhone, enable Settings → Accessibility → Touch → AssistiveTouch and turn Dwell Control off. For the debugging/telemetry tools, set the pointer to a large orange color with auto-hide disabled.
5. Pair PhoneUse under Settings → Bluetooth; the first paired device is trusted via /etc/phoneuse/allowed.
6. Start with phoneuse up, then choose Control Center → Screen Mirroring → PhoneUse. A phone-shaped window appears on the desktop.

Agent and browser use

Actions are subcommands; phoneuse --help lists them. A typical loop is phoneuse open Settings, phoneuse text, phoneuse tap-on "Wi-Fi", phoneuse screenshot shot.png, phoneuse back (CLI example). For MCP, run scripts/setup-mcp.sh and register the server with claude mcp add --scope user phoneuse ~/phoneuse/bin/phoneuse-mcp; each action returns a screenshot and positioned text after the screen settles. A ready-made Claude Code skill lives at skill/SKILL.md, and docs/RECIPES.md documents which gestures work and which do not.

When the phone is locked, phoneuse unlock asks for approval through a browser banner and desktop notification before typing the saved passcode once; the passcode is stored in ~/.config/phoneuse/passcode readable only by you.

Configuration and limits

Optional settings in ~/.config/phoneuse/config.toml include the Bluetooth/AirPlay device name, screen_points for non-tested iPhone screen sizes, the GStreamer decoder, mirror window width, and web_port. After changing name, rerun phoneuse install. The browser mirror listens on localhost only.

The README labels the project a quickly built technology demo for one specific setup, and warns that other setups will likely need fixes and that things may break without notice. The tested iPhone model and Linux stack should be treated as the supported baseline rather than a guarantee for other hardware or compositors. It is released under MIT.

HotRepo's take

On its first day in HotRepo's new-project list (2026-11-07, Python), phoneuse recorded 102 stars and 9 forks from 102 stars gained, but no all-language daily rank is recorded. With a single snapshot and no discussion threads, there is not enough history to say anything about its trajectory; the observational value here is the pitch itself: combining an unmodified iPhone, AirPlay mirroring and Bluetooth HID into a scriptable, agent-accessible remote-control surface without jailbreaking or extra apps.