You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 3fb9a4c
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -52,11 +52,15 @@ Install the CLI:
52
52
53
53
```bash
54
54
npm install -g agent-device@latest
55
+
agent-device doctor
55
56
agent-device --version
56
57
agent-device help workflow
57
58
```
58
59
59
-
The installed CLI help is the source of truth for agents. Start with `agent-device help workflow`, then follow the topic-specific help when a task needs dogfooding, debugging, replay, or React Native profiling.
60
+
Run `agent-device doctor` yourself after installation to check local setup before
61
+
handing the CLI to an agent. The installed CLI help is the source of truth for
62
+
agents. Start with `agent-device help workflow`, then follow the topic-specific
63
+
help when a task needs dogfooding, debugging, replay, or React Native profiling.
60
64
61
65
Prerequisites depend on the target platform: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. Web automation requires Node 24+. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for platform setup.
On a fresh machine (first iOS run), start with `agent-device doctor --platform ios`: it preflights the environment and warms the iOS runner build cache in the background so the first `open` is fast.
42
-
43
41
Use this skill only to route into version-matched CLI help. Let the selected help topic provide exact command shapes, platform limits, and current workflow guidance; use `help workflow` as the full reference when a task-specific topic is too narrow.
44
42
45
43
For precise location workflows, read the installed `settings` help before planning so coordinate support and platform limits come from the active CLI version.
'Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.',
94
94
'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',
95
95
'Install flows: install/install-from-source first, then open the installed id with --relaunch.',
96
-
'Text: fill \'id="field-email"\' "[email protected]" replaces; type appends after press.',
96
+
'Text fields: use fill <target> <text> --settle to replace a field value. Use type <text> only to append after focusing a field with press.',
97
97
'Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',
98
98
'Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.',
99
99
'Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.',
@@ -168,6 +168,7 @@ Loop:
168
168
169
169
Targets:
170
170
Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow".
171
+
For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
171
172
Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
172
173
Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.
173
174
@@ -187,9 +188,6 @@ Core loop:
187
188
Start with the top-level Agent Starting Point for the default settle-first loop. This topic is the full reference for command shapes, refs, selectors, waits, recovery, and platform limits.
188
189
If you intentionally skip --settle or use a command that does not support it, verify a mutation with diff snapshot (or diff snapshot -i) instead of a full snapshot: it diffs the rendered snapshot lines against the previous one in this session and prints only what changed.
189
190
190
-
Fresh machine or first iOS run:
191
-
Run agent-device doctor --platform ios first. Besides preflight checks it warms the iOS XCTest runner build cache in the background, so the first open skips the runner build (~10s). To block until fully warm instead, run agent-device prepare ios-runner.
192
-
193
191
Command shape:
194
192
Plans should use agent-device commands, not raw platform tools, pseudo commands, package-manager aliases, or helper prose.
195
193
If the user asks for a command plan, final output should be command lines only: no intro sentence, numbered list, Markdown fence, shell pipe, grep/head/tail helper, or explanatory bullets.
@@ -690,11 +688,7 @@ Choose the next help topic:
690
688
Remote/cloud config, leases, and local service tunnels: help remote.
691
689
692
690
React Native dev loop:
693
-
Before QA/dogfood runs, use doctor to separate environment setup from app failures (on iOS simulators doctor also warms the runner build cache in the background):
694
-
agent-device doctor --platform android
695
-
agent-device doctor --platform ios
696
-
agent-device doctor --platform android --app com.example.app
697
-
agent-device doctor --remote --remote-config ./remote.json
691
+
Do not run doctor as routine QA/dogfood prep. Use doctor only when the user asks for setup diagnostics or a command failure points to an unhealthy device, runner, dev-server, or remote environment.
698
692
For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
'Preflight for QA and dogfood runs. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing, so the first open on a fresh machine skips the runner build — run doctor first on new setups. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
33
-
summary: 'Preflight device, app, dev-server, and RN/Expo readiness',
32
+
'Setup and recovery diagnostic for device, app, dev-server, and RN/Expo readiness issues. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
33
+
summary: 'Diagnose device, app, dev-server, and RN/Expo readiness',
0 commit comments