The Problem

Standard mobile development requires significant context switching between terminals to manage Metro bundling, Xcode builds, and Gradle tasks, while simultaneously launching and streaming simulator or emulator output. This fragmentation slows the feedback loop, particularly when integrating an AI coding agent into the workflow.

What This Does

mobilecode is a fork of opencode tailored for mobile projects. It detects iOS and Android projects up to two directory levels deep and unifies the build and preview lifecycle. The core mechanism is the "device pane," which opens alongside the conversation session. It starts serve-sim or serve-avd to stream the simulator or emulator directly into the app interface.

Key capabilities include:

  • Reactive Play button: Builds the native project (iOS via xcodebuild, Android via ./gradlew :<module>:assembleDebug), installs it, and launches it on the running simulator or emulator.
  • Shared resource management: The simulator, emulator, and Metro port are shared. Starting a new project stops any currently running project's apps first.
  • Agent-driven builds: The device_run tool allows the agent to build and launch the app, read the build error and log tail, and fix failures iteratively without manual log pasting.
  • Expo integration: npx serve-avd and expo prebuild are used to generate native projects when needed.

The repository structure reflects this focus: packages/ contains the core logic (6394 files), while github/ handles the server and API layer. Configuration and CI files are distributed across .github/workflows/ and root package.json files.

How It Is Wired

Execution flows from the HTTP API into the build orchestration. The entry points indicated by the structure are github/index.ts (server routing) and packages/app/ (core logic).

  • API Entry: Requests to POST /api/device-preview/start or POST /api/device-preview/run trigger the build sequence.
  • Build Orchestration: The system detects the project type (Xcode workspace, Gradle project, or Expo app) and invokes the appropriate subprocess. iOS builds use xcodebuild against the first shared scheme, followed by simctl install and simctl launch. Android builds execute ./gradlew :<module>:assembleDebug, then adb install -r -g with an explicit launch intent.
  • Device Pane: The tooling starts the Metro server and streams the visual output into an embedded pane within the app interface. Controls for Start, Stop, Reload, and Open in browser are available.
  • Port/State Sharing: A single Metro server serves both iOS and Android platforms. The system enforces that only one project runs at a time, managing the lifecycle state to prevent port conflicts.

Files directly responsible for these effects include the workflow definitions in .github/workflows/ (which handle CI and container builds) and the package.json files located at the root and within packages/, which define the Node.js dependencies and scripts the tooling relies on.

How To Use It

Setup is grounded by the presence of package.json files at the root and inside packages/cli and packages/app, indicating a Node.js-based installation and build process.

  • Setup: The repository uses Docker (evidenced by .dockerignore and workflow files like containers.yml). Install dependencies using the package manager defined in the root or packages/ package.json files.
  • Configuration: The README excerpt specifies requirements: macOS with Xcode for iOS (requiring Node 20 or newer) and the Android SDK platform-tools with at least one AVD for Android. The project package name is read from the built APK using aapt2 when SDK build-tools are installed.
  • Running it: Start a session in a directory containing an iOS or Android project. The device pane will open automatically. Use the Play control in the session titlebar or invoke the API endpoints directly: ``bash # Example API invocation (endpoint structure based on repo excerpt) POST /api/device-preview/start { "platform": "ios" } ` Consult the README for the exact npx commands demonstrated in the demo GIFs, as the installation sequence involves starting Metro, building natives, and connecting the emulator via adb reverse`.

Real-World Use

A developer working on a React Native application opens a session in the project root. The device pane appears instantly. Instead of toggling between a terminal and Xcode, they click Play. MobileCode detects the Xcode project, runs the build, installs the app in the embedded simulator pane, and the Metro server starts. The developer sees the app render live next to their AI conversation. If a build error occurs, the device_run tool captures the log tail, allowing the agent to propose a fix without the developer leaving the interface.

Code Health & Issues

  • Low/Risk - Non-reproducible builds: Dependencies are declared without a lockfile in artifacts/glm52-rise-video/package.json. This can lead to varying build outputs across environments if dependency versions shift.

Beyond the measured finding, the repository shows a healthy SDLC signal: 1014 test files and 706 documentation files are present. The presence of over 40 GitHub Actions workflow files indicates a mature CI/CD pipeline focused on testing, publishing, and compliance. Docker is configured and used for containerized execution.

The Bottom Line

MobileCode successfully bridges the gap between AI coding agents and the complex, multi-step mobile build pipeline. It eliminates the manual context switching typically required to preview iOS and Android apps. The primary practical concern is the missing lockfile in a sample project, which should be addressed to ensure build reproducibility. It is well-suited for teams or agents that need to build, install, and preview mobile projects within a unified session environment.