# simfleet

> One control plane for parallel React Native work on macOS: slimmed iOS simulators and Android emulators, a live dashboard, leased Metro ports, a shared native build cache, and per-agent device attribution.

This document contains the full content of all documentation pages for AI consumption.

---

## Agent skill

**URL:** https://entropyconquers.github.io/simfleet/docs/agent-skill
**Description:** Teach Claude Code and Codex to use the fleet safely.

simfleet ships an [agent skill](https://github.com/entropyconquers/simfleet/tree/main/skills/simfleet): a `SKILL.md` plus a full API reference that coding agents load when a task involves simulators, emulators, Metro, or running a branch. It encodes the rules that keep many agents from stepping on each other.

## Install

```bash
simfleet skill install              # ~/.claude/skills/simfleet and ~/.codex/skills/simfleet
simfleet skill install --project    # ./.claude/skills and ./.codex/skills — commit it with your app
simfleet skill install --claude     # only Claude Code
simfleet skill install --codex      # only Codex
```

Re-run it after upgrading simfleet. To have new worktrees link the skill automatically, list it in the project config:

```json
"worktrees": { "skills": [".claude/skills/simfleet"] }
```

## What it teaches

- **Boot slim.** Use `simfleet sim boot` / `emu boot`, never `simctl`, Xcode, or another tool's boot command. Stock only when you ask for it.
- **Claim what you hold.** `simfleet claim` before a long task, `release` after, and never drive a device another live session has claimed.
- **Lanes own ports.** No hand-picked ports, no killing unknown Metro processes.
- **JS-first.** Start a lane and launch; build natively only through `native plan` / `native ensure`.
- **Prove it.** Report the lane, device, environment, port, slim state, and whether the native build was reused, with UI evidence of the feature itself.

## Always-slim policy for every project

The skill applies inside simfleet projects. To make agents boot slim devices everywhere, add a policy to your global instructions — `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex:

```md title="~/.claude/CLAUDE.md"
## Simulators and emulators: always slim

Boot iOS simulators and Android emulators slim unless I explicitly ask for stock.
In projects with .sim-fleet/project.json use `simfleet sim boot` / `simfleet emu boot`.
Elsewhere use `simslim on <udid>` (iOS) and `avdslim start <avd>` / `avdslim on <serial>` (Android).
```

## Other agents

Any agent can use the fleet through the CLI or HTTP API. Set `SIMFLEET_AGENT` and `SIMFLEET_SESSION_ID` (or send `x-simfleet-agent` and `x-simfleet-session` headers) so its activity is attributed.

---

## Agent attribution

**URL:** https://entropyconquers.github.io/simfleet/docs/agents
**Description:** See which Claude Code or Codex session is driving each device, and let sessions claim devices.

When several agents share a Mac, the question "who is using this simulator?" matters. simfleet answers
it for every device.

## Automatic attribution

The `simfleet` CLI detects the session it runs in and sends it with every request:

| Agent | Detected from |
| --- | --- |
| Claude Code | `CLAUDE_CODE_SESSION_ID` |
| Codex | `CODEX_THREAD_ID` or `CODEX_SESSION_ID` |
| Anything else | `SIMFLEET_AGENT` and `SIMFLEET_SESSION_ID` |

A device request (tap, boot, screenshot, lane start, …) from a session records a **touch** on that device. Touches expire after 30 minutes without activity. A lane whose worktree matches an agent session's working directory is attributed to that session too.

## Claims

A claim makes ownership explicit and lasts until it is released, or until the Claude Code session exits:

```bash
simfleet claim <udid-or-avd> "reviewing the checkout flow"
simfleet release <udid-or-avd>
simfleet agents                      # live sessions and the devices attached to each
```

## Where you see it

- **Dashboard.** Each device tile shows its agents; the Agents view lists every live Claude Code and Codex session with its devices.
- **Menu bar.** Right-click the icon for a list of running devices and who is attached to each. Left-click opens the dashboard.
- **API.** `GET /api/v1/agents`. See [Agents](/docs/api-reference/agents).

## Session discovery

simfleet finds live sessions without any agent plugin: Claude Code sessions from `~/.claude/sessions` (checking that each process is alive), and Codex threads from its local state database (recently active ones).

---

## Always slim

**URL:** https://entropyconquers.github.io/simfleet/docs/always-slim
**Description:** Every simulator and emulator runs trimmed unless you explicitly ask for stock.

A stock iOS simulator runs about 200 processes and holds 3–6 GB. Most of that is Apple services a React
Native app never touches: Siri, Photos analysis, App Store, iCloud sync. Android images ship the same
kind of background weight. simfleet's rule is simple: **every device is slim unless someone explicitly
asks for stock.**

## What slimming does

  

## Auto-slim

While `simfleet serve` runs, it checks every 15 seconds for devices that are booted but not slim — for example, ones started from Xcode, Android Studio, `xcrun simctl boot`, or another tool.

| Platform | Behaviour |
| --- | --- |
| Android | Slimmed in place, no reboot. Typically takes about 5 seconds. |
| iOS, booted less than 4 minutes ago | Slimmed (this reboots it). |
| iOS, running longer | Reported as `needs-reboot` and shown as **Unslimmed** in the dashboard, with a Slim button. It is not rebooted automatically, because something may be mid-test on it. |

`status.autoSlim` lists what the loop is doing:

```json
{
  "enabled": true,
  "iosFreshBootSeconds": 240,
  "devices": [
    { "deviceId": "763B…", "platform": "ios", "status": "needs-reboot",
      "reason": "running unslimmed; slimming reboots it, so it is not interrupted automatically" }
  ]
}
```

Failed attempts back off for 10 minutes per device.

## Stock devices

Sometimes you need the full platform, for example to reproduce a bug with Apple Pay or Google services. Ask for it explicitly:

```bash
simfleet sim boot <udid> --stock
simfleet emu boot <avd> --stock
simfleet sim restore <udid>        # restore a running simulator to stock
simfleet emu restore <avd>
```

Each of these records an **opt-out** that auto-slim respects. `simfleet sim slim` or `emu slim` clears it again.

---

## Android emulators

**URL:** https://entropyconquers.github.io/simfleet/docs/android
**Description:** Boot, slim, stream, and drive Android emulators alongside your simulators.

Android devices are addressed by **AVD name** (for example `Pixel_8_API_35`). The `emulator-5554` style serial exists only while an emulator runs, so the fleet never uses it as an identity.

## Lifecycle

```bash
simfleet emu list                                   # AVDs, state, slim status, footprint, agents
simfleet emu boot <avd> [--window] [--cold] [--stock]
simfleet emu slim <avd>                              # re-slim a running emulator, no reboot
simfleet emu restore <avd>                           # stock packages (records an opt-out)
simfleet emu shutdown <avd>
simfleet emu tune <avd>                              # shut-down AVD only: low-memory config.ini
```

`boot` is headless by default (the dashboard is the screen); `--window` opens the emulator window. Boots are serialized so avdslim never races for a console port, and a boot returns only after the slim state is verified on the device.

## Inspect and drive

Coordinates are device pixels from the UIAutomator tree:

```bash
simfleet emu ui <avd> [x y]
simfleet emu tap <avd> <x> <y>
simfleet emu long-press <avd> <x> <y>
simfleet emu swipe <avd> <x1> <y1> <x2> <y2>
simfleet emu type <avd> "ascii text"
simfleet emu key <avd> Enter
simfleet emu button <avd> back|home|app-switcher|menu|lock|power|volume-up|volume-down
simfleet emu rotate <avd> landscape-left
simfleet emu open-url <avd> 'myapp://path'
simfleet emu dev-menu <avd>
simfleet emu screenshot <avd> /absolute/out.png
```

## Lanes

```bash
simfleet lane start "$PWD" <avd>
simfleet lane launch <lane-id>
```

The fleet leases a Metro port, runs `adb reverse` for it, and opens your dev client with the `expo-development-client` deep link for that port. It prefers your configured scheme, then the `exp+<slug>` scheme Expo registers. The development build must already be installed on the emulator; Android lanes are debug-only.

## Performance

- **Guest RAM.** simfleet boots with 2 GB (`SIM_FLEET_ANDROID_RAM_MB`). At 1.5 GB, Android 15 images swap hundreds of megabytes and input feels sluggish.
- **Live video.** Install `scrcpy`. The dashboard then streams H.264 and injects touch directly — typically 15–80 ms from input to frame on Apple silicon, versus about two seconds with screenshot polling.
- **Images.** Google APIs (non-Play) system images let avdslim disable the most packages.

---

## CLI

**URL:** https://entropyconquers.github.io/simfleet/docs/cli
**Description:** Every simfleet command.

The CLI is a thin client over the local API. It talks to `SIM_FLEET_URL` (default `http://127.0.0.1:8790`), prints JSON, and exits non-zero on errors. `simfleet help` prints the full usage.

## Server and setup

| Command | Description |
| --- | --- |
| `simfleet serve [--no-tray]` | Start the dashboard, API, auto-slim loop, and menu-bar icon |
| `simfleet tray` | Run only the menu-bar icon |
| `simfleet init` | Write a starter `.sim-fleet/project.json` |
| `simfleet skill install [--claude\|--codex] [--project]` | Install the agent skill |
| `simfleet version` | Print the version |

## Fleet state

| Command | Description |
| --- | --- |
| `simfleet status` | Host memory, worktrees, lanes, Metros, simulators, emulators, agents, auto-slim |
| `simfleet ports` | Environment port ranges and live leases |
| `simfleet agents` | Live Claude Code / Codex sessions and their devices |
| `simfleet claim <device> [note]` | Attach this agent session to a device |
| `simfleet release <device>` | Release a claim |

## iOS simulators

| Command | Description |
| --- | --- |
| `simfleet sim list` | Simulators with state, memory, and slim status |
| `simfleet sim creation-options` | Installed device types and runtimes |
| `simfleet sim create <name> <device-type-id> <runtime-id>` | Create a simulator (left shut down) |
| `simfleet sim boot <udid> [--stock]` | Boot slim (or stock) and verify |
| `simfleet sim slim\|restore\|shutdown\|open <udid>` | Lifecycle |
| `simfleet sim ui <udid> [x y]` | Accessibility tree, or hit-test a point |
| `simfleet sim tap <udid> <x> <y> [w h]` | Tap in points |
| `simfleet sim swipe <udid> <x1> <y1> <x2> <y2> [w h]` | Swipe |
| `simfleet sim type <udid> <text>` | Type text |
| `simfleet sim key <udid> <code> [modifier,…]` | Press a key (W3C `KeyboardEvent.code`) |
| `simfleet sim button <udid> <button>` | Hardware button |
| `simfleet sim rotate <udid> <orientation>` | Rotate |
| `simfleet sim open-url <udid> <url>` | Open a URL or deep link |
| `simfleet sim shake <udid>` | Shake gesture |

When `w h` are omitted the CLI reads the screen size from the device, so coordinates are correct on any iPhone or iPad.

## Android emulators

| Command | Description |
| --- | --- |
| `simfleet emu list` | AVDs with state, slim status, and footprint |
| `simfleet emu boot <avd> [--window] [--cold] [--stock]` | Boot (headless by default), slim, verify |
| `simfleet emu slim\|restore\|shutdown\|tune <avd>` | Lifecycle |
| `simfleet emu ui <avd> [x y]` | UIAutomator tree, or hit-test a point |
| `simfleet emu tap\|double-tap\|long-press <avd> <x> <y>` | Touch in device pixels |
| `simfleet emu swipe <avd> <x1> <y1> <x2> <y2>` | Swipe |
| `simfleet emu type <avd> <text>` | Type ASCII text |
| `simfleet emu key <avd> <code>` | Press a key |
| `simfleet emu button <avd> <button>` | `home`, `back`, `app-switcher`, `menu`, `lock`, `power`, `volume-up`, `volume-down` |
| `simfleet emu rotate <avd> <orientation>` | Rotate |
| `simfleet emu open-url <avd> <url>` | Open a URL or deep link |
| `simfleet emu dev-menu <avd>` | Open the React Native dev menu |
| `simfleet emu screenshot <avd> <out.png>` | Save a screenshot |

## Lanes, worktrees, and native builds

| Command | Description |
| --- | --- |
| `simfleet lane list` | Lanes with Metro health |
| `simfleet lane start <worktree> <device> [env] [mode] [port]` | Start a lane |
| `simfleet lane launch\|stop\|log <lane-id>` | Operate a lane |
| `simfleet lane open-url <lane-id> <url-or-path>` | Open a deep link with the lane's scheme |
| `simfleet worktree create <name> <branch> [start-point]` | Create a fleet-ready worktree |
| `simfleet native plan <worktree> <debug\|release> [udid]` | Fingerprint and cache status |
| `simfleet native ensure <worktree> <udid> <debug\|release>` | Build if needed, then install |

---

## Project configuration

**URL:** https://entropyconquers.github.io/simfleet/docs/configuration
**Description:** Every field of .sim-fleet/project.json.

simfleet runs against the nearest directory containing `.sim-fleet/project.json` and resolves linked worktrees to their main checkout. Override the project with `SIM_FLEET_PROJECT_ROOT`. `simfleet init` writes a starter file.

```jsonc title=".sim-fleet/project.json"
{
  "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" }
  },
  "environments": {
    "development": { "envFile": ".env.development", "portRange": [8100, 8199] },
    "staging":     { "portRange": [8200, 8299] },
    "preprod":     { "portRange": [8300, 8399] },
    "production":  { "portRange": [8400, 8499] }
  }
}
```

## Required

## Optional

---

## Dashboard

**URL:** https://entropyconquers.github.io/simfleet/docs/dashboard
**Description:** A live wall of every device, with direct control and lane management.

`simfleet serve` hosts the dashboard at [http://127.0.0.1:8790](http://127.0.0.1:8790). Click the menu-bar icon to open it in your default browser.

![The simfleet dashboard focused on a live Android emulator](/images/dashboard.png)

## Views

| View | Shows |
| --- | --- |
| **Devices** | Every simulator and emulator as a live tile: state, memory footprint, slim status, lane, and attached agents. Filter by platform, state, or name. |
| **Focus** | One device, large and controllable, with an inspector for lifecycle, hardware buttons, text entry, deep links, lane controls, and details. |
| **Agents** | Live Claude Code and Codex sessions and the devices each one is attached to. |
| **Host** | Memory and swap, Metro listeners, and the largest processes. |

## Controlling a device

Open a device and interact with its screen:

- **Click** to tap, **drag** to swipe, **scroll** to scroll.
- Press <kbd>Enter</kbd> to take control of the keyboard; keys and text go to the device. <kbd>Esc</kbd> releases it.
- Android devices take raw touch down/move/up over the video socket, so drags track the pointer. iOS input goes through Baguette.

## Streaming

| Platform | Transport |
| --- | --- |
| iOS | MJPEG frames over a WebSocket from Baguette. Tiles stream at a few frames per second; the focused device at 30 fps. |
| Android | H.264 from scrcpy's device server, decoded in the browser with WebCodecs. Frames are sent only when the screen changes. One encoder session is shared by every viewer. |

Tiles that scroll out of view pause their stream. If scrcpy or WebCodecs is unavailable, Android tiles fall back to polling screenshots.

## Keyboard shortcuts

Press <kbd>?</kbd> in the dashboard for the full list.

| Keys | Action |
| --- | --- |
| <kbd>1</kbd> <kbd>2</kbd> <kbd>3</kbd> | Devices, Agents, Host |
| <kbd>/</kbd> | Search devices |
| <kbd>n</kbd> | Start a lane |
| <kbd>t</kbd> | Cycle theme |
| Arrow keys, <kbd>Enter</kbd> | Move between tiles, open one |
| <kbd>[</kbd> <kbd>]</kbd> | Smaller or larger tiles |
| <kbd>Esc</kbd> | Close, release control, or go back |

## Menu-bar icon

The icon starts with `simfleet serve`; disable it with `--no-tray` or `SIM_FLEET_TRAY=0`, or run it alone with `simfleet tray`. Left-click opens the dashboard; right-click lists running devices and their agents. It is a small Swift helper compiled with `swiftc` on first use and cached in `~/Library/Caches/simfleet`.

---

## Environment variables

**URL:** https://entropyconquers.github.io/simfleet/docs/environment
**Description:** Runtime settings for the server, CLI, and tools.

| Variable | Default | Purpose |
| --- | --- | --- |
| `SIM_FLEET_UI_PORT` | `8790` | Dashboard and API port. The server always binds to `127.0.0.1`. |
| `SIM_FLEET_URL` | `http://127.0.0.1:8790` | Where the CLI, menu-bar icon, and dashboard dev server find the API |
| `SIM_FLEET_PROJECT_ROOT` | nearest `.sim-fleet` | Project to serve |
| `SIM_FLEET_TRAY` | `1` | `0` disables the menu-bar icon |
| `SIM_FLEET_AUTO_SLIM` | `1` | `0` disables auto-slim |
| `SIM_FLEET_ANDROID_RAM_MB` | `2048` | Guest RAM for emulator boots, unless `android.avdslimArgs` sets `--ram=` |
| `SIM_FLEET_METRO_WORKERS` | `1` | Metro `--max-workers` per lane |
| `SIM_FLEET_CONTROL_PORT` | `8421` | Port for the Baguette simulator transport |
| `ANDROID_HOME` | `~/Library/Android/sdk` | Android SDK location |
| `AVDSLIM_BIN` | `PATH` | avdslim binary |
| `SCRCPY_SERVER_PATH` | Homebrew's `scrcpy-server` | scrcpy device server used for live Android video |
| `SCRCPY_SERVER_VERSION` | from `scrcpy --version` | Must match the device server's version |

## Agent identity

| Variable | Set by | Purpose |
| --- | --- | --- |
| `CLAUDE_CODE_SESSION_ID` | Claude Code | Attributes CLI calls to the Claude session |
| `CODEX_THREAD_ID`, `CODEX_SESSION_ID` | Codex | Attributes CLI calls to the Codex thread |
| `SIMFLEET_AGENT`, `SIMFLEET_SESSION_ID` | You | Identity for any other agent; takes precedence |

---

## Introduction

**URL:** https://entropyconquers.github.io/simfleet/docs
**Description:** One control plane for parallel React Native work on macOS.

![Three iPhones running a demo app in front of a display showing the simfleet dashboard with fourteen slimmed simulators running at once](/images/hero.webp)

simfleet runs many React Native worktrees in parallel on **slimmed iOS simulators and Android emulators**.
It gives you one live browser dashboard, one CLI and HTTP API that agents can call, leased Metro ports,
a shared native build cache, and a record of which Claude Code or Codex session is driving each device.

  
  
  

## The problem

Working on several branches at once, whether you or a handful of coding agents, runs into the same walls:

- **Memory.** A stock iOS simulator holds about 3.8 GB; five of them and a few Metro servers exhaust a 32 GB Mac.
- **Ports.** Every Metro wants 8081. Collisions show up as the wrong bundle on the wrong device.
- **Rebuilds.** Switching environment or branch often triggers a native rebuild that has nothing to do with the change.
- **Contention.** Agents boot, tap, and shut down each other's devices because nothing says who owns what.

## What simfleet does

| | |
| --- | --- |
| **Always slim** | Simulators are trimmed with SimSlim (about 3.8 → 1.3 GB), emulators with avdslim (`-lowram`, host GPU, ~45 packages disabled). Strays booted by Xcode or Android Studio are slimmed automatically. |
| **Live dashboard** | Every device streams into one wall. iOS over MJPEG; Android as hardware H.264 with real touch, drag, scroll, and keys. |
| **Lanes** | One worktree + one device + one leased Metro port. Lanes refuse to steal anything. |
| **Native build cache** | Native inputs are fingerprinted (JS excluded) and misses are single-flighted, so parallel agents share one build. |
| **Agent attribution** | Every CLI call from Claude Code or Codex is attributed to the device it touches. Claims make ownership explicit, and a menu-bar icon shows it. |

---

## Installation

**URL:** https://entropyconquers.github.io/simfleet/docs/installation
**Description:** Requirements and host tools for iOS and Android.

## Requirements

- macOS (Apple silicon or Intel)
- [Bun](https://bun.sh) 1.1 or newer

```bash
bun add -g simfleet       # installs the `simfleet` command
simfleet version
```

You can also run any command without a global install: `bunx simfleet <command>`.

## iOS

Install Xcode and its command-line tools, then:

```bash
brew install mobai-app/tap/simslim baguette watchman
```

| Tool | Used for |
| --- | --- |
| [SimSlim](https://github.com/MobAI-App/simslim) | Disabling background services in each simulator |
| [Baguette](https://github.com/tddworks/baguette) | Streaming simulator frames and injecting input |
| [Watchman](https://facebook.github.io/watchman/) | Fast Metro file watching across many worktrees |

## Android

Install the Android SDK with platform-tools and the emulator (Android Studio does this), and make sure
`ANDROID_HOME` points at it or it lives in `~/Library/Android/sdk`. Then:

```bash
brew tap kdbhalala/avdslim https://github.com/kdbhalala/avdslim.git
brew install avdslim scrcpy
```

| Tool | Used for |
| --- | --- |
| [avdslim](https://github.com/kdbhalala/avdslim) | Low-memory emulator boots and disabling background packages |
| [scrcpy](https://github.com/Genymobile/scrcpy) | Its device server provides live H.264 video and direct touch in the dashboard |

## Verify

```bash
simfleet serve --no-tray &
simfleet status | head -40
```

`status` reports which host tools were found: `simSlim` for iOS, and `android.adbPath`, `android.emulatorPath`, and `android.avdslim` for Android.

## Upgrading

```bash
bun add -g simfleet@latest
simfleet skill install       # refresh the agent skill
```

Restart `simfleet serve`; open dashboard tabs reload themselves.

---

## Lanes and Metro ports

**URL:** https://entropyconquers.github.io/simfleet/docs/lanes
**Description:** One worktree, one device, one leased Metro port.

A **lane** is the unit of parallel work: one Git checkout running on one device, served by one Metro on
a port the fleet leased for it. Lanes are how five branches run side by side without a single port
collision.

## Port ranges

Each environment in `.sim-fleet/project.json` owns a non-overlapping range:

```json
"environments": {
  "development": { "portRange": [8100, 8199] },
  "staging":     { "portRange": [8200, 8299] },
  "preprod":     { "portRange": [8300, 8399] },
  "production":  { "portRange": [8400, 8499] }
}
```

`lane start` takes the next free port in the lane's range, starts Metro there from the worktree, and records the lease. Nothing else chooses ports, so two agents can never race for one. Inspect leases with:

```bash
simfleet ports
```

A debug lane can ask for a specific `preferredPort` inside its range; it is accepted only when free.

## Lifecycle

```bash
simfleet lane start <worktree> <device> [environment] [debug|release] [preferredPort]
simfleet lane launch <lane-id>        # waits up to 15 s for Metro health, then opens the app
simfleet lane open-url <lane-id> buy  # a path uses the lane's scheme; a full URL passes through
simfleet lane log <lane-id>           # Metro output
simfleet lane stop <lane-id>          # stops only the Metro process group this lane owns
```

Lane creation **fails instead of stealing**: a device, worktree, or port already in use by another lane is an error, not a takeover.

## Debug and release

| | Debug | Release |
| --- | --- | --- |
| JavaScript | Served by the lane's Metro | Embedded in the app bundle |
| Port | Leased | None |
| Fast Refresh | Yes | No |
| Android | Supported | Not yet |

Release lanes copy the cached release build and re-bundle it with the lane's environment, so they need no Metro and use less memory.

## Android lanes

Android lanes work the same way with an AVD name in place of a UDID. On launch the fleet runs `adb reverse tcp:<port> tcp:<port>` so the emulator reaches Metro on localhost, then opens your dev client with its `expo-development-client` deep link. The dev client must already be installed on the emulator.

## Environments are JavaScript

Switching a lane between staging and production changes environment variables for Metro and the JS bundle only. It never changes the bundle identifier and never triggers a native build. See [Native builds](/docs/native-builds).

---

## Native builds

**URL:** https://entropyconquers.github.io/simfleet/docs/native-builds
**Description:** Fingerprinted, single-flight native builds shared by every worktree and agent.

Most branches only change JavaScript. simfleet makes sure those branches reuse an existing native build,
and that when a native build *is* needed, it happens exactly once no matter how many agents ask.

## How it works

1. **Fingerprint.** simfleet hashes the native inputs of a worktree and excludes application JavaScript: `app.config.js`/`app.json`, dependency declarations in `package.json` (scripts and metadata are ignored), the lockfile, `react-native.config.js`, the `plugins`, `patches`, and `firebase` directories, plus any `nativeFingerprint` paths you declare. The platform, build configuration, CPU architecture, and Xcode version are part of the hash. From the project config only `projectName`, `nativeAuth`, and `nativeShells` count, so changing ports or Metro env never invalidates a build.
2. **Look up.** The fingerprint names a cached `.app` in `~/Library/Caches/<cacheDirectoryName>/native`.
3. **Single-flight.** On a miss, the first caller builds; every concurrent caller waits for that job and reuses the result.

```bash
simfleet native plan <worktree> debug <udid>      # fingerprint, hit/miss, installed state — builds nothing
simfleet native ensure <worktree> <udid> debug    # build if needed, then install
```

`plan` also reports whether the installed bundle identifier is declared in `nativeAuth.allowedAppIdentifiers`, so an auth provider that validates app identifiers never sees an unexpected one.

## With Expo

simfleet ships an Expo [build cache provider](https://docs.expo.dev/guides/cache-builds-remotely/), so `expo run:ios` also reuses fleet builds:

```bash
bun add -d simfleet
```

```js title="app.config.js"
module.exports = {
  expo: {
    experiments: {
      buildCacheProvider: { plugin: require.resolve("simfleet/build-cache") },
    },
  },
};
```

## When to rebuild

Rebuild only when native inputs changed: pods, native code, config plugins, entitlements, build settings, or a dependency with native code. `native plan` tells you: a JS-only branch reports the same fingerprint as `main` and a cache hit.

## Identity model

Bundle identifiers are **stable native identities**, not worktree identities. Every worktree installs the same debug app; isolation comes from each lane having its own device and Metro port. This keeps auth providers, push entitlements, and Firebase configs working without per-branch registrations.

---

## Quickstart

**URL:** https://entropyconquers.github.io/simfleet/docs/quickstart
**Description:** Install simfleet, describe your app, and run a worktree on a slim device.

## Next

- Run a second worktree on another device with another `lane start`: no port juggling.
- Open a device in the dashboard and control it directly.
- Read [Native builds](/docs/native-builds) before your first native change.

---

## Troubleshooting

**URL:** https://entropyconquers.github.io/simfleet/docs/troubleshooting
**Description:** Common problems and how to fix them.

Still stuck? [Open an issue](https://github.com/entropyconquers/simfleet/issues/new/choose) with `simfleet version`, `sw_vers`, and the relevant `simfleet serve` output.

---

## Worktrees

**URL:** https://entropyconquers.github.io/simfleet/docs/worktrees
**Description:** Create Git worktrees that are ready for the fleet in one command.

Lanes run existing checkouts — any Git worktree of your project works. When you want a fresh one, let the fleet create it so it arrives ready to run:

```bash
simfleet worktree create <name> <branch> [start-point]
```

The name must be lowercase letters, digits, and hyphens; it becomes the suffix of a sibling directory next to your main checkout. The command prints the absolute path, which is the root to edit in.

## What preparation does

Configured under `worktrees` in `.sim-fleet/project.json`:

| Field | Effect |
| --- | --- |
| `sharedPaths` | Symlinked from the main checkout (default `.sim-fleet` and `node_modules`), so a new worktree does not reinstall dependencies. |
| `overlayFiles` | Fleet-specific files (for example `metro.config.js`) applied as a patch against `baseRef`, so the branch keeps its own content. A file that cannot be merged is skipped and reported. |
| `removedFiles` | Removed from the new worktree. |
| `skills` | Agent skill directories linked into `.claude/skills` and `.codex/skills`. |
| `baseRef` | The ref overlays are diffed against (default `origin/main`). |

Native build products and dependency trees are never copied. The first `native ensure` in a JS-only worktree is a cache hit.

## Resolving the project

Every `simfleet` command resolves the **main checkout** from any linked worktree (through `git rev-parse --git-common-dir`), so you can run commands from wherever you are editing. The server always runs against the main checkout.

---

## Agents

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/agents
**Description:** Agent sessions, attribution headers, and device claims.

## Headers

Send these on any device request to attribute it to an agent session:

| Header | Value |
| --- | --- |
| `x-simfleet-agent` | `claude`, `codex`, or another short name |
| `x-simfleet-session` | The session or thread ID |

Each attributed request records a **touch** on the device, which expires after 30 minutes without activity.

## `GET /api/v1/agents`

```json
{
  "sessions": [
    { "kind": "claude", "sessionId": "2e82…", "title": "checkout-fix", "cwd": "/Users/me/app-feature-x",
      "status": "idle", "pid": 1209, "startedAt": "…", "updatedAt": "…" }
  ],
  "devices": [
    { "platform": "ios", "deviceId": "8CB8…", "name": "iPhone 17", "state": "Booted",
      "agents": [{ "kind": "claude", "sessionId": "2e82…", "title": "checkout-fix", "cwd": "/Users/me/app-feature-x",
                   "via": "claim", "note": "reviewing checkout", "lastSeenAt": "…" }] }
  ]
}
```

`via` is `claim`, `touch`, or `lane-worktree` (a lane whose worktree is the session's working directory).

## `POST /api/v1/devices/{deviceId}/claim`

```json
{ "agent": "claude", "sessionId": "2e82…", "note": "reviewing checkout" }
```

`agent` and `sessionId` can come from the body or the headers above. Returns `201` with the attachment. A claim lasts until released or until the Claude Code session exits.

## `DELETE /api/v1/devices/{deviceId}/claim`

Releases the caller's claim. Returns `{ "released": true, "deviceId": "…" }`.

---

## Emulators

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/emulators
**Description:** Android emulator lifecycle, inspection, and input.

Emulators are addressed by AVD name. Operations on an emulator that is not running return `409`.

## Lifecycle

```http
POST /api/v1/emulators/{avd}/boot       # { "headless": true, "cold": false, "stock": false }
POST /api/v1/emulators/{avd}/slim
POST /api/v1/emulators/{avd}/restore
POST /api/v1/emulators/{avd}/shutdown
POST /api/v1/emulators/{avd}/tune       # shut-down AVD only; rewrites config.ini for low memory
```

Each returns `202` with a `job` and `pollUrl` (`GET /api/v1/emulators/jobs/{jobId}`). Boots are serialized so avdslim never races for a console port.

## Inspect

| Request | Returns |
| --- | --- |
| `GET /api/v1/emulators/{avd}/ui` | UIAutomator nodes with device-pixel bounds |
| `GET /api/v1/emulators/{avd}/ui?x=&y=` | Hit test |
| `GET /api/v1/emulators/{avd}/screenshot` | PNG |
| `GET /api/v1/emulators/{avd}/definition` | Pixel size and density |

## Input

`POST /api/v1/emulators/{avd}/input` accepts the [simulator input kinds](/docs/api-reference/simulators#input) (except `shake`) plus:

```json
{ "kind": "long-press", "x": 540, "y": 960 }
{ "kind": "dev-menu" }
{ "kind": "button", "button": "back" }
```

Coordinates are device pixels unless `width` and `height` describe a scaled frame. Buttons: `home`, `back`, `app-switcher`, `menu`, `lock`, `power`, `volume-up`, `volume-down`. Text must be ASCII.

---

## Overview

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference
**Description:** The local HTTP and WebSocket API behind the CLI and dashboard.



---

## Lanes

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/lanes
**Description:** Start, launch, and stop lanes; create worktrees.

## `POST /api/v1/lanes`

Returns the lane. Release lanes have `port: null` and `metroPid: null`. Creation fails rather than taking a device, worktree, or port another lane holds.

## Operate

| Request | Effect |
| --- | --- |
| `GET /api/v1/lanes` | Lanes with Metro health |
| `POST /api/v1/lanes/{laneId}/launch` | Debug: waits up to 15 s for Metro, then opens the app at its exact URL. Release: returns a job polled at `/api/v1/lanes/launch-jobs/{jobId}`. |
| `POST /api/v1/lanes/{laneId}/open-url` | Body `{ "url": "buy" }`. A path uses the lane mode's scheme; a full URL passes through. |
| `GET /api/v1/lanes/{laneId}/log?maxCharacters=20000` | Metro log tail (plain text) |
| `POST /api/v1/lanes/{laneId}/stop` | Stops only the Metro process group this lane owns and releases the lease |

## `POST /api/v1/worktrees`

```json
{ "name": "agent-e2e-a", "branch": "fleet-agent/e2e-a", "startPoint": "origin/main" }
```

Creates a sibling worktree and prepares it for the fleet (shared paths, overlays, skills). The name must be lowercase letters, digits, and hyphens. See [Worktrees](/docs/worktrees).

---

## Native builds

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/native-builds
**Description:** Plan and ensure cached native builds.

## `GET /api/v1/native-builds/plan`

Query: `worktreePath`, `mode` (`debug` or `release`), and optionally `simulatorUdid`.

Reports the native fingerprint, cache hit or miss, the cached artifact, whether it is installed on the simulator, the Google services file, and whether the installed app identifier is declared in `nativeAuth`. Builds nothing.

## `POST /api/v1/native-builds/ensure`

```json
{ "worktreePath": "/abs/path", "simulatorUdid": "8CB8…", "mode": "debug" }
```

Starts a single-flight job: the first request for a fingerprint builds it, and concurrent requests wait for the same job. Poll `GET /api/v1/native-builds/jobs/{jobId}` until it completes; the artifact is then installed on the simulator.

---

## Simulators

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/simulators
**Description:** iOS simulator lifecycle, inspection, and input.

## Create

`GET /api/v1/simulator-creation-options` returns installed device types and runtimes. Then:

```http
POST /api/v1/simulators
{ "name": "Fleet iPhone", "deviceTypeIdentifier": "…", "runtimeIdentifier": "…" }
```

The new simulator stays shut down until you boot it through the fleet.

## Lifecycle

```http
POST /api/v1/simulators/{udid}/boot       # body { "stock": true } boots without slimming
POST /api/v1/simulators/{udid}/slim
POST /api/v1/simulators/{udid}/restore
POST /api/v1/simulators/{udid}/shutdown
POST /api/v1/simulators/{udid}/open       # show in Device Hub (Xcode 27+) or Simulator.app
```

Each returns `202` with a `job` and `pollUrl` (`GET /api/v1/simulators/jobs/{jobId}`). Boots succeed only after `simslim verify` confirms the profile, with one automatic retry; cold boots can take a few minutes when several devices contend for CoreSimulator. `restore` and stock boots record an opt-out from [auto-slim](/docs/always-slim); `slim` and a normal boot clear it.

## Inspect

| Request | Returns |
| --- | --- |
| `GET /api/v1/simulators/{udid}/ui` | Accessibility tree with frames in points |
| `GET /api/v1/simulators/{udid}/ui?x=20&y=40` | Hit test at a point |
| `GET /api/v1/simulators/{udid}/screenshot` | JPEG |
| `GET /api/v1/simulators/{udid}/definition` | Screen and device geometry |

## Input

`POST /api/v1/simulators/{udid}/input` with one of:

```json
{ "kind": "tap", "x": 200, "y": 436, "width": 400, "height": 872 }
{ "kind": "double-tap", "x": 200, "y": 436, "width": 400, "height": 872 }
{ "kind": "swipe", "startX": 200, "startY": 700, "endX": 200, "endY": 200, "width": 400, "height": 872 }
{ "kind": "text", "text": "hello" }
{ "kind": "key", "code": "Enter", "modifiers": ["command"] }
{ "kind": "button", "button": "home" }
{ "kind": "orientation", "orientation": "landscape-left" }
{ "kind": "open-url", "url": "myapp://path" }
{ "kind": "shake" }
```

`width` and `height` describe the frame your coordinates are in; pass the size from `/definition` to use device points directly. Key codes are W3C `KeyboardEvent.code` values.

---

## Status

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/status
**Description:** Fleet state, capabilities, and port leases.

## `GET /api/v1/status`

Everything the dashboard shows, in one payload. Cached for a few seconds.

## `GET /api/v1/capabilities`

Supported lifecycle actions, input kinds, buttons, attribution headers, and resource templates per platform. Use it to feature-detect instead of hard-coding.

## `GET /api/v1/ports`

Each environment and mode's port range, live leases, and the next free port.

```json
{
  "allocation": "leased-by-lane",
  "variants": [
    { "environment": "development", "mode": "debug", "range": [8100, 8199],
      "leasedPorts": [8104], "leases": [{ "port": 8104, "laneId": "feature-x-8CB8…" }], "nextAvailablePort": 8105 },
    { "environment": "development", "mode": "release", "range": null,
      "leasedPorts": [], "leases": [], "nextAvailablePort": null }
  ]
}
```

---

## Streaming

**URL:** https://entropyconquers.github.io/simfleet/docs/api-reference/streaming
**Description:** Live video and input over WebSockets.

## iOS

```
ws://127.0.0.1:8790/api/v1/simulators/{udid}/stream?format=mjpeg&version=v2
```

Binary messages are JPEG frames. Send JSON text messages to control the stream, for example `{ "type": "set_fps", "fps": 30 }` and `{ "type": "snapshot" }`. Keep one socket per visible simulator, keep the last frame while reconnecting, and back off exponentially.

## Android

```
ws://127.0.0.1:8790/api/v1/emulators/{avd}/stream
```

Requires scrcpy on the host (`brew install scrcpy`); without it the upgrade fails with `501`. The server pushes scrcpy's device server to the emulator, forwards its H.264 stream, and shares one encoder session between every viewer.

### Messages from the server

The first text message describes the stream:

```json
{ "type": "meta", "width": 720, "height": 1280, "name": "sdk_gphone64_arm64" }
```

Each binary message is one packet: a flag byte followed by an Annex B H.264 payload.

| Bit | Meaning |
| --- | --- |
| `0x01` | Codec config (SPS/PPS). Sent at start and after every rotation. |
| `0x02` | Key frame |

With WebCodecs: build the codec string from the SPS (`avc1.PPCCLL`), configure a `VideoDecoder` without a `description` (Annex B), and prepend the latest config to each key frame.

### Messages to the server

Coordinates are in **video pixels** and must use the current video size (it changes on rotation).

```json
{ "type": "touch", "action": "down", "x": 360, "y": 900, "width": 720, "height": 1280 }
{ "type": "touch", "action": "move", "x": 360, "y": 600, "width": 720, "height": 1280 }
{ "type": "touch", "action": "up",   "x": 360, "y": 400, "width": 720, "height": 1280 }
{ "type": "scroll", "x": 360, "y": 640, "width": 720, "height": 1280, "dx": 0, "dy": -2 }
{ "type": "key", "code": "Enter" }
{ "type": "text", "text": "hello" }
{ "type": "button", "button": "back" }
{ "type": "reset" }
```

`reset` asks the encoder for a fresh config and key frame, which is useful after a decoder error. `scroll` values are wheel notches (±16 max).

---

## Links

- [GitHub](https://github.com/entropyconquers/simfleet)
- [npm](https://www.npmjs.com/package/simfleet)