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
2 changes: 1 addition & 1 deletion docs/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ measure.
| `mac-sim`, `mac-sim-remote`, `sim-fps`, `android-sim`, `android-gpu-desktop`, `phone-build`, `macbox` | links in `~/.local/bin` |
| the `simulators`, `phone-builds` and `macbox` skills | links in `~/.claude/skills` and `~/.agents/skills` |
| the "Simulators" section of the instructions ([src/agents/simulators-snippet.md](../src/agents/simulators-snippet.md)) | between `<!-- macbox:simulators -->` markers in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md` (each backed up as `.bak-macbox`) |
| `mac-sim-idle.timer` | a user unit, enabled: idle pool simulators shut down after 20 minutes |
| `mac-sim-idle.timer` | a user unit, enabled: idle pool simulators shut down after 15 minutes |

Optional: a Claude Code hook that reminds the agent of the skill whenever a prompt mentions a
simulator ([src/agents/README.md](../src/agents/README.md)). `./macbox agents uninstall` removes the links
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ Everything inside macOS comes from [guest/](../src/guest/README.md), copied to `
| the pool | macOS | `macbox-guest pool create`: simulators named `<device> (<prefix> <label>)`, custom 1x device types copied from the stock profile with `mainScreenScale` changed |
| `mac-sim` | host | claims a pool simulator per checkout (git root), copies the checkout to the Mac, builds there, runs Metro on the host (`macbox-sim-metro-<name>`, a user unit) and reaches it from the Mac through an SSH reverse tunnel, drives the simulator with agent-device. State in `~/.local/state/macbox/mac-sim/` |
| `mac-sim-remote` | macOS, `~/.local/lib/mac-sim/` | the Mac side of mac-sim; mac-sim copies it there when it changes |
| `mac-sim-idle.timer` | host | every 5 minutes, shuts down pool simulators idle for 20 minutes (no mac-sim command, no viewer, no app coming to the front) |
| `mac-sim-idle.timer` | host | every 5 minutes, shuts down pool simulators idle for 15 minutes (no mac-sim command, no viewer, no app coming to the front) |
| `sim-fps` | host | reads a recording; fps and dropped frames per stretch of motion |
| `android-sim` | host | the same shape for local Android emulators |

