# Screenmap

> Screenmap automatically screenshots every screen in an Expo/React Native app during CI and posts changed screens as a pull request comment, without requiring any tests.

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.

## Features
- Automatic screenshot capture of every app screen in CI
- Pull request comment with before-and-after screen captures
- Region-aware visual diff with changed areas boxed and moved areas arrowed
- Interactive map viewer running entirely in the browser
- Deterministic flow replay via committed argent YAML flows
- Agent-driven exploration for screens with no recorded flow
- Support for Claude Code, Codex, Gemini, and OpenCode agents
- Static route parsing for expo-router and react-navigation
- Baseline map cached on a screenmaps branch in your own repo
- Suspect detection: only re-captures screens a diff can reach
- Per-screen agent notes describing what visually changed
- Flow playback with tap markers and follow camera in the viewer
- Runtime state capture: bottom sheets, modals, drawers
- EAS build fingerprint caching to skip rebuilds on JS-only PRs
- Bring-your-own simulator build via app_path input
- Monorepo support via project input
- Local mapping via /screenmap Claude Code plugin
- Configurable effort levels: deterministic, fast, balanced, thorough
- Status bar frozen at 9:41 before every screenshot for pixel-stable diffs
- Flows PR opened automatically after baseline runs

## Integrations
GitHub Actions, Expo / EAS, expo-router, react-navigation, Claude Code, OpenAI Codex, Google Gemini, OpenCode, argent (Software Mansion), iOS Simulator, xcrun simctl, Apple Vision (OCR for landing checks)

## Platforms
MACOS, LINUX, ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
v1

## Links
- Website: https://screenmap.dev
- Documentation: https://github.com/aleqsio/screenmap
- Repository: https://github.com/aleqsio/screenmap
- EveryDev.ai: https://www.everydev.ai/tools/screenmap