Screenmap

Screenmap is an MIT-licensed GitHub Action and Claude Code plugin built by Aleksander Mikucki that maps every screen in an Expo or React Native app and shows reviewers exactly which screens a pull request changed. It runs on macOS CI runners, captures screenshots via an iOS simulator, and posts a sticky comment on each pull request with before-and-after images of affected screens and a link to an interactive map viewer.

What It Is

Screenmap fills the gap that exists in mobile code review: web pull requests get preview URLs, but mobile pull requests typically get a QR code and a build to install, leaving reviewers to find the changed screen on their own. Screenmap closes that gap by running the app in CI, working out which routes a diff can reach, capturing those screens on a simulator, and posting them directly into the review. It is MIT licensed, runs entirely in your own GitHub Actions, and keeps every screenshot on a branch in your own repository.

How the Three-Lane Architecture Works

Screenmap separates work into a deterministic lane and an agent lane, with a third path for local use:

• Deterministic lane — parses expo-router file conventions or react-navigation route maps, replays committed argent YAML flows headlessly, deep-links remaining routes, and diffs captures against a cached baseline. No LLM tokens are spent.
• Agent lane — a headless coding agent (Claude Code by default, with presets for Codex, Gemini, and OpenCode) explores screens that have no recorded flow, writes tap paths as replayable YAML flows, and adds per-screen notes describing what visually changed. The agent budget is capped per run.
• Local plugin — the same pipeline runs as a /screenmap Claude Code plugin for mapping an unfamiliar app on your own machine before wiring up CI.

Once a flow is committed to .screenmap/flows/, that screen replays deterministically on every future run with no agent involvement and no tokens spent.

What the PR Comment Shows

Each pull request comment includes before-and-after captures of every affected screen, a region-aware visual diff that boxes changed areas and draws arrows for moved elements, a short agent-written note per screen describing what visually moved, and a link to the hosted viewer preloaded with the baseline map and the changes overlay. The viewer at app.screenmap.dev runs entirely in the browser — no uploads — and supports flow playback with tap markers, per-screen state pickers, and a minimap.

Setup Path

Setup requires an Expo or React Native app using expo-router or a react-navigation route map, an EAS simulator build profile (or a prebuilt .app), and macOS runner minutes. Two workflow files from the action/templates/ directory are copied into .github/workflows/: one for PR runs and one for keeping the baseline map of main fresh. An optional .screenmap/config.json supplies real route parameter values, device choice, agent budget, and timing knobs. An optional .screenmap/SKILL.md tells the agent how to log in, which controls to avoid, and how long slow screens take to settle.

Tradeoffs to Know

• iOS only — Android is not yet supported; the interactive phases require a macOS host with the iOS simulator.
• macOS runner cost — macOS GitHub Actions runners bill at ten times the Linux rate; the project documentation states a JavaScript-only PR run takes about 12 minutes.
• Reports, does not gate — there is no pass/fail check by design; a reviewer decides what the screenshots mean.
• Router dependency — screens registered without URLs are invisible to the static parse and only appear through agent exploration.
• Edge extraction is regex-based — dynamic hrefs resolve to their route pattern rather than resolved values.

Current Status

The repository was created in August 2026 and last pushed on 2026-08-28, with 105 stars and 8 forks at time of indexing. The project is actively developed under the MIT license by Aleksander Mikucki, with flow replay powered by argent (Software Mansion). A hosted simulator option via argent cloud and Expo is listed as coming soon on the project homepage, which would allow running Screenmap without a macOS runner.