Tapp README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Tapp listing page.
Tapp
Tapp lets coding agents verify UI changes on real iOS, Android, and web surfaces, then turns reviewed proof into deterministic CI checks. It can inspect and drive screens, explore for technical failures, and save important journeys as replayable tests.
Exploration reports findings, coverage, evidence, and limits. Only the repository-connected gate
returns pass, fail, or inconclusive. Tapp does not turn an autonomous crawl into a subjective
"ship-ready" score.
Real evidence, not a mock: this public DemoApp run reached the requested iOS surface in three observed route actions. Watch 45 seconds of autonomous exploration or inspect a complete sanitized web evidence report.
Supported targets:
| Target app | Runtime |
|---|---|
| iOS | Simulator on macOS with Xcode; driven through XCUITest and accessibility |
| Android | Connected emulator or device with adb; driven through UIAutomator |
| Web | Owned browser app in Playwright Chromium |
| Windows desktop | WPF, WinForms, and WinUI apps through Windows UI Automation — early runs are set up through the pilot |
Windows hosts Android and web testing when their prerequisites are installed, and is the home of the Windows desktop target.
Give Tapp to your coding agent
After setup, the whole user prompt is:
Use Tapp to test this app.
The official skill teaches the agent to choose the smallest useful operation, handle repositories with multiple app targets, inspect visual evidence, and keep exploration observations separate from gate decisions.
Claude Code, Codex, Cursor, Copilot, and other Agent Skills clients (recommended):
This installs the open Agent Skills workflow into the current project and lets the agent run the npm
CLI directly. Inspecting, focused evidence, autonomous exploration, deterministic replay, and gating
need no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block. Add -g
for a user-wide install, or --agent claude-code, --agent codex, and similar selectors to constrain
the clients. Start or restart the agent from the application repository and use the short prompt
above.
Claude Code — optional enhanced skill and MCP tools:
The plugin bundles the same tapp Agent Skill with the matching npm-backed MCP server. Add it when
you want inline screenshot results or when the agent must interactively tap, type, and record an
arbitrary multi-step journey in one persistent session. It is not required for the core
skill-to-CLI workflow.
No agent integration: run the npm package directly from an app repository in one line:
VS Code: install Tapp from the Marketplace. It contributes the same cross-platform Agent Skill to Copilot plus focused iOS simulator tools and an auto-refreshing screenshot preview. The preview is not an embedded Simulator or video stream. Android and web remain available through the skill's CLI/MCP workflow.
Teams: Tapp's core stays MIT licensed. A small paid founding pilot is open for hands-on repository onboarding, important-journey setup, and CI integration in infrastructure you control. Apply without sharing private data.
npm CLI quickstart
Requirements: Node ≥ 18. iOS needs macOS + Xcode; Android needs adb plus a connected
emulator/device (and JDK 17 when Tapp builds source rather than installing an existing APK); web
needs Playwright + Chromium. tapp doctor reports these separately.
From the app repository, ground Tapp once, then use the smallest operation for later checks:
Source tells focus where the requested UI likely lives; only a route already observed in
.tapp/ui-map.json authorizes navigation. If a fresh repository has no such route yet, Tapp returns
the source evidence instead of guessing through the app.
Claude Code can read the saved image with its file-reading tool; Codex can open it with
view_image. The agent should report what the screenshot proves, relay the exploration findings
as-is (an observation, not a merge decision — tapp ci gates that), and link the HTML evidence
report. No Tapp server, account, global install, API key, or bundle id is required for this loop.
The platform runtime still needs to be installed, and repository onboarding can write reviewed
configuration under .tapp/.
The product, executable, and package leaf are all Tapp: npm distributes it as
@aarwitz/tapp, while the installed command remains tapp.
To bootstrap maintained release infrastructure, preview the repository model and grounded plan before Tapp writes anything:
Actor setup refuses to overwrite an existing actor. Repeat actor set with --replace only when
you intend to replace that actor's reviewed role, session, provisioning, or credential bindings.
In a repository containing multiple apps (for example, iOS plus web),
tapp init . --explore without an explicit target does not guess from detection order—even when a
prior choice is recorded. A human terminal gets a numbered
selector; a non-interactive CLI prints exact target-selection commands, while MCP also returns
structured choices. Neither builds or writes before the choice. After you choose one, the model
retains every detected target and records the choice as the default for the next bare tapp explore;
explicit init --explore continues to ask because it is the onboarding/refresh operation. Setup gaps
belonging only to unselected targets are shown as informational, not as failures of the selected run.
The baseline command writes only after exploration and every selected deterministic suite pass
conclusively. It stores .tapp/baselines/<platform>/<target-id>.json; the generated workflow
uses that exact target identity so two apps on the same platform never share a baseline. ci install writes .github/workflows/tapp.yml plus .tapp/ci.json, refuses unresolved build
configuration and existing-file collisions, and never commits, pushes, enables branch protection,
or creates GitHub resources. Review and pin the generated Tapp release reference to its immutable
commit SHA before production.
Every verb takes whatever you have: nothing (auto-detects the repo you're in, or the app
already on the simulator), a repo directory, a path/to/App.app, or a bundle id:
Web: npx -y @aarwitz/tapp@latest explore http://localhost:3000 (one-time setup:
npm i -g playwright && npx playwright install chromium). Add --watch to open Tapp's controlled,
isolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that
watch UI from saved evidence screenshots and does not automate your personal/default browser profile.
Focused web inspection waits briefly for loading states to settle. If a consent or location modal blocks the screen, dismiss it and wait for the content you care about in the same package-only call:
Android:
Turn a driven journey into a deterministic test, or print the complete Flow format before writing one by hand:
Flows support an atomic login step using $TEST_EMAIL / $TEST_PASSWORD; Tapp's session recorder
creates that step without writing credential values into the repository.
Optional but recommended (prebuilds the test harness so the first run is fast):
MCP hookup (optional)
The MCP server adds the two things a CLI can't do: screenshots inline in your agent's context (the model literally sees the screen) and the interactive session loop (tap → read tree → type, with the app staying open between actions).
Claude Code:
Cursor / VS Code (Copilot) — add to ~/.cursor/mcp.json (Cursor) or .vscode/mcp.json (VS Code):
Codex CLI — add to ~/.codex/config.toml:
Any other MCP client: stdio command npx -y @aarwitz/tapp@latest mcp.
Then ask your agent:
"Explore my app and show me what breaks." "Open com.mycompany.app on the simulator and screenshot the home screen." "Log in with test@example.com, drive to checkout, and record it as a replayable test."
What the agent gets
| Tool | What it does | |
|---|---|---|
| 👁 | tapp_open_app | See a screen — launch the app, return screenshot + accessibility tree. Seconds. |
| 📸 | tapp_screenshot | Whatever's on the sim right now, as an inline image. |
| 🌳 | tapp_ui_tree | The accessibility tree of the current screen (ids, labels, hittability). |
| 🕹 | tapp_session_start/act/end | Interactive driving — the Playwright loop. App launches once; each act (tap/type/swipe/back/wait) returns the fresh tree. |
| 🔭 | tapp_explore | Autonomous exploration — explores with no authored test, returns an observation {kind, headline, inconclusive, findingCounts, findings[]} (no verdict/score — the deterministic gate judges). Takes appBundleId (iOS), androidAppId (Android), or url (web). |
| 🧭 | tapp_init | Repository import — detect targets; optionally explore a real surface; persist the shared UI Map; construct the evidence-classified model and grounded release plan. |
| 👤 | tapp_actor_config | Actor/session setup — store roles, isolation/provisioning, and environment-variable names without accepting or persisting credential values. |
| ✅ | tapp_release_plan | Release-plan lifecycle — inspect, approve/reject/defer, generate, real-target validate, and explicitly promote proposed guarantees without silent test edits. |
| 🚦 | tapp_ci_setup | Baseline and CI setup — import a conclusive target baseline or render/install the same reviewable target-aware workflow as the CLI. |
| 🗺️ | tapp_ui_map | Persistent UI Map — build, inspect, merge, and diff observed states, controls, transitions, provenance, and coverage. |
| 🧩 | tapp_task | Reusable deterministic Tasks — validate and compile shared actions such as signIn against the UI Map; replay stays keyless. |
| 📜 | tapp_release_contract | Business-level release contracts — validate, compile, or run typed guarantees composed from Tasks and named actors. |
| 📋 | tapp_pr_plan | PR-aware evolution — select reviewed contracts, schedule bounded changed-surface exploration, and explicitly adopt observed coverage proposals without silent rewrites. |
| 🔁 | tapp_flow_run / flow_save / flow_generate | Deterministic E2E execution (Flows) — raw steps or reusable Task calls replay with exact assertions. |
| 👥 | tapp_scenario_run | Multi-actor system tests — isolated named browser sessions verify cross-account state with deterministic assertions. No AI at replay time. |
| 📱 | tapp_list_simulators / boot_simulator / install_app | Simulator + app management. |
| 🩺 | tapp_health, tapp_capture*, tapp_parse_markers | Diagnostics and capture history. |
Canonical installable skill: skills/tapp/SKILL.md. Full low-level tool
reference: AGENTS.md. Both ship inside the npm package; installing the Claude plugin
or Agent Skill is what makes the workflow discoverable without pasting instructions.
Application-model and import contract: docs/application-model.md.
The desktop Coverage view reads the same .tapp/application-model.json,
.tapp/release-plan.json, and .tapp/ui-map.json, including explicit proposal review; it
does not maintain a separate product model. Map nodes identify both the real launch entry and the
deterministic per-platform navigation root used for bounded changed-surface replay.
Observation you can read, judgment you can trust
Exploration observes; the gate judges. Exploration is adaptive — two runs may traverse different
paths — and it produces an observation, never a ship verdict: findings + coverage + evidence. The
gate is deterministic: the same evidence trace, contracts, and baseline always produce the same
outcome — pass, fail, or inconclusive — with no LLM in the decision loop. PR gating keys on the
regression diff (stable finding signatures vs. a baseline), so it reacts to what changed, not to
run-to-run path variance. For critical user journeys, committed Tasks and Flows provide the stable
CI suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state,
bounded timeouts, and evidence on failure. We call this flake-resistant, not magically flake-free —
backend outages, unstable test data, and poorly identified controls can still make any E2E test fail.
No scores, no soft verdicts. Exploration reports deterministic findings, advisory budget-capped control probes, and concrete coverage — never a 0–100 number or a "ready/ship" label a shallow crawl can't honestly earn. The merge decision comes only from the gate: reviewed contracts, committed Flows/Scenarios, and baseline regressions.
tapp_explore explores like a user — accessibility surfaces on iOS/Android and a real browser on web
— and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests, broken
links and assets, and visible placeholder links with no destination). The observation is honest about
its limits:
- It surfaces findings; it does not pronounce "ready." A shallow run is never a pass — if the
app crashed on launch or a login wall blocked exploration, you get
inconclusive: true, not a false green. Absence of findings is not a pass. - The gate turns findings + coverage + your reviewed contracts + a baseline into
pass/fail/inconclusive(inconclusivefails closed). Deterministic — no LLM in the run loop. - An exploratory crawl explicitly excludes content/claim accuracy, privacy and API data minimization, brand/SEO consistency, and subjective visual credibility. Those require reviewed contracts, privacy review, or human/vision judgment; a crawl must not imply they were validated.
For a business guarantee such as “every coach is insured,” use a deterministic app-owned verifier endpoint that returns success only when the invariant holds, then require that status and the customer-visible claim in a release contract. The current DSL does not yet read arbitrary JSON response bodies or compare a cross-origin API payload directly with page copy; use a verifier or an explicit CI preflight rather than assuming exploration inferred the guarantee.
Apps behind a login? Pass testEmail/testPassword (typed into the login form automatically),
appLaunchArgs (e.g. ["--uitesting"] if your app supports a bypass), or explicit loginSteps
for custom login UIs.
CI gate
The same engine runs as a merge gate — explore on every PR, replay committed release contracts, Flows, and multi-actor Scenarios, diff findings against the last conclusive default-branch run, fail on regressions, post a sticky PR comment, and upload screenshots, the recording, and machine-readable JSON:
On pull requests, the Action automatically reads the complete changed-file set from GitHub,
retaining old and new paths for renames. It always runs critical/policy.always contracts, adds
contracts related through reviewed source ownership, the UI Map, and transitive Task composition,
and records skipped contracts and coverage gaps in tapp-pr-plan.json. A selected contract that
does not execute blocks the merge. Set pr-selection: "false" only when intentionally running the
full contract set.
Changed weakly covered surfaces are not limited to direct web URLs. Reviewed Task source ownership can compile one bounded native target (or up to five web targets) through observed UI Map edges, with condition waits and stable target evidence. Missing or failed targets make the run inconclusive; Tapp does not guess a path from a screen name.
The first successful, conclusive run on main seeds a repository-scoped Actions cache and a
90-day baseline artifact. Both are keyed by platform and stable application-model target id. Pull requests automatically restore it and fail only on new
high/critical findings or broken Flows—not pre-existing debt. No baseline commit or PAT is required.
If you prefer a reviewed, durable baseline, run tapp baseline create and commit the generated
.tapp/baselines/<platform>/<target-id>.json; tapp ci install wires its explicit path into the
corresponding job. The legacy .tapp/baseline.json is still recognized. Automatic baseline restore and the PR comment need actions: read and
pull-requests: write as shown above. Secrets are unavailable to workflows from forks, so
auth-gated apps should either use a non-secret UI-testing launch argument or skip the gate for
untrusted forks.
Already build the simulator app in another job, or use another CI provider? The portable command
accepts that .app, detects its bundle id, writes report artifacts, and exits non-zero when the
gate fails:
See the self-test at .github/workflows/tapp-gate-example.yml for Flows, auth inputs, and other controls. GitHub-hosted iOS runs require a macOS runner; the first run also builds the XCUITest harness, so budget roughly 5–10 minutes depending on app size.
Android CI runs on Linux with an emulator/device already connected. The Action can build the APK or accept a prebuilt one:
For web, pass platform: web plus web-target: and Tapp uses the application model to run its
lockfile-backed install/build, start a detected package script or read-only static server, wait for
readiness, gate it, and stop it even on failure. Pass url: instead for an already-running owned
environment. Add
scenarios: .tapp/scenarios/*.yml to gate isolated cross-account journeys; see
docs/scenarios.md. Automatic
baselines are isolated by platform and target, so two same-platform apps are never compared.
Make your repo agent-verified
Drop this into your repo's AGENTS.md (read by Codex, Cursor, Copilot, Devin, Zed, …) so
your agent proves its UI work instead of claiming it:
How it works
Every driver speaks one protocol: structured OCQA_* markers (state, actions, issues,
transitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.
On iOS, a generic XCUITest harness attaches to any app by bundle id — no SDK or app code
changes — and acts through the accessibility tree. On Android, ADB + UIAutomator provide the
same black-box driver contract. On web, a deterministic Playwright crawler does the
same in a real browser. Same detectors' spirit,
same dedup, same regression gate, same honest pass/fail/inconclusive outcome. Core exploration,
evidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI
features are explicit: finding enrichment requires TAPP_ENABLE_REMOTE_AI=1 (an ambient
API key alone never changes data handling), and AI flow generation / assert_ai only run
when you invoke them; these send selected metadata (screen names, finding titles) to your
configured model provider. Runtime configuration uses TAPP_* environment variables. Repository
artifacts live under .tapp/, and desktop run configuration uses .tapp.yml. These are the only
names Tapp reads: the pre-rename .autotap/, .autotap.yml, and AUTOTAP_* inputs are no longer
supported. If you still have an old directory or config, rename it to the .tapp names in a
reviewed change—no secrets or evidence formats need to be rewritten.
Committed Flow replay, recording a driven session, autonomous exploration, exact assertions,
regression comparison, and CI gating require no API key and no coding agent at runtime. AI is
only an optional authoring/enrichment layer (tapp_flow_generate, assert_ai, finding enrichment).
The first tool call builds the harness once (~2 min, cached in ~/.tapp; rebuilt automatically
if you switch simulators). All captures land in ~/.tapp/captures/.
Feedback
Tapp accepts feedback the way agents already work: as GitHub issues on
aarwitz/tapp. tapp feedback "short title" --body "…"
(or the tapp_feedback MCP tool) drafts an issue with the version, platform availability, and latest
capture id filled in and home paths and tokens redacted; --submit files it with your authenticated
gh. Drafts are the default because issues are public — an agent should show you the draft first.
Nothing is uploaded automatically; captures stay on your machine.