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 6e80737
Browse filesBrowse the repository at this point in the historyBrowse files
docs(agent-setup): keep one canonical agent rule (#3396)
* docs(agent-setup): keep one canonical agent rule with per-client placement
Collapse the recommended, Cursor .mdc, and CLAUDE.md rule copies into one
copyable rule and point each client section at it, with a placement table.
Cursor keeps its required frontmatter; Claude Code no longer overwrites an
existing CLAUDE.md. The startup contract test now requires a single rule
block that starts work immediately.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* docs(agent-setup): require the open-first line first; leave a visible Cursor placeholder
Co-Authored-By: Claude Opus 5.5 <[email protected]>
---------
Co-authored-by: Claude Opus 5.5 <[email protected]>
Copy file name to clipboardExpand all lines: website/docs/docs/agent-setup.md
+36-41Lines changed: 36 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,12 +29,26 @@ Skills come from the GitHub repository, not the npm package. The [agent-device s
29
29
30
30
## Recommended agent rule
31
31
32
-
Add this as a project rule or custom instruction if your agentclient supports one:
32
+
Add this rule to your agent client's project rules or custom instructions. [Set up your client](#set-up-your-agent-client) shows where the file goes for each client.
33
33
34
34
```text
35
-
Use agent-device only for app/device automation tasks. For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot. For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`. For exploratory QA, read `agent-device help dogfood`. For logs, network, audio, 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`. For React Native JavaScript heap growth, heap snapshots, allocation hotspots, or retained-object leaks, read `agent-device help cdp`. For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
35
+
Use agent-device only for app/device automation tasks.
36
+
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
37
+
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
38
+
For exploratory QA, read `agent-device help dogfood`.
39
+
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
40
+
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
41
+
For React Native JavaScript heap growth, heap snapshots, allocation hotspots, or retained-object leaks, read `agent-device help cdp`.
42
+
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
36
43
37
-
Use MCP tools or the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where the target supports capture and selectors; otherwise follow target-specific help. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
44
+
Use MCP tools or the CLI in the integrated terminal.
45
+
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`.
46
+
Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version.
47
+
MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution.
48
+
Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close` where the target supports capture and selectors; otherwise follow target-specific help.
49
+
Use current refs such as `@e3` for exploration and selectors for durable replay.
50
+
Keep mutating commands against one session serial.
51
+
Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
38
52
```
39
53
40
54
## MCP server
@@ -81,13 +95,26 @@ In MCP registries, the server is listed as `io.github.callstack/agent-device` (n
81
95
82
96
Some agent clients run commands with a different `PATH` than your normal shell, so a global install that works in your terminal can be missing in the agent's terminal or MCP server. Run `command -v agent-device` in your own terminal and give the agent that absolute path, or use it as the MCP server `command`. If the path is under a version manager or a package-manager global bin directory, check your shell startup files for how that directory gets on `PATH`; the agent client may not load them.
83
97
98
+
## Set up your agent client
99
+
100
+
Each client reads the [recommended agent rule](#recommended-agent-rule) from its own location:
101
+
102
+
| Client | Where the rule goes | Client-specific wrapper |
103
+
| --- | --- | --- |
104
+
| Cursor |`.cursor/rules/agent-device.mdc`| Required `.mdc` frontmatter above the rule |
105
+
| Codex |`AGENTS.md` in the project root | None |
106
+
| Claude Code |`CLAUDE.md` in the project root | None; an `# agent-device` heading keeps it separate from other instructions |
107
+
| Windsurf, Cline, Goose, and others | The client's project rules or custom instructions | Whatever the client requires for a rules file |
108
+
109
+
The sections below cover each client, including MCP setup.
110
+
84
111
## Cursor
85
112
86
113
Cursor can use the CLI or MCP tools. Use the CLI when you want every command visible in the terminal. Add MCP when you want Cursor Agent to discover `agent-device` tools directly from chat.
87
114
88
115
### Cursor: use the CLI
89
116
90
-
Create a project rule:
117
+
Create the rule file with the frontmatter Cursor requires:
91
118
92
119
```bash
93
120
mkdir -p .cursor/rules
@@ -97,23 +124,11 @@ description: Use agent-device for app and device automation
97
124
alwaysApply: true
98
125
---
99
126
100
-
Use agent-device only for app/device automation tasks.
101
-
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
102
-
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
103
-
For exploratory QA, read `agent-device help dogfood`.
104
-
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
105
-
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
106
-
For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help cdp`.
107
-
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
108
-
109
-
Use the CLI in Cursor's integrated terminal.
110
-
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the absolute binary path instead of using `npx -y agent-device@latest`.
Keep mutating commands against one session serial.
127
+
REPLACE THIS LINE with the recommended agent rule from https://oss.callstack.com/agent-device/docs/agent-setup#recommended-agent-rule
113
128
EOF
114
129
```
115
130
116
-
Then ask Cursor Agent to run:
131
+
Open `.cursor/rules/agent-device.mdc` and replace the placeholder line with the [recommended agent rule](#recommended-agent-rule). Then ask Cursor Agent to run:
117
132
118
133
```bash
119
134
agent-device open <app-or-url> --platform ios --foreground
@@ -158,7 +173,7 @@ If the MCP server fails to start because Cursor can't find the global binary, us
158
173
159
174
## Codex
160
175
161
-
Put the [recommended rule](#recommended-agent-rule)in`AGENTS.md`or the project instructions, then let Codex run `agent-device` in the terminal:
176
+
Paste the [recommended agent rule](#recommended-agent-rule)into`AGENTS.md`in the project root, or into the project instructions, then let Codex run `agent-device` in the terminal:
162
177
163
178
```bash
164
179
agent-device open <app-or-url> --platform ios --foreground
@@ -174,27 +189,7 @@ Claude Code can use `agent-device` from the terminal or from the VS Code extensi
174
189
175
190
### Claude Code: use the CLI
176
191
177
-
Put this in `CLAUDE.md`:
178
-
179
-
```bash
180
-
cat > CLAUDE.md <<'EOF'
181
-
# agent-device
182
-
183
-
Use agent-device only for app/device automation tasks.
184
-
For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`; open the requested app in the foreground and continue from its initial interactive snapshot.
185
-
For TV, Fire TV, or Vega OS tasks, read `agent-device help tv`.
186
-
For exploratory QA, read `agent-device help dogfood`.
187
-
For logs, network, audio, traces, or runtime failures, read `agent-device help debugging`.
188
-
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
189
-
For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help cdp`.
190
-
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
191
-
192
-
Use the CLI in the integrated terminal.
193
-
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the absolute binary path instead of using `npx -y agent-device@latest`.
Keep mutating commands against one session serial.
196
-
EOF
197
-
```
192
+
Open `CLAUDE.md` in the project root, creating it if it doesn't exist. Add an `# agent-device` heading and paste the [recommended agent rule](#recommended-agent-rule) below it. Keep any instructions already in the file.
198
193
199
194
Then ask Claude Code to run:
200
195
@@ -242,7 +237,7 @@ You can still run CLI commands in the integrated terminal for long-running or ma
242
237
243
238
If the client supports `mcpServers`, use the [MCP server](#mcp-server) configuration, then tell the agent to use MCP tools or terminal CLI commands for device work.
244
239
245
-
If the client supports project rules or custom instructions, add the [recommended agent rule](#recommended-agent-rule). If it doesn't, ask the agent to open the requested app and continue from the initial interactive snapshot; point it to a help topic only when the task is specialized or a command is unclear.
240
+
If the client supports project rules or custom instructions, paste the [recommended agent rule](#recommended-agent-rule) there, inside any wrapper the client requires for a rules file. If it doesn't, ask the agent to open the requested app and continue from the initial interactive snapshot; point it to a help topic only when the task is specialized or a command is unclear.
0 commit comments