Steps

Run in order. Relay each Step N line. Do not pick variants; the CLI owns them.

1. bun devices list. Copy one value of column OPTION: --platform=<ios|android> for simulator or emulator, --target=<target> for a phone. Use it as <device> below. Phone: bun devices reserve <device> --goal="<what you do>" first, so other agents cannot take it. Pick another phone on device_reserved.
2. bun app install <device>
3. bun app seed <device> --fixture=<id> (ids: bun app seed --help)
4. bun app open <device>
5. Use the app: bun app drive <device> -- <agent-device args>. Commands: bunx agent-device help workflow. Never call bunx agent-device directly: it skips reservations and picks its own session.
6. bun app close <device>
7. Phone: bun devices release <device>

e2e: bun e2e run <device> [--paths=<path,...>]. One device per command. Start one command per phone for parallel runs. Help and errors: bun <noun> <command> --help. devicectl hangs or "Device is busy": bun devices doctor. Limits on phones: development.md.

Waiting

app build, app install, app dev, and e2e run take minutes. First stderr line: Log: <path>, new file per run. Last stdout line: PIXY_RESULT status=<ok|error> command=<name> [code=<status>] [path=<artifact>].

1. Start the command with run_in_background.
2. Wait for the exit notification. Read PIXY_RESULT for the result.
3. To watch progress, Monitor tail -n 0 -F <Log path> | grep -E --line-buffered 'Step |PIXY_RESULT|error:|BUILD FAILED'. Take the path from the Log: line of this run only.

• Never poll with sleep N; tail. Never reuse old /tmp or log files.
• Never switch verification surface (web, Playwright, other device) while you wait, unless the user asks.

Development with Metro (hot reload)

Use when the user edits code and wants to see changes without a native build.

1. bun app dev --platform=<ios|android>. Installs the cached dev client, starts this checkout's Metro, opens the app, prints a screenshot path. Data and flags in one go: bun app dev --platform=ios --fixture=year --flag=people=on,photos=off. Dev menu stays hidden.
2. Edit code. The app reloads. Rerun step 1 to reload by hand.
3. Drive the app: bun app drive --platform=<ios|android> -- <agent-device args>. App ID com.devmood.pixymoodtracker.dev.
4. bun app close --platform=<ios|android> stops Metro and the device.

Rules:

• Builds live in ~/.cache/pixy-mood-tracker/build-cache. bun builds list shows them. Never search ios/build or ~/Library/Developer/Xcode/DerivedData, never conclude "no dev build" from them.
• Never create simulators by hand. The CLI owns one simulator per checkout.
• Dev client is shared across worktrees with the same native dependencies. A cache miss means native dependencies changed. Compile then, not before.
• Phones: bun ios --device <udid>.

Shell (zsh)

• Never put several flags in one variable ($FLAGS). zsh does not split words, so the command gets one argument. Use an array: flags=(--platform=ios); bun app drive "${flags[@]}" -- snapshot
• Write ${VAR}:path, not $VAR:path. zsh reads :r, :h, :t after $VAR as modifiers.
• Quote globs in arguments (--include='*.ts'). zsh fails the command on an unmatched glob: no matches found.