Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,2 +1,10 @@
# Auto detect text files and perform LF normalization
* text=auto
# Unix executes this file by its shebang. Codex resolves the .cmd sibling on Windows.
apps/codex-plugin/scripts/launch-mcp text eol=lf
# Source bytes used to verify the checked-in Android collectors.
packages/native/android-cpu/collector.c text eol=lf
packages/native/android-fps/collector.cpp text eol=lf
packages/native/android-fps/perfetto/perfetto.* text eol=lf
packages/native/telemetry/telemetry.[ch] text eol=lf
tooling/native-telemetry.mjs text eol=lf
37 changes: 33 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,18 @@ env:

jobs:
unit:
name: Unit tests
runs-on: ubuntu-latest
name: ${{ matrix.name }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-latest
name: Unit tests
- os: windows-latest
name: Windows Android and package
- os: macos-latest
name: macOS Android and launcher
timeout-minutes: 20
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
Expand All @@ -42,8 +52,27 @@ jobs:
npm run vendor:agent-device
npm run vendor:serve-emu

# macOS-only paths skip themselves here; the release build runs the full suite on macOS.
- run: npm test
# The release workflow also runs the full suite on a Mac with Xcode and native helpers.
- if: runner.os == 'Linux'
run: npm test
- if: runner.os != 'Linux'
name: Android, source analysis, and launcher regressions
run: >
node --test
apps/codex-plugin/test/mcp-launch.test.ts apps/codex-plugin/test/plugin-updates.test.ts
packages/core/test/agent-device-runtime.test.ts
packages/core/test/android-sdk.test.ts packages/core/test/android.test.ts packages/core/test/android-emulator.test.ts
packages/core/test/app-storage.test.ts packages/core/test/testing-run.test.ts packages/core/test/windows-adb-trace.test.ts
packages/core/test/app-flow-presentations-bindings.test.ts packages/core/test/app-flow-typescript-runtime.test.ts
packages/runtimes/test/serve-emu-node.test.ts packages/ui/test/simulator-panel.test.ts packages/ui/test/testing-panel.test.ts
- if: runner.os == 'Windows'
run: npm run build
- if: runner.os == 'Windows'
run: npm run package
- if: runner.os == 'Windows'
run: npm run test:package
env:
MOBILE_DEV_TELEMETRY: 'off'
- run: npm run typecheck:telemetry

# Codex and Claude ship from main. Add mac here once it ships.
Expand Down
43 changes: 29 additions & 14 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,10 @@ keep it. Restart the server from **View › Restart Server** (⇧⌘R).

## Development requirements

- An Apple Silicon Mac with Xcode 27 and Swift 6.4 or later selected as the active
developer tools, plus an installed iOS simulator runtime.
- For Apple helpers and release builds, an Apple Silicon Mac with Xcode 27, Swift 6.4 or later selected as the active developer tools, and an installed iOS simulator runtime. Windows development builds use the checked-in Android collectors.
- Node.js 22.19 or later, npm, Git, and network access to fetch pinned dependencies.
- Rust and Cargo for the iOS native helpers. The release workflow uses Rust 1.98.1.
- CMake, Ninja, pkg-config, OpenSSL 3, Autoconf, Automake, and Libtool for native
builds. With Homebrew, install them using:
- For the iOS native helpers, Rust and Cargo. The release workflow uses Rust 1.98.1.
- CMake, Ninja, pkg-config, OpenSSL 3, Autoconf, Automake, and Libtool for rebuilding native helpers. With Homebrew, install them using:

```sh
brew install cmake ninja pkgconf openssl@3 autoconf automake libtool
Expand All @@ -110,8 +108,26 @@ titles for squash merges. Git-generated merge messages are exempt. Existing
history does not need rewriting. Make the `commitlint` check required in the
repository's branch rules to block merging a failed check.

From the repository root, prepare the JavaScript runtimes and native helpers,
then build and verify the package:
For a local Windows build, install the Android SDK platform-tools and emulator. Set
`ANDROID_HOME` if the SDK is outside `%LOCALAPPDATA%\Android\Sdk`. In PowerShell, run
the following from the repository root.

```powershell
npm ci
npm run vendor:agent-device
npm run vendor:serve-emu
npm run build
npm run package
$env:MOBILE_DEV_TELEMETRY = 'off'
npm run test:package
```

This produces a local marketplace under `release/marketplace` and
`release/mobile-dev-<version>-windows.zip`. To test installation with the Codex CLI,
run `npm run test:codex-plugin`.

For the full macOS build, prepare the JavaScript runtimes and native helpers from
the repository root.

```sh
npm ci
Expand All @@ -132,7 +148,7 @@ npm run test:codex-plugin
npm run check:mcp-budget
```

Native rebuilds are required on a fresh checkout. Repeat the affected rebuild when
The full macOS build requires native rebuilds on a fresh checkout. Repeat the affected rebuild when
changing native code or shared native telemetry; the build validates source and
binary hashes. For UI or server edits with unchanged native sources, run the build,
relevant checks, and packaging steps again.
Expand All @@ -143,11 +159,11 @@ relevant checks, and packaging steps again.

agent-device is held at 0.21.33 in the weekly dependency updater. Versions 0.21.34 and 0.21.35 reject iOS input when an obsolete Xcode selection link points at a deleted installation, even when `xcode-select -p` and `xcrun` resolve the installed Xcode. See [upstream #3995](https://github.com/callstack/agent-device/pull/3995). Verify that case before raising the pin and removing the updater hold.

`build` also bundles JavaScript and CSS with esbuild and copies Baguette into `dist/baguette`. It does not run TypeScript, lint, Biome, visual checks, or React Doctor.
`build` also bundles JavaScript and CSS with esbuild and includes Baguette in macOS builds under `dist/baguette`. It does not run TypeScript, lint, Biome, visual checks, or React Doctor.

`package` copies built files into `release/marketplace/plugins/mobile-dev` and creates the ZIP. It includes agent-device's runtime `node_modules`, licenses, and Apple runner source. The Codex compatibility manifest lives at `apps/codex-plugin/.codex-plugin/plugin.json` and declares `.mcp.json`. The MCP entry invokes `apps/codex-plugin/scripts/launch-mcp.sh` (`scripts/launch-mcp.sh` inside the package) through `/bin/sh` and explicitly forwards `HOME` and the telemetry settings. The launcher directly executes Codex's bundled Node at `$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node`. `npm start` uses the same launcher. The `build-codex-native-plugins` skill in `.agents/skills` helps agents working on this repository and is not shipped.
`package` copies built files into `release/marketplace/plugins/mobile-dev` and creates the ZIP. It includes agent-device's runtime `node_modules`, licenses, and Apple runner source. The Codex compatibility manifest lives at `apps/codex-plugin/.codex-plugin/plugin.json` and declares `.mcp.json`. The MCP entry runs `./scripts/launch-mcp` from the plugin directory. Unix uses the executable shell script and Windows resolves its `.cmd` sibling. Both launch the Node runtime in the Codex cache under the user profile. The manifest forwards the profile, Android SDK and telemetry settings. For a development build, `npm start` runs the built server with the Node executable on PATH. The `build-codex-native-plugins` skill in `.agents/skills` helps agents working on this repository and is not shipped.

`test` checks MCP contracts, frame reads, input validation, and capture cleanup against a local fixture, plus runtime selection and argument forwarding with Node absent from PATH or another Node present. `test:package` copies the release package into a temporary directory and uses its actual MCP launch configuration with a system-only PATH. The smoke-test caller supplies an isolated home with the Codex runtime cache layout and its test Node executable; the MCP process has a system-only PATH. Run these checks with the Codex bundled Node executable to verify the packaged runtime. It checks native addon loading, sidebar/chat entrypoints, UI resources, and telemetry attribution, starts bundled Baguette, reads the real device list, and checks shutdown. It does not boot or change a simulator. Run it on an Apple Silicon Mac with Xcode.
`test` checks MCP contracts, frame reads, input validation, and capture cleanup against a local fixture, plus runtime selection and argument forwarding with Node absent from PATH or another Node present. `test:package` copies the release package into a temporary directory and uses its actual MCP launch configuration with a system-only PATH. The test creates an isolated Codex cache using the Node executable running the test. It checks sidebar and chat entrypoints, resources, telemetry attribution or opt-out, and the bundled device runtime. On an Apple Silicon Mac with Xcode, it also loads the iOS native addon, starts Baguette, lists simulators and verifies shutdown.

`test:codex-plugin` requires the Codex CLI (`codex` on PATH or `CODEX_CLI_PATH`). It installs the package into a temporary Codex profile, asks Codex to resolve the installed MCP configuration, then starts that exact command and working directory with no Node on MCP PATH. It checks the sidebar resource and telemetry opt-out without changing the user's plugins or devices. Pass an extracted ZIP directory to test the shipped artifact. The compatibility manifest uses `cwd: "."`; `${PLUGIN_ROOT}` is not expanded in this format and would become a nonexistent subdirectory of the installed cache.

Expand All @@ -159,8 +175,7 @@ The host installs a cache copy. After changing source, rebuild and package, then

## Host regression and visual tests

Pull requests run [CI](.github/workflows/ci.yml) on Linux: the unit tests (macOS-only paths
skip themselves), Codex and Claude regression jobs and a Codex visual regression job. The
Pull requests run Android, launcher and package checks on Windows. Linux CI runs the unit suite, the Codex and Claude host regressions and the Codex visual suite. See the [CI workflow](.github/workflows/ci.yml). The
`mac` regression project runs locally until that target ships. The host jobs need no Mac, simulator or host app. `build:hosts` builds
each target's real server and page without the native helpers, and Playwright drives
them in [`tooling/hosts`](tooling/hosts):
Expand Down Expand Up @@ -276,7 +291,7 @@ codex plugin add mobile-dev@mobile-dev-local

Open a new chat after installing, then open Mobile Dev from the sidebar.

`npm run package` writes the local ZIP to `release/mobile-dev-<version>-darwin-arm64.zip`. Install through the local marketplace above. The New Plugin archive dialog uploads to the workspace plugin service; it is a separate install route. This package has not gone through public directory review or publication.
`npm run package` writes the local ZIP to `release/mobile-dev-<version>-windows.zip` on Windows and `release/mobile-dev-<version>-darwin-arm64.zip` on Apple Silicon Macs. Install through the local marketplace above. The New Plugin archive dialog uploads to the workspace plugin service; it is a separate install route. This package has not gone through public directory review or publication.

### Claude Desktop local development

Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ See [storage privacy and review checks](docs/storage-privacy.md).
**[Add Mobile Dev to Codex](https://chatgpt.com/plugins/plugins_6ac4c117f76881918d3676e851fa4005)**
from the plugin directory, then open a new chat.

On Windows, choose **Android** to connect an emulator or phone. The iOS tab stays visible for future cloud devices. [Set up Android on Windows](docs/devices.md#android-on-windows)

To install the prebuilt plugin from this repository instead, see
[Install from the GitHub marketplace](CONTRIBUTING.md#install-from-the-github-marketplace).

Expand Down Expand Up @@ -185,7 +187,7 @@ open "release/mac/Mobile Dev.app"

## Requirements

Mobile Dev runs on an Apple Silicon Mac. In Codex desktop, the prebuilt plugin
Codex desktop supports Android on Windows and Apple Silicon Macs. Local iOS devices require an Apple Silicon Mac. The prebuilt Codex plugin
uses Codex's bundled Node runtime from its workspace dependency cache; the Claude
Desktop bundle uses Claude's Node runtime, the Cursor plugin uses Node.js from
`PATH`, and the Mac app bundles its own. Install the tools for the platforms you use:
Expand All @@ -194,12 +196,12 @@ Desktop bundle uses Claude's Node runtime, the Cursor plugin uses Node.js from
| --- | --- |
| iOS simulators | Xcode 26 or later with an installed simulator runtime. |
| Physical iPhones and iPads | Xcode 27 or later, a paired device with Developer Mode enabled, and USB or Wi-Fi connectivity. Screen mirroring requires HEVC WebCodecs support in the host. |
| Android | Android SDK platform-tools and emulator, and an AVD or a physical device with authorized USB or wireless debugging. Screen streaming requires H.264 WebCodecs support in the host. |
| Android | Android SDK Platform-Tools for an authorized USB or wireless device. For an AVD, also install Android Emulator and a system image. Screen streaming requires H.264 WebCodecs support in the host. |
| Metro logs and React Native inspection | An existing local Metro server with a compatible app inspector target. |
| Physical iOS CPU and memory | iOS 17.4 or later, a running development-signed app with `get-task-allow`, a mounted developer disk image, and Xcode/LLDB detached. |
| Display FPS | Android 12 or later with FrameTimeline support, or a physical iOS device running iOS 17.4 or later. iOS simulators do not support Display FPS. |
| Testing Studio | A booted iOS simulator or Android emulator, plus an existing e2e project with its dependencies installed and a target bundle ID in `e2e.config.*`. |
| Profile analysis | The TraceSift CLI installed with `npm install -g @callstack/tracesift`, initialized once with `tracesift init`, and found on `PATH` or through `TRACE_SIFT_COMMAND`. |
| TraceSift profile analysis (macOS or Linux) | The TraceSift CLI installed with `npm install -g @callstack/tracesift`, initialized once with `tracesift init`, and found on `PATH` or through `TRACE_SIFT_COMMAND`. |

Simulator tools use the full Xcode installation selected by `xcode-select` (or
`DEVELOPER_DIR`), including its Swift compatibility libraries. Custom Xcode names
Expand All @@ -216,7 +218,7 @@ open Mobile Dev from the sidebar; in Cursor, ask **"Open Mobile Dev"** in an age
Pick a device from the toolbar; selecting a stopped simulator or AVD
boots it. Use the iOS and Android toggles to show either platform or both.

Click an iOS simulator or Android screen to focus it, then press **Command-V** to
Click an iOS simulator or Android screen to focus it, then press **Ctrl+V** on Windows or **Command-V** on macOS to
paste text into the device. Paste accepts up to 4,096 printable US-ASCII characters;
line breaks and other characters show a notice without sending partial text.

Expand Down
2 changes: 1 addition & 1 deletion SUPPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ reports, or privacy requests.

Use "Mobile Dev support" in the email subject, or open a
[GitHub issue](https://github.com/callstackincubator/mobile-dev/issues).
Include the plugin and host versions, macOS/device OS versions, the feature
Include the plugin and host app versions, the operating systems and versions of your computer and device, the feature
involved, expected and actual behavior, and minimal reproduction steps.

Review any log or screenshot before sharing it. Do not include passwords, API
Expand Down
6 changes: 3 additions & 3 deletions apps/codex-plugin/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "mobile-dev",
"description": "Keep a simulator beside the chat while building, running, or debugging iOS and Android apps. Stream devices, read native and Metro logs, analyze CPU and React profiles with TraceSift, render interactive CPU, memory, and FPS recordings, map your app's screens and navigation with App Flow, and control apps with Mobile Dev tools.",
"description": "Keep mobile devices beside the chat while building, running, or debugging iOS and Android apps. Stream devices, read native and Metro logs, analyze CPU and React profiles with TraceSift, render interactive CPU, memory, and FPS recordings, map your app's screens and navigation with App Flow, and control apps with Mobile Dev tools.",
"author": {
"name": "Callstack",
"email": "hello@callstack.com"
Expand Down Expand Up @@ -68,14 +68,14 @@
"demo_recording_url": "https://raw.githubusercontent.com/callstackincubator/mobile-dev/main/docs/review/media/mobile-dev-demo.mp4"
},
"publication": {
"release_notes": "Checks updates against the published plugin-store version and opens the store to update. Adds a version-gated migration that verifies the enabled store installation before removing the GitHub plugin and marketplace, preserving local recordings and saved data. Reduces Sentry reporting volume and excludes expected failures."
"release_notes": "Adds Android emulator and phone support on Windows, including screen streaming, element selection and sharing annotations with chat. Checks updates against the published plugin-store version and opens the store to update. Adds a version-gated migration that verifies the enabled store installation before removing the GitHub plugin and marketplace, preserving local recordings and saved data. Reduces Sentry reporting volume and excludes expected failures."
}
}
},
"interface": {
"displayName": "Mobile Dev",
"shortDescription": "Devices, logs, and performance",
"longDescription": "Keep an iOS simulator or Android device beside your chat while building, running, or debugging Expo, React Native, SwiftUI, and other mobile apps. Monitor native CPU, memory, and device-wide Display FPS, analyze local CPU and React profiles with TraceSift cards, render interactive performance recordings in chat, read native and Metro logs, map your app's screens and navigation with App Flow, and inspect and control apps with Mobile Dev tools.",
"longDescription": "Keep mobile devices beside your chat while building, running, or debugging Expo, React Native, SwiftUI, and other mobile apps. Monitor native CPU, memory, and device-wide Display FPS, analyze local CPU and React profiles with TraceSift cards, render interactive performance recordings in chat, read native and Metro logs, map your app's screens and navigation with App Flow, and inspect and control apps with Mobile Dev tools.",
"developerName": "Callstack",
"websiteURL": "https://github.com/callstackincubator/mobile-dev",
"supportURL": "https://github.com/callstackincubator/mobile-dev/blob/main/SUPPORT.md",
Expand Down
9 changes: 7 additions & 2 deletions apps/codex-plugin/.mcp.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
{
"mcpServers": {
"mobile-dev": {
"command": "/bin/sh",
"command": "./scripts/launch-mcp",
"args": [
"./scripts/launch-mcp.sh",
"./dist/server.mjs"
],
"cwd": ".",
"env_vars": [
"HOME",
"USERPROFILE",
"LOCALAPPDATA",
"ANDROID_HOME",
"ANDROID_SDK_ROOT",
"ANDROID_AVD_HOME",
"ANDROID_USER_HOME",
"CODEX_HOME",
"DEVELOPER_DIR",
"TRACE_SIFT_HOME",
Expand Down
7 changes: 7 additions & 0 deletions apps/codex-plugin/scripts/launch-mcp.cmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
@echo off
setlocal
set "entry=%~f1"
rem A running Windows process locks its working directory. Release the plugin cache
rem before starting the server so Codex can update or uninstall this version.
cd /d "%USERPROFILE%" || exit /b 1
"%USERPROFILE%\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe" "%entry%" & exit /b
Loading
Loading