AppScreenMap

Your app's screens and routes, mapped by crawling it. No SDK, no test IDs, no source.
Point it at a build. It explores on an emulator and writes every screen and transition as plain files
your tests, audits, CI and AI agent can use.

Why · Get started · How it works · Agent · Dashboard · Docs

appscreenmap crawl --apk app.apk   # explore the app, then run `appscreenmap` to browse the map

Note

Early alpha. Commands and flags may change. iOS is beta. Adaptive UI review is planned, and the security audit covers 18 of its 19 rules (see Roadmap).

Why

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 crawls the build you already ship 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
Generated Maestro flows	A starting E2E suite, one flow per screen
WCAG 2.2 and performance audits	Every screen checked, with the fix and an official source
A CI gate	verify replays every path on a new build and fails the job if one breaks

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 in the crawl: 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.
• Agent-native. An MCP server and skills for Claude Code or any MCP client.

Get started

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 + dashboard

No 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.

How it works

1. Drive. The engine talks to the device over adb (Android) or simctl + idb (iOS Simulator), pinned to your app so a crawl cannot wander into other apps.
2. Observe. Each step captures a screenshot and the UI hierarchy (uiautomator on Android).
3. 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.
4. 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).
5. 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 re-crawls. See docs/ARCHITECTURE.md for the details.

Use it with an 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. Crawl the new build and compare it with the last run. The last crawl merged two screens. Fix it and crawl again.

Its work shows up live in the dashboard. Any MCP client can query the maps too (find a screen, get the route, drive the device there, read findings):

claude mcp add appscreenmap -- appscreenmap mcp

Job	Skill
Map and review a crawl	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

Dashboard

appscreenmap serve opens it on runs/. No backend; it updates live during a crawl.

• Insights: scored audits with findings, fixes and official sources
• Map: every screen as a tree, graph or storyboard
• Screens: search, tappable overlays, transitions, the Maestro 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

Export Markdown or CSV from the dashboard, or take the files straight from the run: Maestro flows (flows/), 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.

Commands

Command	Does
crawl --apk app.apk	Install and explore (--clear-data for first run, --config for logins)
report <run>	Crawl health: wasted steps, merged screens
a11y <run> --report	WCAG 2.2 checks and report
perf <run>	Load time, jank, cold start
security <run> --apk app.apk	Manifest, code, secrets and data-at-rest checks (--app for an iOS build)
store [run] --apk app.apk · --app App.ipa	Target / compile / min SDK (Android) or build SDK and deployment target (iOS) against Google Play and App Store rules, with every deadline in the next 365 days. A crawl writes it too
export <run> --svg	The whole map as one SVG (--layout tree|graph|storyboard, --theme light|dark): opens in a browser, drag it into Figma
verify	Replay paths on a new build; exit codes for CI
serve · mcp	Dashboard · MCP server

Run as appscreenmap <command>. More: appscreenmap --help, docs/SETUP.md.

After pulling new code, run make install again to rebuild the appscreenmap command. The agent skills from Google's android/skills stay current with make skills-check and make skills-sync, and Apple's Xcode 27 skills with make skills-xcode.

Roadmap

Details in docs/PLAN.md.

Planned	What it will do	Today
Adaptive UI review	Crawl at phone, tablet and foldable window sizes (compact, medium, expanded width classes) and check each layout against Android's adaptive-layout guidance	Only manifest orientation locks and the crawl's window class are real; shows as "sample data" in the dashboard
Security audit, remaining rule	Sensitive data in logs (sensitive-logging), and confirming code findings instead of only matching strings	appscreenmap security works today on Android (--apk) and iOS (--app): manifest and Info.plist flags, risky API use in the code, hard-coded secrets, data at rest, and runtime pinning and cleartext checks from a Frida log (18 of 19 rules). See the security-audit skill

Also planned: platform-change checks per Android/iOS release. Store readiness (target SDK and build SDK deadlines) is built: appscreenmap store.

License

MIT © 2026 MKS and AppScreenMap contributors.