Skip to content

docs: clarify agent-device binary resolution #511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thymikee merged 1 commit into from
May 13, 2026
+47 −40
Merged

docs: clarify agent-device binary resolution #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 1 addition & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Paste one of these into clients that accept `mcpServers`, such as Cursor project
"mcpServers": {
"agent-device": {
"command": "npx",
"args": ["-y", "agent-device@latest", "mcp"]
"args": ["-y", "agent-device@<reviewed-version>", "mcp"]
}
}
}
Expand Down Expand Up @@ -221,7 +221,6 @@ Used by teams and developers at Callstack, Expensify, Shopify, Kindred, Total Wi
Agent integration:

- [agent-device skill](skills/agent-device/SKILL.md)
- [react-devtools skill](skills/react-devtools/SKILL.md)
- [dogfood skill](skills/dogfood/SKILL.md)
- MCP router: `agent-device mcp`
- [agent-device skill on ClawHub](https://clawhub.ai/okwasniewski/agent-device)
Expand Down
10 changes: 9 additions & 1 deletion skills/agent-device/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,15 @@ Router only. Private setup before using this skill:
agent-device --version
```

Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
If that fails but the user installed `agent-device` globally, try the user's login shell before using `npx`:

```bash
zsh -lic 'command -v agent-device'
```

If it prints a path, run that absolute path instead of `agent-device`. For non-zsh shells, use the equivalent login-shell command.

Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.

Before your first agent-device command or plan, read the version-matched CLI guide:

Expand Down
4 changes: 3 additions & 1 deletion skills/dogfood/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ Router for exploratory QA. Private setup before using this skill:
agent-device --version
```

Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
If that fails, stop and tell the user to expose a trusted `agent-device` binary on PATH or approve an exact-version npm command. This skill intentionally keeps allowed tools restricted to `agent-device` and `npx agent-device`.

Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.

Read current CLI guidance:

Expand Down
24 changes: 0 additions & 24 deletions skills/react-devtools/SKILL.md
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion test/skillgym/suites/agent-device-smoke-suite.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ function assertAgentDeviceEvidence(report: SessionReport) {
const detectedSkills = report.detectedSkills ?? [];
const hasDetectedSkills = detectedSkills.length > 0;
const hasBundledDeviceSkill = detectedSkills.some((skill) =>
['agent-device', 'react-devtools', 'dogfood'].includes(skill.skill),
['agent-device', 'dogfood'].includes(skill.skill),
);

// Some SkillGym runners do not expose skill telemetry. Keep this as a conditional routing
Expand Down
26 changes: 19 additions & 7 deletions website/docs/docs/agent-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,16 @@ agent-device --version
agent-device help workflow
```

For one-off use without a global install:
For one-off human use without a global install:

```bash
npx -y agent-device@latest --version
npx -y agent-device@latest help workflow
npx agent-device --version
npx agent-device help workflow
```

Global install is better for normal agent workflows because repeated commands, skills, and terminal sessions resolve to one stable version.
Global install is better for normal agent workflows because repeated commands, skills, and terminal sessions resolve to one stable version. Project-local installs are also good when you want a lockfile-pinned agent-device version.

Avoid telling agents to choose an npm version or run `npx -y agent-device@latest` autonomously: it fetches and executes a mutable npm package without a human prompt. For unattended agent use, prefer a trusted installed binary, a project-local install, or a version supplied by the user or project config.

For Node, Xcode, Android SDK, macOS, and iOS device prerequisites, see [Installation](/docs/installation).

Expand All @@ -47,7 +49,7 @@ Add this as a project rule, custom instruction, or skill equivalent when your ag
```text
Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.

Use the CLI in the integrated terminal. MCP is only a discovery/help router and does not expose device automation tools. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
Use the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, ask the user's login shell for the absolute path and run that path instead. For macOS zsh users, use `zsh -lic 'command -v agent-device'`; for other shells, use the equivalent login-shell lookup. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP is only a discovery/help router and does not expose device automation tools. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
```

## MCP router
Expand All @@ -67,14 +69,14 @@ Global install configuration:
}
```

No global install variant:
No global install variant. Pin a user- or project-selected package version for unattended agent use:

```json
{
"mcpServers": {
"agent-device": {
"command": "npx",
"args": ["-y", "agent-device@latest", "mcp"]
"args": ["-y", "agent-device@<reviewed-version>", "mcp"]
}
}
}
Expand Down Expand Up @@ -106,6 +108,16 @@ agent-device open <app-or-url> --platform ios
agent-device snapshot -i
```

Some agent clients run commands in an environment that differs from the user's normal install shell. If the user installed `agent-device` globally but the agent cannot find it, have the agent ask the user's login shell for the absolute path.

For macOS zsh users:

```bash
zsh -lic 'command -v agent-device'
```

For other shells, use the equivalent login-shell lookup. Then use the printed path for `--version`, `help workflow`, and subsequent commands.

For reviews or planning-only tasks, tell the agent not to run devices unless explicitly requested.

## Claude Code
Expand Down
18 changes: 14 additions & 4 deletions website/docs/docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,16 @@ agent-device help debugging
agent-device help react-devtools
```

Some agent clients run commands in an environment that differs from the user's normal install shell. If `agent-device` is missing in the agent terminal but was installed globally elsewhere, ask the user's login shell for the absolute path.

For macOS zsh users:

```bash
zsh -lic 'command -v agent-device'
```
Comment on lines +30 to +32
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve the actual login shell instead of zsh

This guidance says to resolve the user's login shell, but the command unconditionally runs zsh; on Linux agents, bash/fish users, or machines without zsh, it either fails or reads the wrong shell startup files, so a valid global npm install can still be missed. Use the user's actual login shell (or clearly scope this to zsh/macOS and provide a portable alternative) so the documented fallback works outside zsh environments.

Useful? React with 👍 / 👎.


For other shells, use the equivalent login-shell lookup. Then use the printed path for agent commands.

For Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, project rules, and MCP configuration, see [AI Agent Setup](/docs/agent-setup). For the first app automation commands, see [Quick Start](/docs/quick-start).

Interactive CLI runs periodically check for a newer published `agent-device` package in the background. When an upgrade is available, the CLI suggests reinstalling the package globally:
Expand All @@ -47,12 +57,12 @@ Use [AI Agent Setup](/docs/agent-setup#mcp-router) for copy-paste MCP client con
## Without installing

```bash
npx -y agent-device@latest --version
npx -y agent-device@latest help workflow
npx -y agent-device@latest open Settings --platform ios
npx agent-device --version
npx agent-device help workflow
npx agent-device open Settings --platform ios
```

One-off `npx` usage is fine for humans and scripts. For agents, prefer global install so repeated commands and any installed skills resolve to the same CLI version. If an agent cannot rely on skills, it should run `agent-device help` or `agent-device help workflow` before planning device commands.
One-off `npx` usage is fine for humans and scripts that intentionally fetch from npm. For agents, prefer a global install, a project-local install, or a version supplied by the user or project config so repeated commands resolve to a known CLI. Do not ask agents to choose a version or run `npx -y agent-device@latest` without an explicit trust decision.

## Requirements

Expand Down
Loading