Android emulator and iOS Simulator · No SDK, no test IDs, no source code
Why · Get started · How it works · Agent and MCP · Dashboard · Docs
appscreenmap crawl --apk app.apk # explore the app, then run `appscreenmap` to browse the mapNote
Early alpha: the project is under active development and commands may change.
Ask a team "how many screens does your app have, and how do I reach checkout?" and you get a guess. The answer lives in someone's head, a stale design file, or a test suite that breaks every sprint. AppScreenMap walks through the build you already ship, taps every screen it can reach and writes it down, so the answer is a file you can query, diff and build on.
| You get | Which means |
|---|---|
| A complete screen inventory | Know what is in the build, including screens nobody remembers |
| Routes to every screen | "How do I reach Settings?" is a lookup, for you and for your agent |
| A diff between builds | Added, removed and changed screens before release, not after |
| Android and iOS | One command explores the build on an emulator or Simulator, no scripting |
| Exports you can use | Test flows, one per screen (Maestro format), a Mermaid graph, a one-file SVG map you can drop into Figma, a WCAG report |
| Audits, not just a map | WCAG 2.2, performance, store deadlines and security, with the fix and an official source. They read the app and its APK or app bundle, no source code needed |
| A CI gate | verify replays every path on a new build and fails the job if one breaks |
| An MCP server for your agent | Your agent knows the app without re-exploring it: find a screen, get the route, go there |
And it asks nothing of your app:
- Zero app changes. No SDK, no test IDs, no source. Works on any mobile app, native or cross-platform (Jetpack Compose, React Native, SwiftUI), even with almost no resource ids.
- Deterministic. No model calls while it explores: same build and config, same map, so a regression is a diff.
- Local and safe. Nothing leaves your machine. It stays in the app and never taps log out, delete or pay, in 24 languages.
- Agent-native. A local MCP server and skills for Claude Code or any MCP client.
Needs macOS, uv, Bun, and an Android emulator or device (adb),
or Xcode with a booted Simulator for iOS.
git clone https://github.com/MKS-01/appscreenmap && cd appscreenmap
make install # engine, dashboard and the `appscreenmap` command
appscreenmap setup # checks adb, devices, simulators; says what is missing
appscreenmap crawl --apk app.apk # explore the app
appscreenmap # terminal home + dashboardNo app handy? Press x in the terminal home to map the Playground sample app.
Output is a run folder of plain files (map.json, screens/, flows/, a11y.json, perf.json, reports);
map.json is a versioned contract, see docs/MAP_SCHEMA.md.
To map the app in another language, add --locale fr-FR (or ja, ar, …). Android 13+; on iOS the app is relaunched.
appscreenmap --help lists every command; after pulling new code, run make install again.
Everything runs through your AI agent. Press t in the terminal home for a new terminal in the same folder, run
claude, and ask in plain language:
Map my app on the emulator and review the map.
Audit accessibility on the latest run at WCAG 2.2 AA.
Map the new build and compare it with the last run.
Two screens got merged in the last map. Fix it and map again.
The agent works through the MCP server, so it answers from the map instead of exploring the app again, and its work shows up live in the dashboard:
You: How do I reach Settings?
Agent →route("Settings"): From launch: tap Profile, then tap Settings. Here is the test flow.
You: Take the emulator there.
Agent →go_to_screen("Settings")→where_am_i(): Done, the device is on Settings.
appscreenmap mcp serves your mapped runs to any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, …). It
is a local stdio server: it reads runs/ on your machine and talks to your emulator or Simulator, with no account,
no API key and no network calls.
claude mcp add appscreenmap -- appscreenmap mcpOther clients take the same command in their MCP config:
{ "mcpServers": { "appscreenmap": { "command": "appscreenmap", "args": ["mcp"] } } }Options: --runs <dir> (default ./runs), --run <run-id> (default: the latest finished run), --serial <device>.
| Tool | Answers | Kind |
|---|---|---|
list_runs, list_screens, find_screens |
What has been mapped; which screen is "Settings" or has a "Save" button | read-only |
get_screen, screenshot |
One screen: elements and where each leads, how to reach it, findings, load time, image | read-only |
route |
Steps to a screen, from launch or another screen (with its test flow) | read-only |
a11y_findings, perf_summary |
Which screens fail which WCAG 2.2 criteria; which are slow | read-only |
where_am_i |
Which mapped screen the device shows now | read-only |
go_to_screen |
Drive the device to a screen along its route | drives the device |
crawl, crawl_status |
Map an app (or a new build) in the background, and follow it | drives the device |
Tools carry MCP annotations (readOnlyHint, destructiveHint), so clients can ask before the two that drive the
device. More in docs/SETUP.md.
Skills teach the agent the jobs around mapping an app:
| Job | Skill |
|---|---|
| Map an app and review the result | crawl-app, tune-crawler |
| Accessibility (WCAG 2.2) | a11y-audit |
| iOS Simulator setup | ios-simulator |
| Store deadlines (Play target API, App Store SDK) | store-requirements |
| Test export | add-exporter |
- Drive. The engine talks to the device over
adb(Android) orsimctl+idb(iOS Simulator), pinned to your app so it cannot wander into other apps. - Observe. Each step captures a screenshot and the UI hierarchy (
uiautomatoron Android). - Identify. The analyzer fingerprints the layout and ignores list contents and digits (clocks, counters), so a list with new rows is the same screen and a different layout is a new one. That keeps the map stable across runs.
- Act. The explorer picks the next tap, scroll or text entry. It recognises tabs, lists, forms, dialogs and login screens, and skips destructive actions (log out, delete, pay).
- Record. Screens and transitions go to
map.json; the audits read the same files.
Your agent sits above this loop: it starts runs, reads the health report, fixes config and maps again. See docs/ARCHITECTURE.md for the details.
appscreenmap serve opens it on runs/. No backend; it updates live while it maps.
- Insights: scored audits with findings, fixes and official sources
- Map: every screen as a tree, graph or storyboard. Comment, add planned screens, rename, move or remove; edits go in
notes.jsonand the mapped data is never touched - Screens: search, tappable overlays, transitions, the test flow
- Accessibility: findings per rule with screenshots; triage them, export a WCAG 2.2 report
- Compare: what changed between two builds
- Crawl replay: step through what was tapped and why
The map exports as one self-contained SVG with every screenshot inside: send it to a teammate, open it in a browser or drop it into Figma.
Export Markdown or CSV from the dashboard, or take the files straight from the run: test flows (flows/, Maestro format), a
Mermaid graph (map.mmd), a one-file WCAG report (a11y-report.html, evidence not a conformance claim), and
map.json / a11y.json / perf.json for your own tooling.
| Feature | Status | What you get |
|---|---|---|
| Android screen map | ✅ Ready | Every screen and route from an emulator or device, without leaving your app |
| Dashboard | ✅ Ready | Map, screens, crawl replay and build compare, live while it maps |
| Accessibility audit | ✅ Ready | WCAG 2.2 findings with screenshots, fixes and a shareable report |
| Performance | ✅ Ready | Load time per screen, jank and cold start |
verify CI gate |
✅ Ready | Replays every path on a new build and fails the job if one breaks |
| Exports | ✅ Ready | Test flows (Maestro format), Mermaid graph and a one-file SVG of the map |
| MCP server and agent skills | ✅ Ready | Ask your AI agent to map, audit and compare |
| Store readiness | ✅ Ready | Play and App Store SDK deadlines for the next 365 days |
| iOS Simulator | 🧪 Beta | Same map on iOS; see the ios-simulator skill |
| Security audit | 🧪 Beta | 18 of 19 rules on Android and iOS builds; see the security-audit skill |
| Adaptive UI review | 🚧 Coming soon | Check every screen at phone, tablet and foldable sizes |
Audit rules (WCAG, security, Play and App Store) are updated as the official guidance changes.
Open source under the MIT License. © 2026 MKS and AppScreenMap contributors.
Built with Claude Code.