blackpaw-studio/xcode-remote

xcode-remote is a command line tool built to help an AI coding agent build and test iOS or Mac apps even when the agent is running on a headless machine with no screen. Normally a coding agent working on a build server cannot see whether the app it just compiled actually opens correctly, but xcode-remote builds the project on that build machine, copies the finished app over SSH to a separate Mac you are actually watching, launches it there, and then reports back a single structured result showing whether the build succeeded, whether the app launched, recent logs, and any crash details. Setting it up requires a Mac with Xcode installed to do the building, and a second Mac reachable over SSH with key based login already configured, to actually run the app. For testing on a real iPhone rather than the simulator, the phone needs to already be paired to that second Mac with Developer Mode turned on. You install the tool with either the uv or pipx Python package installers, then configure a small settings file for your laptop connection details and a separate per project settings file for things like the app's scheme name. Once configured, running one command builds the app, ships it to the target machine, launches it, and prints a JSON object describing what happened, which an AI agent can read and act on directly, for example by fixing a reported compiler error and trying again, or by inspecting a crash signal. Building for a real iPhone from a machine with no interactive login session breaks Xcode's usual automatic code signing, so the tool works around this by only injecting the development team setting itself, while your own project must declare its full manual signing configuration. The project also ships an installable skill file that teaches AI coding assistants such as Claude Code or Cursor exactly when and how to call this tool and how to interpret its JSON output. The project is released under the MIT license.