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

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:

[
  {"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"}
]

---

​

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.