tapp

# Tapp

[![CI](https://github.com/aarwitz/tapp/actions/workflows/ci.yml/badge.svg)](https://github.com/aarwitz/tapp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40aarwitz%2Ftapp?color=cb3837&label=npm)](https://www.npmjs.com/package/@aarwitz/tapp)
[![npm downloads](https://img.shields.io/npm/dw/%40aarwitz%2Ftapp?label=downloads)](https://www.npmjs.com/package/@aarwitz/tapp)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
[![Agent Skill](https://img.shields.io/badge/Agent_Skill-install-6b5cff)](https://skills.sh/aarwitz/tapp)
[![VS Code extension](https://img.shields.io/badge/VS_Code-extension-0098FF)](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp)
[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHBAbGF0ZXN0IiwibWNwIl19)
[![VS Code MCP](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=tapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40aarwitz%2Ftapp%40latest%22%2C%22mcp%22%5D%7D)

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

[![A real Tapp focus run reaches Update Profile from source and an observed route](https://runtapp.com/assets/tapp-focus-proof.png)](https://runtapp.com/#proof)

**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](https://runtapp.com/assets/tapp-explore-ios.mp4)
or [inspect a complete sanitized web evidence report](https://runtapp.com/evidence/webdemo/report.html).

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 (beta) | Owned browser app in Playwright Chromium |

Windows can host Android and web testing when their prerequisites are installed. Windows desktop
UI applications such as WinForms, WPF, and WinUI are not currently Tapp targets.

## 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):**

```bash
npx -y skills add aarwitz/tapp --skill tapp
```

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:**

```bash
claude plugin marketplace add aarwitz/tapp
claude plugin install tapp@tapp
```

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:

```bash
npx -y @aarwitz/tapp@latest init . --explore
```

**VS Code:** install [Tapp from the Marketplace](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp).
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](https://github.com/aarwitz/tapp/issues/new?template=founding-pilot.yml).

```
you:    "Add a logout button to the settings screen"
agent:  *writes the Swift*
agent:  *tapp: finds Settings in source, follows its previously observed route, screenshots it*
agent:  "Done — and here it is working on the simulator: [screenshot]"
```

## 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:

```bash
npx -y @aarwitz/tapp@latest init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json
npx -y @aarwitz/tapp@latest open            # one current screen + screenshot
npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" # source + observed-route fast path
npx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)
```

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:

```bash
npx -y @aarwitz/tapp@latest init . --dry-run --json-out /tmp/tapp-init.json
# Build/start the detected web target, ground the first UI Map, then stop it.
npx -y @aarwitz/tapp@latest init . --explore --platform web
# Or build/install the detected Xcode target, ground the map, and persist the validated scheme.
npx -y @aarwitz/tapp@latest init . --explore --platform ios --target .
# Or connect to an already-running owned URL:
npx -y @aarwitz/tapp@latest init . --explore --platform web --url http://127.0.0.1:4173
# If the app has roles/accounts, bind names once; values stay in local/CI secrets.
npx -y @aarwitz/tapp@latest actor set alice . --role member --session isolated \
  --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD
# Review-only path: tapp init . → tapp plan show → tapp plan review --approve ...

# After approved drafts replay and are promoted, establish the selected target's baseline
# through the ordinary full gate, then generate the reviewable GitHub workflow.
npx -y @aarwitz/tapp@latest baseline create . --platform web
npx -y @aarwitz/tapp@latest ci install .
```

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:

```bash
npx -y @aarwitz/tapp@latest open [target]   # launch the app → screen summary + screenshot file
npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree of the current screen
npx -y @aarwitz/tapp@latest shot