From 7ecd2bf12a43099939a09c16a12d3a254da98682 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Wed, 13 May 2026 13:50:29 +0200 Subject: [PATCH] docs: clarify agent-device binary resolution --- README.md | 3 +-- skills/agent-device/SKILL.md | 10 ++++++- skills/dogfood/SKILL.md | 4 ++- skills/react-devtools/SKILL.md | 24 ----------------- .../suites/agent-device-smoke-suite.ts | 2 +- website/docs/docs/agent-setup.md | 26 ++++++++++++++----- website/docs/docs/installation.md | 18 ++++++++++--- 7 files changed, 47 insertions(+), 40 deletions(-) delete mode 100644 skills/react-devtools/SKILL.md diff --git a/README.md b/README.md index de970cb2..e875d6eb 100644 --- a/README.md +++ b/README.md @@ -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@", "mcp"] } } } @@ -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) diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md index b88a0fd8..027ff615 100644 --- a/skills/agent-device/SKILL.md +++ b/skills/agent-device/SKILL.md @@ -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: diff --git a/skills/dogfood/SKILL.md b/skills/dogfood/SKILL.md index 2295edda..2cab72a1 100644 --- a/skills/dogfood/SKILL.md +++ b/skills/dogfood/SKILL.md @@ -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: diff --git a/skills/react-devtools/SKILL.md b/skills/react-devtools/SKILL.md deleted file mode 100644 index 24ec482a..00000000 --- a/skills/react-devtools/SKILL.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: react-devtools -description: Inspect and profile React Native component trees from agent-device. Use for React Native performance, profiling, props, state, hooks, render causes, slow components, excessive rerenders, or questions like why a component rerendered. ---- - -# react-devtools - -Router for React Native internals. Private setup before using this skill: - -```bash -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. - -Read current CLI guidance: - -```bash -agent-device help react-devtools -``` - -Use `agent-device react-devtools ...` for component tree, props, state, hooks, render ownership, performance profiling, slow components, or rerenders. Use normal `agent-device` commands for visible UI, refs, screenshots, logs, network, or device-level perf. - -Keep reads bounded with `--depth`/`find`, treat `@c` refs as reload-local, and profile only the investigated interaction. Let `help react-devtools` provide exact command shapes, remote bridge ordering, pinned package details, and current workflow guidance. diff --git a/test/skillgym/suites/agent-device-smoke-suite.ts b/test/skillgym/suites/agent-device-smoke-suite.ts index 11a15efd..e31815e7 100644 --- a/test/skillgym/suites/agent-device-smoke-suite.ts +++ b/test/skillgym/suites/agent-device-smoke-suite.ts @@ -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 diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index 007a1014..982012dd 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -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). @@ -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 @@ -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@", "mcp"] } } } @@ -106,6 +108,16 @@ agent-device open --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 diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md index cafbc2ec..b4cfe8e0 100644 --- a/website/docs/docs/installation.md +++ b/website/docs/docs/installation.md @@ -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' +``` + +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: @@ -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