simfleet

https://github.com/user-attachments/assets/96422e28-f5a8-400b-b8d9-9a2530fa1eda

Running several branches of a React Native app at once usually means five simulators eating 4 GB each, Metro servers fighting over port 8081, native rebuilds every time you switch environments, and coding agents stepping on each other's devices. simfleet turns that into one managed fleet:

• Always slim. Every iOS simulator is trimmed with SimSlim (about 3.8 GB → 1.3 GB) and every Android emulator with avdslim (-lowram, host GPU, ~45 background packages disabled). Devices booted any other way (Xcode, Android Studio, simctl) are slimmed automatically.
• One live dashboard. Every booted device streams into a browser wall you can drive directly: iOS over MJPEG, Android as hardware H.264 through scrcpy's device server with real touch down/move/up (15–80 ms input-to-frame on an M-series Mac).
• Lanes, not port juggling. A lane is one worktree on one device with one leased Metro port from the environment's range. Lanes refuse to steal a device, worktree, or port.
• Native builds once. An Expo buildCacheProvider fingerprints native inputs (JS excluded) and single-flights misses, so ten agents on JS-only branches share one build, and switching staging/production never rebuilds native.
• Know which agent is where. Every CLI call from a Claude Code or Codex session is attributed to the device it touches; sessions can claim devices. A menu-bar icon shows who is driving what.

Requirements

• macOS, Bun ≥ 1.1
• iOS: Xcode, plus brew install mobai-app/tap/simslim baguette watchman
• Android: the Android SDK (platform-tools and emulator, via ANDROID_HOME or ~/Library/Android/sdk), plus brew tap kdbhalala/avdslim https://github.com/kdbhalala/avdslim.git && brew install avdslim scrcpy

Each platform is optional; simfleet status and the dashboard report what is missing.

Quick start

bun add -g simfleet               # or run any command with: bunx simfleet <command>
cd path/to/your-app
simfleet init                     # writes .sim-fleet/project.json; set your real bundle IDs/schemes
simfleet skill install            # optional: teach Claude Code and Codex to use the fleet
simfleet serve                    # dashboard + API on http://127.0.0.1:8790 and the menu-bar icon

Then, in another terminal (or from an agent):

simfleet sim list                                     # iOS simulators with slim state
simfleet sim boot <udid>                              # boots slim and verifies it
simfleet lane start "$PWD" <udid> development debug   # leases a Metro port, starts Metro
simfleet lane launch <lane-id>                        # opens the dev client at that Metro

Android works the same way with AVD names:

simfleet emu boot Pixel_8_API_35                      # headless, 2 GB guest RAM, slimmed
simfleet lane start "$PWD" Pixel_8_API_35             # adb reverse + dev-client deep link on launch

Using the dashboard

Open http://127.0.0.1:8790 (or click the menu-bar icon). The wall shows every simulator and emulator with state, memory footprint, slim status, lane, and attached agents. Open a device to control it: click to tap, drag to swipe, scroll to scroll, press Enter to send keystrokes and Esc to release. The inspector has lifecycle actions, hardware buttons, text entry, deep links, and lane controls. The page follows the system light/dark theme, is keyboard and screen-reader accessible, and reloads itself when the dashboard is upgraded.

The menu-bar icon starts with simfleet serve (disable with --no-tray or SIM_FLEET_TRAY=0) or on its own with simfleet tray. Left-click opens the dashboard; right-click lists devices and their agents. The helper is compiled from tray/SimFleetTray.swift with swiftc on first use and cached in ~/Library/Caches/simfleet.

CLI

Run simfleet help for everything. The most used commands:

Every command is a thin client over the local HTTP API; GET /api/v1/capabilities describes it, and skills/simfleet/references/api.md documents it in full.

Agent skill

simfleet ships an agent skill that teaches Claude Code and Codex to use the fleet correctly: boot devices slim, claim what they hold, let lanes own ports, and prefer the JS-first path over native rebuilds.

simfleet skill install              # ~/.claude/skills/simfleet and ~/.codex/skills/simfleet
simfleet skill install --project    # ./.claude/skills and ./.codex/skills, to commit with your app
simfleet skill install --claude     # only Claude Code (or --codex for only Codex)

Re-run it after upgrading simfleet. The skill lives in skills/simfleet if you prefer to copy or adapt it; list it under worktrees.skills in project.json so new worktrees link it too.

Attribution. The CLI reads CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID and sends it with every device request, so the dashboard shows which session touched which device (touches expire after 30 minutes). Other agents can set SIMFLEET_AGENT and SIMFLEET_SESSION_ID, or send the x-simfleet-agent / x-simfleet-session headers. simfleet claim attaches a session until it releases the device or the Claude session exits.

To make every agent boot slim devices by default even outside simfleet projects, add a line like this to ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md:

Boot iOS simulators and Android emulators slim unless I explicitly ask for stock: use
`simfleet sim boot` / `simfleet emu boot` in simfleet projects, otherwise `simslim on <udid>` and
`avdslim start <avd>`.

Always slim

sim boot and emu boot apply and verify the slim profile, and simfleet serve checks every 15 seconds for devices booted another way:

• Android: a running emulator without avdslim state is slimmed in place (no reboot).
• iOS: SimSlim needs a reboot, so a simulator is slimmed automatically only within its first 4 minutes. An older unslimmed simulator is reported as needs-reboot (and shown as "Unslimmed" with a Slim button) rather than being interrupted mid-test.

Opt a device out with --stock on boot, or with restore; slim opts it back in. Disable auto-slim entirely with SIM_FLEET_AUTO_SLIM=0 or "autoSlim": false.

Project configuration

simfleet runs against the nearest directory containing .sim-fleet/project.json and resolves linked Git worktrees to their main checkout (override with SIM_FLEET_PROJECT_ROOT).

{
  "schemaVersion": 1,
  "projectName": "my-app",
  "nativeShells": {
    "debug":   { "appName": "My App Dev", "bundleId": "com.example.app.dev", "scheme": "myapp-dev" },
    "release": { "appName": "My App",     "bundleId": "com.example.app",     "scheme": "myapp",
                 "androidPackage": "com.example.app" }          // optional; defaults to bundleId
  },
  "environments": {                                             // non-overlapping Metro port ranges
    "development": { "envFile": ".env.development", "portRange": [8100, 8199] },
    "staging":     { "portRange": [8200, 8299] },
    "preprod":     { "portRange": [8300, 8399] },
    "production":  { "portRange": [8400, 8499] }
  },
  // Everything below is optional.
  "nativeAuth": { "pro