appscreenmap

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

[!NOTE] Early alpha: the project is under active development and commands may change.

Know your app

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 and writes every screen down, so the answer is a file you can query, diff and build on.

• What is in this build? A complete screen inventory, including screens nobody remembers.
• How do I reach Settings? A route to every screen, for you and for your agent.
• What changed since the last release? Added, removed and changed screens, before release.
• Is it accessible, fast, secure, store-ready? WCAG 2.2, performance, store deadlines and security, each with the fix and an official source.
• What does the app talk to? The hosts it calls and its own log lines, tied to the screen you were on (crawl --network, watch).
• Did this build break a path? verify replays every path and fails the CI job if one is gone.

It makes no model calls while it explores, so the same build gives the same map, and nothing leaves your machine. Android and iOS (iOS is beta).

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: docs/MAP_SCHEMA.md.
• Another language: add --locale fr-FR (or ja, ar, …). Android 13+; on iOS the app is relaunched.
• Commands: appscreenmap --help lists them all. After pulling new code, run make install again.

AI agent and MCP

Everything can run 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.

Connect

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 mcp

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

Tools

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	Map an app (or a new build) in the background	drives the device
crawl_status	Follow a running map	read-only

Tools carry MCP annotations (readOnlyHint, destructiveHint), so clients can ask before go_to_screen and crawl, the two that drive the device. More in docs/SETUP.md.

Dashboard

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, file screens the crawl missed, rename, move or remove; edits go in notes.json and 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
• Network · Logs: the hosts the app called and its own log lines, with sessions you recorded by hand
• Compare: what changed between two builds
• Crawl replay: step through what was tapped and why

Export the map as one self-contained SVG (every screenshot inside) or Markdown/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.

License

Open source under the MIT License. © 2026 MKS and AppScreenMap contributors.

Built with Claude Code.