Expand Down
2 changes: 1 addition & 1 deletion src/agents/simulators-snippet.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Read the `simulators` skill before you start one. Every simulator runs on this m
- **Android** (if set up): `android-sim`, local emulators, one per checkout, so don't wait for another agent's. In T3 Code, open yours in the Device panel with `device_open` (`hostId` `local`, the serial `android-sim serial` prints). Leave an emulator alone if the user opened it from the panel.
- **Web:** run it here (`npx expo start --web`, or the project's own dev server) and look at it in T3 Code's browser.
- **Verify every UI change in the simulator:** run it, take a screenshot and look at it, record the whole flow and check with `sim-fps` that it holds 60 fps with no dropped frames. The skill has the loop and the checklist.
- Close it when the task is done: `mac-sim down` / `android-sim down`.
- **You start it, you stop it.** Start a simulator only when the work needs it, reuse the one your checkout already has, and close it as soon as you're done with it: `mac-sim down` / `android-sim down` (and `device_close` for one you opened in the Device panel). An iOS simulator nobody uses for 15 minutes is shut down anyway.
- If the Mac doesn't answer: `macbox status`, then `macbox up`.
- **A real phone** (an `.ipa` for the user's iPhone, TestFlight, an `.apk`): the `phone-builds` skill (`phone-build`). Free EAS cloud builds go first, then the build runs here.
<!-- macbox:simulators end -->
4 changes: 2 additions & 2 deletions src/sims/bin/mac-sim
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
# mac-sim clean delete this checkout's copy and build on the Mac
# mac-sim setup copy the Mac-side helper and install agent-device on the Mac
# mac-sim idle [--dry-run] [name...]
# shut down pool simulators idle for MAC_SIM_IDLE_MINUTES (20); run
# shut down pool simulators idle for MAC_SIM_IDLE_MINUTES (15); run
# every 5 minutes by the user timer mac-sim-idle.timer
#
# Each checkout (git root) gets its own simulator, so agents in different checkouts work
Expand Down Expand Up @@ -63,7 +63,7 @@ POOL=() MISSING=()
IDLE_HOURS="${MAC_SIM_IDLE_HOURS:-3}"
# A booted simulator with no mac-sim command, viewer or app switch for this long is shut down
# by `mac-sim idle` (its claim stays; the next mac-sim command boots it again).
IDLE_MIN="${MAC_SIM_IDLE_MINUTES:-20}"
IDLE_MIN="${MAC_SIM_IDLE_MINUTES:-15}"
HOST="${MAC_SIM_HOST:-${MACBOX_SSH_HOST:-macbox}}"
T3_HOST_ID="${MACBOX_T3_HOST_ID:-$HOST}"
# Metro for the i-th pool simulator listens on METRO_BASE + 2i (android-sim uses 8081 up).
Expand Down
2 changes: 1 addition & 1 deletion src/sims/systemd/mac-sim-idle.service
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Type=oneshot
# Minutes without a mac-sim command, a viewer or an app switch before a booted pool simulator
# is shut down. MAC_SIM_IDLE_DRY_RUN=1 only logs what it would do. mac-sim reads the rest of
# its settings from ~/.config/macbox/macbox.env.
Environment=MAC_SIM_IDLE_MINUTES=20
Environment=MAC_SIM_IDLE_MINUTES=15
# Use mac-sim's running SSH master if there is one, never start one (systemd would kill it
# when this unit ends, cutting off an agent's command that shares it).
Environment=MAC_SIM_SSH_MASTER=no
Expand Down
2 changes: 1 addition & 1 deletion src/skills/simulators/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ The iOS Simulator draws on the host's GPU through the VM's virtual GPU, so the h

## Rules

- **Close it when the task is done: `mac-sim down` / `android-sim down`.** The pools are shared with other agents and the user. Idle iOS simulators shut down after 20 minutes without a `mac-sim` command or a viewer; a forgotten Android emulator stops after 6 hours.
- **Close it when the task is done: `mac-sim down` / `android-sim down`.** The pools are shared with other agents and the user. Idle iOS simulators shut down after 15 minutes without a `mac-sim` command or a viewer; a forgotten Android emulator stops after 6 hours.
- **Snapshots are the truth.** Refs (`@eN`) change with the screen; take a new snapshot before each tap.
- Use your checkout's simulator only. Don't erase or reset pool simulators, and don't restart CoreSimulatorService (it shuts down every simulator on the Mac). Don't run Simulator.app or `npx expo run:ios` on the Mac: Simulator.app opens a window per simulator and doubles the GPU work. An Android emulator the user opened from the Device panel is theirs; use it only when they ask.
- **The `full` iOS simulator is also the user's own.** Don't change its settings or erase it; `mac-sim down` leaves it running.
Expand Down
4 changes: 2 additions & 2 deletions src/skills/simulators/references/ios.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,9 @@ You run on the same machine as the Mac, so the stream in T3 doesn't matter to yo
## Rules

- **Close it when the task is done: `mac-sim down`.** A claim nobody uses for 3 hours (`MAC_SIM_IDLE_HOURS`) is freed by the next `mac-sim` command, and its simulator shut down.
- **Idle simulators are shut down, the full one too.** Every 5 minutes a user timer (`mac-sim-idle.timer`) shuts down a pool simulator that was booted at least 20 minutes ago (`MAC_SIM_IDLE_MINUTES`) and, for 20 minutes, had no `mac-sim` command, no viewer (T3's Device panel while it's visible, a hub's WebRTC viewer, Simulator.app) and no app coming to the foreground. The claim stays, and so do Metro and the tunnel:
- **Idle simulators are shut down, the full one too.** Every 5 minutes a user timer (`mac-sim-idle.timer`) shuts down a pool simulator that was booted at least 15 minutes ago (`MAC_SIM_IDLE_MINUTES`) and, for 15 minutes, had no `mac-sim` command, no viewer (T3's Device panel while it's visible, a hub's WebRTC viewer, Simulator.app) and no app coming to the foreground. The claim stays, and so do Metro and the tunnel:
- The next `mac-sim` command (`up`, `run`, `snapshot`, `ad`, `shot`, `open`...) boots it again and says it had been shut down. Apps that were open are closed: `mac-sim run` again. `mac-sim mac`, `udid` and `t3` don't boot it; `mac-sim up` first.
- A build or recording in progress counts as use. Waiting more than 20 minutes between commands without anyone watching doesn't.
- A build or recording in progress counts as use. Waiting more than 15 minutes between commands without anyone watching doesn't.
- Shutdowns and their reasons are in `~/.local/state/macbox/mac-sim/idle.log`; `mac-sim status` shows `off (shut down idle at …)`. Simulators outside the pool are never touched.
- **Snapshots are the truth.** Refs (`@eN`) change with the screen; take a new snapshot before each tap.
- Don't restart CoreSimulatorService, don't run `simslim`, and don't erase or delete pool simulators: other agents and the user use them.
Expand Down
Loading