Skip to content

Commit 52a46a9

Browse files
committed
docs: clarify follow-up routing after session open
1 parent 1c7fffd commit 52a46a9

1 file changed

Lines changed: 30 additions & 0 deletions

File tree

skills/agent-device/references/bootstrap-install.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,36 @@ agent-device --session auth snapshot -i
5959
- In iOS sessions, use `open <app>` for the app itself. Use `open <url>` for deep links, and `open <app> <url>` when you need to launch the app and deep link in one step.
6060
- On iOS, `appstate` is session-scoped and requires the matching active session on the target device.
6161

62+
## After a session is established
63+
64+
Once you have opened the correct session on the correct target, stop repeating device-routing flags on follow-up commands unless you are intentionally retargeting.
65+
66+
Two common cases:
67+
68+
- Single-agent or isolated environment:
69+
- If this agent is the only session on the device or the environment is already isolated, follow-up commands can usually omit routing flags after the initial `open`.
70+
- Shared host or multiple agents:
71+
- If several agents may use the same machine, always keep the session binding on follow-up commands with `--session <name>` or a sandboxed `AGENT_DEVICE_SESSION`.
72+
- Do not keep repeating `--platform`, `--target`, `--device`, `--udid`, `--serial`, or similar target-selection flags on normal follow-up commands.
73+
74+
Good shared-host pattern:
75+
76+
```bash
77+
agent-device --session auth open Settings --platform ios --device "iPhone 17 Pro"
78+
agent-device --session auth snapshot -i
79+
agent-device --session auth press @e3
80+
agent-device --session auth close
81+
```
82+
83+
Bad shared-host pattern:
84+
85+
```bash
86+
agent-device --session auth open Settings --platform ios --device "iPhone 17 Pro"
87+
agent-device --session auth snapshot -i --platform ios --device "iPhone 17 Pro"
88+
```
89+
90+
Use target-selection flags again only when you are choosing the target before opening a session, or when you explicitly mean to retarget.
91+
6292
## Session-bound automation
6393

6494
Use this when an orchestrator must keep plain CLI calls on one session and device.

0 commit comments

Comments
 (0)