
mobile-agent-testers
Set up and run parallel AI testers (one Claude Code agent per phone, with personas) for an iOS/Android app
- GitHub stars
- 32
Install
/plugin install mobile-agent-testers@mobile-agent-testersRun it inside Claude Code after adding the marketplace with /plugin marketplace add pierridotite/mobile-agent-testers.
Contents
Discovered from sourceSkills 1
Set up mobile agent testers
Goal: the user gets a testers repo where one workflow builds their app, boots one phone per persona (Android emulators on Linux runners, iOS Simulators on macOS runners), lets a Claude Code agent use the app like a new user, and returns encrypted reports with screenshots, merged into one SUMMARY.md.
Template and full docs: https://github.com/pierridotite/mobile-agent-testers
1. Tell the user the rules before anything else
- Runners are free only for public repos (about 20 jobs at once, 5 on macOS, on the Free plan; check GitHub's current docs). In a private repo, macOS minutes count 10x.
- GitHub's terms reserve hosted runners for the project of the repository. Fine: open-source app, or testers inside the app's own repo. Grey zone: pulling a closed-source app into a public repo only to get free Macs. Say so, and offer the private-repo or self-hosted alternative.
- A Claude Pro/Max subscription can be used up quickly: 20 agents at once used a 5-hour window in about 15 minutes. Recommend batches of 6-10.
- Logs of a public repo are public. The template encrypts build logs, apps, screenshots and reports. Never add a step that prints them.
2. Create the testers repo
Ask where the testers should live, then:
gh repo create <name> --public --template pierridotite/mobile-agent-testers --clone
cd <name> && ./setup.sh
The user runs setup.sh in their own terminal, not through you. It creates
the results key pair, configures the repo and pushes the public key. It asks
the user directly, in that terminal, for the Claude sign-in it needs.
Credentials rule: you never read, print, store or ask for any credential or
private key. Never open files under ~/.mobile-agent-testers/. If the user
pastes a credential into the chat, do not reuse it: tell them to revoke it and to
type the new one into the terminal prompt.
Offer the demo first (gh workflow run agent-testers.yml): it tests the
bundled Tiny Todo app, which has 11 deliberate bugs listed in
demo-app/BUGS.md, so the user can see what the agents catch.
3. Point it at the user's app
Read the app to fill the workflow inputs (give them with -f or change the
defaults in .github/workflows/agent-testers.yml):
| Input | How to find it |
|---|---|
source_repo | owner/name of the app repo (empty if the app is in the testers repo) |
ref | branch or full SHA to test |
app_dir | folder with package.json (. for most apps) |
app_id | expo.android.package in app.json, or applicationId in android/app/build.gradle. One id is enough: if the iOS bundle id differs, it is read from the built app |
If the app repo is private, point the user to the "Private repo" line of the template README: they create a read-only access for that one repo and store it themselves, in their own terminal.
The build detects the framework (scripts/build/detect.sh): Flutter, Expo,
React Native, Capacitor/Ionic, Kotlin Multiplatform, native Kotlin/Java and
Swift/Objective-C, .NET MAUI (beta). Force it with -f framework=<name> if
detection is wrong. For anything else, or to test an app that is already
built, set android_build + apk_path and ios_build + ios_app_path
(a build command or a download; paths relative to app_dir). For a native
iOS project with several schemes, set the repo variable: gh variable set IOS_SCHEME --body <scheme>.
4. Personas and brief
personas.json ships 20 personas (10 Android, 10 iOS) that cover what breaks
layouts: small phones and tablets, Android 10 to 15, text from small to
Android's 200% and iOS's largest accessibility size, dark mode, 14 languages
including Arabic (right to left), Hindi, Japanese and Chinese, and someone who
refuses permissions. Pick the ones that match the app's audience and markets,
adapt their goals to the app (no "create an account" if it has none), and add
personas for languages the app ships that are missing. Each persona has a
profile, a goal, a locale, a GPS position and a device.
Adapt AGENT_BRIEF.md to the app: what to check, how to sign up (test
accounts, success+<id>@simulator.amazonses.com for e-mails), what is out of
scope. Keep the rules "screenshot after every action" and "write
findings.json". For a quick targeted check, write a second, short brief and
run with -f brief=<file>.
Add the app's analytics and ad hosts to block_hosts so test runs never reach
production stats.
5. Run, collect, triage
gh workflow run agent-testers.yml -f android_personas=a,b -f ios_personas=c,d -f app_id=com.example.app
-f android_personas=all -f ios_personas=all runs the 20 personas (10 iOS
jobs run 5 at a time on the Free plan), and none skips a platform.
When the run ends, the user decrypts the results in their own terminal (the private key stays with them):
bash scripts/collect.sh <run id> # downloads + decrypts into runs/<id>/
Then read runs/<id>/SUMMARY.md (if the claude CLI is installed, reports that
describe the same bug are grouped, with how many personas hit each one), then
open the screenshots of each important issue before you trust it: agents
sometimes misread a screen. Check that no agent stopped on a usage limit
(collect.sh warns). Turn confirmed issues into fixes or tickets, most severe
first, and say which personas hit each one.
Sponsors
Details
- Marketplace
- pierridotite/mobile-agent-testers
- Source
- plugins/mobile-agent-testers
- Category
- Community