agent device
- Repo stars 4,864
- Author repo App
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @Expensify · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# agent-device
## Pre-flight (auto)
These checks evaluate at skill load. If any line shows `FAIL`, stop and surface the fix before running any device command.
`agent-device` version: !`R=0.13.0; V=$(agent-device --version 2>/dev/null); [ -n "$V" ] && [ "$(printf '%s\n%s\n' "$R" "$V" | sort -V | head -1)" = "$R" ] && echo "OK ($V)" || echo "FAIL (need v$R+, got: ${V:-not installed}). Fix: npm install -g agent-device@latest"`
Bundled CLI skills dir: !`D="$(npm root -g)/agent-device/skills/agent-device"; test -s "$D/SKILL.md" && echo "OK ($D)" || echo "FAIL (missing $D/SKILL.md). Fix: npm install -g agent-device@latest"`
HybridApp mode: !`M=$(scripts/is-hybrid-app.sh 2>/dev/null | tail -1); [ "$M" = "true" ] && echo "OK (HybridApp)" || echo "FAIL (got: ${M:-unknown}). This skill only supports the HybridApp build - ensure the Mobile-Expensify submodule is present."`
## Bring-up
Run this sequence the first time the user asks for device interaction in a session, before any `open` / `snapshot` / `replay`.
### 1. Platform
If the user prompt names `ios` or `android` explicitly, use it. Otherwise ask. Only iOS and Android are supported; reject other platforms.
### 2. Bundle ID
HybridApp dev builds only (the pre-flight gate enforces this).
| Platform | Bundle ID | Build script |
| --------- | ------------------------------- | ----------------- |
| `ios` | `com.expensify.expensifylite` | `npm run ios` |
| `android` | `org.me.mobiexpensifyg.dev` | `npm run android` |
### 3. Confirm dev build is installed
```bash
agent-device apps --user-installed --platform <p> --json
```
If the resolved bundle ID is missing from the list, **STOP** and instruct the developer to run the matching build script from the table. HybridApp mobile builds **must** be initiated from `Mobile-Expensify/` (per project CLAUDE.md).
### 4. Metro
```bash
agent-device metro prepare --public-base-url http://localhost:8081 --port 8081 --kind react-native
```
If `metro prepare` fails, **STOP** and surface the error verbatim.
### 5. Pick a target device
```bash
agent-device devices --platform <p> --json
```
- Prefer the first device with `booted=true`.
- If none are booted, choose the default target device (usually the first listed), then continue to step 6 to detect and clear any stale session bound to that device before opening.
- If multiple are booted, ask the user which.
Capture the device name and (for iOS) the simulator UDID, or (for Android) the serial.
### 6. Session reuse vs reset
```bash
agent-device session list --json
```
For each entry whose `device_udid` (iOS) or `serial` (Android) matches the chosen device:
- If the session was created earlier in the **current** Claude invocation, reuse it silently.
- Otherwise prompt: `reuse` (continue with the existing session) or `reset` (force-close it).
- To reset: `agent-device close --shutdown --session <name>`. `--shutdown` also frees the simulator.
### 7. Open
```bash
agent-device open <bundle-id> --platform <p> --device "<name>"
```
If `open` errors with "app not installed", revisit step 3.
### 8. Sanity
```bash
agent-device snapshot -i
```
Confirm the app rendered. From here, follow the [Agent decision loop](flows/README.md) for repeatable flows or drive interactively.
### Canonical skill references
Read these files directly for device automation guidance (bootstrap, exploration, verification, debugging): !`echo "$(npm root -g)/agent-device/skills/agent-device"`
## Flows
Repeatable steps (sign-in, onboarding, etc.) are captured as composable `.ad` snippets under [`flows/`](flows/README.md). For interactive usage, propose and run only `flows/macros/` helpers. `flows/tests/` belongs to a separate QA workflow and must not be proposed by this skill; QA/perf runs execute them via `agent-device test <path>`.
Sections and files
Listed in source order.
sections -> Pre-flight (auto) → Bring-up → 1. Platform → 2. Bundle ID → 3. Confirm dev build is installed → 4. Metro
terms -> STOP · must · current · These checks evaluate at skill load. · Run this sequence the first time the user asks for device interaction in a session, before any open / snapshot / replay. · If the user prompt names ios or android explicitly, use it. · HybridApp dev builds only (the pre-flight gate enforces this). · If the resolved bundle ID is missing from the list, STOP and instruct the developer to run the matching build script from the table.
files/cmd -> FAIL · agent-device · open · snapshot · replay · ios · android · com.expensify.expensifylite
body sha256 -> 0ba3ce5ce654
Pre-flight (auto)
These checks evaluate at skill load. If any line shows
FAIL, stop and surface the fix before running any device command.agent-deviceversion: !R=0.13.0; V=$(agent-device --version 2>/dev/null); [ -n "$V" ] && [ "$(printf '%s\n%s\n' "$R" "$V" | sort -V | head -1)" = "$R" ] && echo "OK ($V)" || echo "FAIL (need v$R+, got: ${V:-not installed}). Fix: npm install -g agent-device@latest"Bundled CLI skills dir: !D="$(npm root -g)/agent-device/skills/agent-device"; test -s "$D/SKILL.md" && echo "OK ($D)" || echo "FAIL (missing $D/SKILL.md). Fix: npm install -g agent-device@latest"Bring-up
Run this sequence the first time the user asks for device interaction in a session, before any
open/snapshot/replay.1. Platform
If the user prompt names
iosorandroidexplicitly, use it. Otherwise ask. Only iOS and Android are supported; reject other platforms.2. Bundle ID
HybridApp dev builds only (the pre-flight gate enforces this). Platform · Bundle ID · Build script
ios·com.expensify.expensifylite·npm run iosandroid·org.me.mobiexpensifyg.dev·npm run android3. Confirm dev build is installed
If the resolved bundle ID is missing from the list, STOP and instruct the developer to run the matching build script from the table. HybridApp mobile builds must be initiated from
Mobile-Expensify/(per project CLAUDE.md).