> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useswarm.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Sample Prompts

> Drop-in prompts for driving the Swarm MCP from Claude Code, Codex, Cursor, or any AI editor.

# Sample Prompts

Copy-paste these into your AI editor. Each one maps to a specific MCP tool call (`dev_test`, `dev_watch`, `dev_status`, `dev_close`) so the editor doesn't have to guess.

Replace `localhost:3000` with whatever port your dev server runs on, and the goal/audience text with what you actually want tested.

***

## Smoke tests

### "Is this thing on?"

> Use **dev\_status** to check whether the Useswarm MCP is set up correctly. Tell me the auth state, tunnel state, and any active test.

Returns `{ auth: { configured, valid, apiUrl, recovery }, tunnel, activeTest }`. If `auth.valid: false`, the response includes the exact command to run to fix it.

### List available tools

> What Useswarm MCP tools do you have available, and when would you use each one?

Forces the editor to read the tool descriptions out loud — useful right after `npx @useswarm/mcp setup` to confirm the registration worked.

***

## Using saved swarms

Saved swarms are persona sets you've built once on the Useswarm dashboard and want to reuse — instead of generating fresh personas every test.

### Discover what swarms you have

> Use **dev\_list\_swarms** to show me which Useswarm persona sets are saved on my account.

Returns `{ swarms: [{ id, name, description, agentCount, ... }] }`. Useful as a first step when the user wants to "test with my Buyers swarm" but you don't know the UUID yet.

### Run a test with a named swarm

> Use **dev\_list\_swarms**, then **dev\_test** on `http://localhost:3000` with goal "complete the trial signup" using my "B2B SaaS Buyers" swarm. Then **dev\_watch** the results.

The editor will list swarms, match the name, pass the UUID as `swarmId`, and skip persona generation entirely. `userDescription` and `agentCount` are not needed in this mode.

### Auto-pick if there's only one swarm

> Run **dev\_test** on `http://localhost:3000` with goal "sign up for the free plan". If I have exactly one saved swarm, use it; otherwise generate personas from audience "first-time visitors".

The editor calls `dev_list_swarms`, checks `count`, and branches.

### Compare a saved swarm vs fresh personas

> Run two **dev\_test** calls in parallel against `http://localhost:3000`, goal "complete checkout":
>
> 1. Using my "Returning Customers" swarm
> 2. Generating new personas from audience "first-time shoppers"
>
> **dev\_watch** both, then tell me which group hits more friction and where their experiences diverge.

***

## Single-shot tests

### Basic frontend

> Use **dev\_test** on `http://localhost:3000` with goal "sign up for a new account and reach the dashboard". Audience: "first-time SaaS users, mostly non-technical, ages 25-45". Then call **dev\_watch** with the returned batchId and summarize the issues.

### Frontend + backend (Next + Express, React + Rails, etc.)

> Use **dev\_test** on `http://localhost:3000`, backend `http://localhost:8080`, goal "create a new project and invite a teammate". Audience: "product managers at small startups". Then call **dev\_watch** and tell me what to fix.

### Custom backend paths (WebSocket, gRPC-Web, etc.)

> Use **dev\_test** on `http://localhost:3000` with backendUrl `http://localhost:8080`, backendPaths `["/ws", "/socket.io"]`, goal "send a message in the chat room". Audience: "early-adopter developers".

### More agents for broader signal

> Use **dev\_test** on `http://localhost:3000` with goal "complete checkout end-to-end", audience "shoppers buying their first item", agentCount 8. After the run, give me the top 3 issues by severity.

***

## Authenticated tests

### `agent_login` (existing test account)

> Use **dev\_test** on `http://localhost:3000` with goal "edit profile settings and save". Audience: "returning users on the Pro plan". Auth: mode `agent_login`, loginUrl `http://localhost:3000/login`, username `test@example.com`, password `testpass123`, startUrl `http://localhost:3000/dashboard`.

### `signup` (sub-aliased emails per persona)

> Use **dev\_test** on `http://localhost:3000` with goal "sign up for a free account and verify the email". Audience: "first-time visitors who heard about us on Twitter". Auth: mode `signup`, signupEmail `you@yourdomain.com`. Use 5 agents.

