screenmap plugin
A plugin and GitHub Action that map every screen of an Expo, React Native or NativeScript app and flag screens a PR changed.
- 252 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The Action runs the app and a CI agent with `EXPO_TOKEN` and a provider key, and forks require `pull_request`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/screenmapDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The Action runs the app and a CI agent with `EXPO_TOKEN` and a provider key, and forks require `pull_request`.
This is third-party code. Review the repository files before installing.
What it does
screenmap runs a mobile app on a simulator, screenshots its screens and packs them into a `.scrmap` map: screenshots, routes, edges between screens and recorded tap paths. The Claude Code plugin runs as `/screenmap`, and the `--static` variant needs no simulator. The GitHub Action `aleqsio/screenmap@v1` works out affected screens in a pull request from the router and changed files, recaptures only those, and posts a comment with before and after and boxes around changes. Recorded paths live in the repository and replay without a model, and an agent steps in only for screens with no recording. Screenshots stay on a `screenmaps` branch of your repository.
Who it is for. Mobile teams on Expo, React Native and NativeScript whose reviewers skip the visual half of pull request changes.
Good fit when
- A new developer wants to learn which screens exist in an unfamiliar app.
- A button moved in a pull request and the reviewer needs before and after shots.
- A designer gets the map of all screens with recorded paths to them.
- A path to a screen is saved in the repo and replayed in CI without a model.
- The team map is refreshed on every push to the main branch.
Not a fit when
- The app is native Swift or Kotlin with no Expo, React Native or NativeScript.
- You need an automated gate that blocks merging: screenmap only reports.
- Routes cannot be read from files or a navigation map and screens are registered without addresses.
Example request
Run /screenmap --static and list the app screens with their routes.Limitations
A readable router is required: expo-router, a react-navigation map or a NativeScript page tree. Screens without addresses appear only through agent exploration. iOS needs macOS with a simulator, Android an emulator, and CI runs one platform per job. Recorded paths are stored per platform. On Linux text recognition uses tesseract and recovers fewer words than Apple Vision. EAS builds need an `EXPO_TOKEN` secret, and the CI agent uses the key of the chosen provider within a run budget.
How to disable. Remove the plugin through the Claude Code plugin manager and the workflow file that uses `aleqsio/screenmap@v1`. Delete the `.screenmap/out/` directory and the `screenmaps` branch by hand.
FAQ
Is a simulator required?
For a full map yes: an iOS simulator on macOS or an Android emulator via `--platform android`. The `/screenmap --static` mode builds a map without a simulator.
Does it block merging?
No. By design it reports rather than gates, and the decision stays with the reviewer.
Where do screenshots live?
Per the README, on a `screenmaps` branch of your repository, and the Action runs in your own GitHub Actions.
Which event should run the Action?
`pull_request`, not `pull_request_target`, because the latter hands a fork the write token and secrets.
What does the Action need?
An app with `expo-dev-client` and addressable routes, an EAS profile for a simulator build (a prebuilt `.app` or `.apk` for NativeScript) and a provider key for the CI agent.
Discussion
No questions or reviews yet.
Related
PluginsA Callstack plugin that shows simulators and devices beside the agent chat and lets it control the mobile app.
A Claude Code skill that builds Expo mobile apps with onboarding, paid subscriptions, AdMob ads, analytics and localization.
CLI for parallel React Native work on macOS: slimmed simulators, leased Metro ports and per-agent device tracking.
An opencode fork for mobile development: the agent runs the iOS simulator or Android emulator and shows the device alongside
Evan Bacon's skill teaches an agent to add widgets, App Clips, Safari extensions and other native Apple targets to an Expo app
A plugin and MCP server that give an agent annotations on the iOS Simulator screen: element, screen, search strings, two shots.
README in short
The main branch baseline map is cached, so a pull request captures only its own side of affected screens. The comment shows the changed region and a link to the viewer.