Every persona gets a unique `you+<hash>@yourdomain.com` alias — all confirmations land in your single inbox.

### `cookie_injection` from a JSON file

> Read the cookies from `/path/to/cookies.json`. Then use **dev\_test** on `http://localhost:3000` with goal "create a new project from the dashboard". Audience: "logged-in power users". Pass the cookies as `auth.cookies` and set `auth.startUrl` to `http://localhost:3000/dashboard`.

The editor will read the file, map each entry to the `{name, value, domain, path?, secure?, httpOnly?, sameSite?}` shape, and skip extra Cookie-Editor fields.

### `cookie_injection` inline (Better Auth example)

> Use **dev\_test** on `http://localhost:3000` with goal "open the dashboard", audience "returning logged-in users". Auth: mode `cookie_injection`, startUrl `http://localhost:3000/dashboard`, cookies:
>
> ```json theme={null}
> [
>   {"name":"better-auth.session_token","value":"<paste>","domain":"localhost","path":"/","httpOnly":true,"secure":false,"sameSite":"lax"},
>   {"name":"better-auth.session_data","value":"<paste>","domain":"localhost","path":"/","httpOnly":true,"secure":false,"sameSite":"lax"}
> ]
> ```

<Note>
  **Always set `startUrl`** when using cookie injection. Without it the agent lands on `targetUrl` (often the login page) and won't realize it's already authenticated.
</Note>

***

## The dev loop (multi-step)

### Test → fix → retest until clean

> Test my app at `http://localhost:3000`. Goal: "complete the checkout flow". Audience: "first-time shoppers". After the test, read every issue from **dev\_watch**, fix the code, then call **dev\_test** again. Keep iterating until there are no critical or high issues — then stop and tell me what you changed.

This single prompt drives the full loop. The editor calls `dev_test`, waits with `dev_watch`, reads the structured `issues[]` + `recommendedActions[]`, edits the code, and re-runs. Useful for refactors where you want broad UX validation.

### Test only specific personas

> Use **dev\_test** on `http://localhost:3000` with goal "complete onboarding". Audience: "power users who already use our competitors". Use 4 agents. Then call **dev\_watch**. From the issues, ignore anything tagged "friction" and only fix `critical` and `high` severity items.

The editor can filter the structured `issues[]` array by severity client-side.

### Compare two flows

> Run **dev\_test** twice in sequence:
>
> 1. Goal "sign up via email + password", audience "first-time users"
> 2. Goal "sign up via Google OAuth", audience "first-time users"
>
> Wait for both with **dev\_watch**, then tell me which flow had more friction and what specifically broke for each.

***

## Diagnostics & cleanup

### Something looks wrong

> Use **dev\_status** to figure out what's broken. If auth is invalid, tell me the exact command to fix it. If a tunnel is stuck open, call **dev\_close**.

### Force-close a stuck tunnel

> Use **dev\_close** to tear down whatever tunnel is currently open, then run a fresh **dev\_test** on `http://localhost:3000` with goal "...".

### Quick check on a long-running test

> Call **dev\_watch** with batchId `<paste>` and `wait: false` — I just want a status snapshot, not to wait for completion.

***

## Public URLs (no tunnel)

If your app is already deployed to a staging URL, skip the tunnel:

> Use **dev\_test** on `https://staging.myapp.com` with goal "sign up and create a project". Audience: "first-time users". No backendUrl needed — the public URL serves both frontend and API.

The MCP detects non-localhost targets and goes straight to the API without tunneling.

***

## Tips for getting better results

1. **Be specific about the goal.** "Complete checkout" beats "test the app". Mention the success condition — "...and see the order confirmation page".
2. **Be specific about the audience.** The personas Swarm generates are driven by this. "First-time SaaS users" beats "users".
3. **Set `startUrl` for cookie injection.** Without it the agent lands on the login page.
4. **For frontend+backend apps, always pass `backendUrl`.** Otherwise the agent loads the UI but every API call 404s.
5. **Start with 3 agents.** Add more (`agentCount: 5-8`) once you trust the signal.
6. **Use `dev_status` before raising bugs.** Saves a round-trip when the actual issue is just a stale API key.