{
  "markdown": "# Tapp\n\n[![CI](https://github.com/aarwitz/tapp/actions/workflows/ci.yml/badge.svg)](https://github.com/aarwitz/tapp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%40aarwitz%2Ftapp?color=cb3837&label=npm)](https://www.npmjs.com/package/@aarwitz/tapp)\n[![npm downloads](https://img.shields.io/npm/dw/%40aarwitz%2Ftapp?label=downloads)](https://www.npmjs.com/package/@aarwitz/tapp)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![Agent Skill](https://img.shields.io/badge/Agent_Skill-install-6b5cff)](https://skills.sh/aarwitz/tapp)\n[![VS Code extension](https://img.shields.io/badge/VS_Code-extension-0098FF)](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp)\n[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHBAbGF0ZXN0IiwibWNwIl19)\n[![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)\n\n**Tapp lets coding agents verify UI changes on real iOS, Android, and web surfaces, then turns\nreviewed proof into deterministic CI checks.** It can inspect and drive screens, explore for\ntechnical failures, and save important journeys as replayable tests.\n\nExploration reports findings, coverage, evidence, and limits. Only the repository-connected gate\nreturns `pass`, `fail`, or `inconclusive`. Tapp does not turn an autonomous crawl into a subjective\n\"ship-ready\" score.\n\n[![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)\n\n**Real evidence, not a mock:** this public DemoApp run reached the requested iOS surface in three\nobserved route actions. [Watch 45 seconds of autonomous exploration](https://runtapp.com/assets/tapp-explore-ios.mp4)\nor [inspect a complete sanitized web evidence report](https://runtapp.com/evidence/webdemo/report.html).\n\nSupported targets:\n\n| Target app | Runtime |\n|---|---|\n| iOS | Simulator on macOS with Xcode; driven through XCUITest and accessibility |\n| Android | Connected emulator or device with `adb`; driven through UIAutomator |\n| Web (beta) | Owned browser app in Playwright Chromium |\n\nWindows can host Android and web testing when their prerequisites are installed. Windows desktop\nUI applications such as WinForms, WPF, and WinUI are not currently Tapp targets.\n\n## Give Tapp to your coding agent\n\nAfter setup, the whole user prompt is:\n\n> Use Tapp to test this app.\n\nThe official skill teaches the agent to choose the smallest useful operation, handle repositories\nwith multiple app targets, inspect visual evidence, and keep exploration observations separate from\ngate decisions.\n\n**Claude Code, Codex, Cursor, Copilot, and other Agent Skills clients (recommended):**\n\n```bash\nnpx -y skills add aarwitz/tapp --skill tapp\n```\n\nThis installs the open Agent Skills workflow into the current project and lets the agent run the npm\nCLI directly. Inspecting, focused evidence, autonomous exploration, deterministic replay, and gating\nneed no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block. Add `-g`\nfor a user-wide install, or `--agent claude-code`, `--agent codex`, and similar selectors to constrain\nthe clients. Start or restart the agent from the application repository and use the short prompt\nabove.\n\n**Claude Code — optional enhanced skill and MCP tools:**\n\n```bash\nclaude plugin marketplace add aarwitz/tapp\nclaude plugin install tapp@tapp\n```\n\nThe plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Add it when\nyou want inline screenshot results or when the agent must interactively tap, type, and record an\narbitrary multi-step journey in one persistent session. It is not required for the core\nskill-to-CLI workflow.\n\n**No agent integration:** run the npm package directly from an app repository in one line:\n\n```bash\nnpx -y @aarwitz/tapp@latest init . --explore\n```\n\n**VS Code:** install [Tapp from the Marketplace](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp).\nIt contributes the same cross-platform Agent Skill to Copilot plus focused iOS simulator tools and\nan auto-refreshing screenshot preview. The preview is not an embedded Simulator or video stream.\nAndroid and web remain available through the skill's CLI/MCP workflow.\n\n**Teams:** Tapp's core stays MIT licensed. A small paid founding pilot is open for hands-on\nrepository onboarding, important-journey setup, and CI integration in infrastructure you control.\n[Apply without sharing private data](https://github.com/aarwitz/tapp/issues/new?template=founding-pilot.yml).\n\n```\nyou:    \"Add a logout button to the settings screen\"\nagent:  *writes the Swift*\nagent:  *tapp: finds Settings in source, follows its previously observed route, screenshots it*\nagent:  \"Done — and here it is working on the simulator: [screenshot]\"\n```\n\n## npm CLI quickstart\n\nRequirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected\nemulator/device (and JDK 17 when Tapp builds source rather than installing an existing APK); web\nneeds Playwright + Chromium. `tapp doctor` reports these separately.\n\nFrom the app repository, ground Tapp once, then use the smallest operation for later checks:\n\n```bash\nnpx -y @aarwitz/tapp@latest init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json\nnpx -y @aarwitz/tapp@latest open            # one current screen + screenshot\nnpx -y @aarwitz/tapp@latest focus \"Save storefront settings visible above keyboard\" # source + observed-route fast path\nnpx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)\n```\n\nSource tells `focus` where the requested UI likely lives; only a route already observed in\n`.tapp/ui-map.json` authorizes navigation. If a fresh repository has no such route yet, Tapp returns\nthe source evidence instead of guessing through the app.\n\nClaude Code can read the saved image with its file-reading tool; Codex can open it with\n`view_image`. The agent should report what the screenshot proves, relay the exploration findings\nas-is (an observation, not a merge decision — `tapp ci` gates that), and link the HTML evidence\nreport. No Tapp server, account, global install, API key, or bundle id is required for this loop.\nThe platform runtime still needs to be installed, and repository onboarding can write reviewed\nconfiguration under `.tapp/`.\n\nThe product, executable, and package leaf are all Tapp: npm distributes it as\n`@aarwitz/tapp`, while the installed command remains `tapp`.\n\nTo bootstrap maintained release infrastructure, preview the repository model and grounded plan\nbefore Tapp writes anything:\n\n```bash\nnpx -y @aarwitz/tapp@latest init . --dry-run --json-out /tmp/tapp-init.json\n# Build/start the detected web target, ground the first UI Map, then stop it.\nnpx -y @aarwitz/tapp@latest init . --explore --platform web\n# Or build/install the detected Xcode target, ground the map, and persist the validated scheme.\nnpx -y @aarwitz/tapp@latest init . --explore --platform ios --target .\n# Or connect to an already-running owned URL:\nnpx -y @aarwitz/tapp@latest init . --explore --platform web --url http://127.0.0.1:4173\n# If the app has roles/accounts, bind names once; values stay in local/CI secrets.\nnpx -y @aarwitz/tapp@latest actor set alice . --role member --session isolated \\\n  --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD\n# Review-only path: tapp init . → tapp plan show → tapp plan review --approve ...\n\n# After approved drafts replay and are promoted, establish the selected target's baseline\n# through the ordinary full gate, then generate the reviewable GitHub workflow.\nnpx -y @aarwitz/tapp@latest baseline create . --platform web\nnpx -y @aarwitz/tapp@latest ci install .\n```\n\nActor setup refuses to overwrite an existing actor. Repeat `actor set` with `--replace` only when\nyou intend to replace that actor's reviewed role, session, provisioning, or credential bindings.\n\nIn a repository containing multiple apps (for example, iOS plus web),\n`tapp init . --explore` without an explicit target does not guess from detection order—even when a\nprior choice is recorded. A human terminal gets a numbered\nselector; a non-interactive CLI prints exact target-selection commands, while MCP also returns\nstructured choices. Neither builds or writes before the choice. After you choose one, the model\nretains every detected target and records the choice as the default for the next bare `tapp explore`;\nexplicit `init --explore` continues to ask because it is the onboarding/refresh operation. Setup gaps\nbelonging only to unselected targets are shown as informational, not as failures of the selected run.\n\nThe baseline command writes only after exploration and every selected deterministic suite pass\nconclusively. It stores `.tapp/baselines/<platform>/<target-id>.json`; the generated workflow\nuses that exact target identity so two apps on the same platform never share a baseline. `ci\ninstall` writes `.github/workflows/tapp.yml` plus `.tapp/ci.json`, refuses unresolved build\nconfiguration and existing-file collisions, and never commits, pushes, enables branch protection,\nor creates GitHub resources. Review and pin the generated Tapp release reference to its immutable\ncommit SHA before production.\n\nEvery verb takes whatever you have: nothing (auto-detects the repo you're in, or the app\nalready on the simulator), a repo directory, a `path/to/App.app`, or a bundle id:\n\n```bash\nnpx -y @aarwitz/tapp@latest open [target]   # launch the app → screen summary + screenshot file\nnpx -y @aarwitz/tapp@latest tree [target]   # accessibility tree of the current screen\nnpx -y @aarwitz/tapp@latest shot            # screenshot the booted simulator\nnpx -y @aarwitz/tapp@latest apps            # what's installed on the simulator (names + bundle ids)\nnpx -y @aarwitz/tapp@latest build [dir]     # just build + install (scheme auto-detected)\n```\n\nWeb (beta): `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:\n`npm i -g playwright && npx playwright install chromium`)*. Add `--watch` to open Tapp's controlled,\nisolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that\nwatch UI from saved evidence screenshots and does not automate your personal/default browser profile.\n\nFocused web inspection waits briefly for loading states to settle. If a consent or location modal\nblocks the screen, dismiss it and wait for the content you care about in the same package-only call:\n\n```bash\nnpx -y @aarwitz/tapp@latest open https://example.com --tap \"Not now\" --wait-for \"Dashboard\"\nnpx -y @aarwitz/tapp@latest tree https://example.com --tap \"Not now\" --wait-for \"Dashboard\" --json\n```\n\nAndroid:\n\n```bash\nnpx -y @aarwitz/tapp@latest explore path/to/app-debug.apk --platform android --app-id com.acme.app\nnpx -y @aarwitz/tapp@latest open com.acme.app --platform android\n```\n\nTurn a driven journey into a deterministic test, or print the complete Flow format before writing\none by hand:\n\n```bash\nnpx -y @aarwitz/tapp@latest flow example\nnpx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml\nnpx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml\n```\n\nFlows support an atomic `login` step using `$TEST_EMAIL` / `$TEST_PASSWORD`; Tapp's session recorder\ncreates that step without writing credential values into the repository.\n\nOptional but recommended (prebuilds the test harness so the first run is fast):\n```bash\nnpx -y @aarwitz/tapp@latest install    # ~2 min, one time\nnpx -y @aarwitz/tapp@latest doctor     # verify Xcode / simulators / toolchain\n```\n\n### MCP hookup (optional)\n\nThe MCP server adds the two things a CLI can't do: **screenshots inline in your agent's\ncontext** (the model literally sees the screen) and the **interactive session loop**\n(tap → read tree → type, with the app staying open between actions).\n\n**Claude Code:**\n```bash\nclaude mcp add tapp -- npx -y @aarwitz/tapp@latest mcp\n```\n\n**Cursor / VS Code (Copilot)** — add to `~/.cursor/mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):\n```json\n{\n  \"servers\": {\n    \"tapp\": { \"type\": \"stdio\", \"command\": \"npx\", \"args\": [\"-y\", \"@aarwitz/tapp@latest\", \"mcp\"] }\n  }\n}\n```\n\n**Codex CLI** — add to `~/.codex/config.toml`:\n```toml\n[mcp_servers.tapp]\ncommand = \"npx\"\nargs = [\"-y\", \"@aarwitz/tapp@latest\", \"mcp\"]\n```\n\n**Any other MCP client:** stdio command `npx -y @aarwitz/tapp@latest mcp`.\n\nThen ask your agent:\n> \"Explore my app and show me what breaks.\"\n> \"Open com.mycompany.app on the simulator and screenshot the home screen.\"\n> \"Log in with test@example.com, drive to checkout, and record it as a replayable test.\"\n\n## What the agent gets\n\n| | Tool | What it does |\n|---|---|---|\n| 👁 | `tapp_open_app` | **See a screen** — launch the app, return screenshot + accessibility tree. Seconds. |\n| 📸 | `tapp_screenshot` | Whatever's on the sim right now, as an inline image. |\n| 🌳 | `tapp_ui_tree` | The accessibility tree of the current screen (ids, labels, hittability). |\n| 🕹 | `tapp_session_start/act/end` | **Interactive driving** — the Playwright loop. App launches once; each act (tap/type/swipe/back/wait) returns the fresh tree. |\n| 🔭 | `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). |\n| 🧭 | `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. |\n| 👤 | `tapp_actor_config` | **Actor/session setup** — store roles, isolation/provisioning, and environment-variable names without accepting or persisting credential values. |\n| ✅ | `tapp_release_plan` | **Release-plan lifecycle** — inspect, approve/reject/defer, generate, real-target validate, and explicitly promote proposed guarantees without silent test edits. |\n| 🚦 | `tapp_ci_setup` | **Baseline and CI setup** — import a conclusive target baseline or render/install the same reviewable target-aware workflow as the CLI. |\n| 🗺️ | `tapp_ui_map` | **Persistent UI Map** — build, inspect, merge, and diff observed states, controls, transitions, provenance, and coverage. |\n| 🧩 | `tapp_task` | **Reusable deterministic Tasks** — validate and compile shared actions such as `signIn` against the UI Map; replay stays keyless. |\n| 📜 | `tapp_release_contract` | **Business-level release contracts** — validate, compile, or run typed guarantees composed from Tasks and named actors. |\n| 📋 | `tapp_pr_plan` | **PR-aware evolution** — select reviewed contracts, schedule bounded changed-surface exploration, and explicitly adopt observed coverage proposals without silent rewrites. |\n| 🔁 | `tapp_flow_run` / `flow_save` / `flow_generate` | **Deterministic E2E execution (Flows)** — raw steps or reusable Task calls replay with exact assertions. |\n| 👥 | `tapp_scenario_run` | **Multi-actor system tests** — isolated named browser sessions verify cross-account state with deterministic assertions. No AI at replay time. |\n| 📱 | `tapp_list_simulators` / `boot_simulator` / `install_app` | Simulator + app management. |\n| 🩺 | `tapp_health`, `tapp_capture*`, `tapp_parse_markers` | Diagnostics and capture history. |\n\nCanonical installable skill: [`skills/tapp/SKILL.md`](skills/tapp/SKILL.md). Full low-level tool\nreference: [AGENTS.md](./AGENTS.md). Both ship inside the npm package; installing the Claude plugin\nor Agent Skill is what makes the workflow discoverable without pasting instructions.\nApplication-model and import contract: [`docs/application-model.md`](docs/application-model.md).\nThe desktop Coverage view reads the same `.tapp/application-model.json`,\n`.tapp/release-plan.json`, and `.tapp/ui-map.json`, including explicit proposal review; it\ndoes not maintain a separate product model. Map nodes identify both the real launch entry and the\ndeterministic per-platform navigation root used for bounded changed-surface replay.\n\n## Observation you can read, judgment you can trust\n\n**Exploration observes; the gate judges.** Exploration is adaptive — two runs may traverse different\npaths — and it produces an **observation**, never a ship verdict: findings + coverage + evidence. The\n**gate** is deterministic: the same evidence trace, contracts, and baseline always produce the same\noutcome — `pass`, `fail`, or `inconclusive` — with no LLM in the decision loop. PR gating keys on the\n**regression diff** (stable finding signatures vs. a baseline), so it reacts to what *changed*, not to\nrun-to-run path variance. For critical user journeys, committed **Tasks and Flows** provide the stable\nCI suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state,\nbounded timeouts, and evidence on failure. We call this *flake-resistant*, not magically flake-free —\nbackend outages, unstable test data, and poorly identified controls can still make any E2E test fail.\n\n**No scores, no soft verdicts.** Exploration reports deterministic findings, advisory budget-capped\ncontrol probes, and concrete coverage — never a 0–100 number or a \"ready/ship\" label a shallow crawl\ncan't honestly earn. The merge decision comes only from the gate: reviewed contracts, committed\nFlows/Scenarios, and baseline regressions.\n\n`tapp_explore` explores like a user — accessibility surfaces on iOS/Android and a real browser on web\n— and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,\nnavigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests, broken\nlinks and assets, and visible placeholder links with no destination). The observation is honest about\nits limits:\n\n- It **surfaces findings**; it does not pronounce \"ready.\" **A shallow run is never a pass** — if the\n  app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`, not a false\n  green. Absence of findings is not a pass.\n- The **gate** turns findings + coverage + your reviewed contracts + a baseline into `pass` / `fail` /\n  `inconclusive` (`inconclusive` fails closed). Deterministic — no LLM in the run loop.\n- An exploratory crawl explicitly **excludes** content/claim accuracy, privacy and API data\n  minimization, brand/SEO consistency, and subjective visual credibility. Those require reviewed\n  contracts, privacy review, or human/vision judgment; a crawl must not imply they were validated.\n\nFor a business guarantee such as “every coach is insured,” use a deterministic app-owned verifier\nendpoint that returns success only when the invariant holds, then require that status and the\ncustomer-visible claim in a release contract. The current DSL does not yet read arbitrary JSON\nresponse bodies or compare a cross-origin API payload directly with page copy; use a verifier or an\nexplicit CI preflight rather than assuming exploration inferred the guarantee.\n\nApps behind a login? Pass `testEmail`/`testPassword` (typed into the login form automatically),\n`appLaunchArgs` (e.g. `[\"--uitesting\"]` if your app supports a bypass), or explicit `loginSteps`\nfor custom login UIs.\n\n## CI gate\n\nThe same engine runs as a merge gate — explore on every PR, replay committed release contracts,\nFlows, and multi-actor Scenarios, diff findings\nagainst the last conclusive default-branch run, fail on regressions, post a sticky PR comment, and\nupload screenshots, the recording, and machine-readable JSON:\n\n```yaml\n# .github/workflows/tapp.yml\nname: Tapp release gate\non:\n  pull_request:\n  push:\n    branches: [main] # refreshes the automatic baseline after merges\n\npermissions:\n  actions: read\n  contents: read\n  pull-requests: write\n\nconcurrency:\n  group: tapp-${{ github.ref }}\n  cancel-in-progress: true\n\njobs:\n  tapp:\n    runs-on: macos-15\n    timeout-minutes: 45\n    steps:\n      - uses: actions/checkout@v4\n      - uses: aarwitz/tapp@v0.17.4 # or pin the reviewed release commit SHA\n        with:\n          project: MyApp.xcodeproj # or MyApp.xcworkspace\n          scheme: MyApp\n```\n\nOn pull requests, the Action automatically reads the complete changed-file set from GitHub,\nretaining old and new paths for renames. It always runs critical/`policy.always` contracts, adds\ncontracts related through reviewed source ownership, the UI Map, and transitive Task composition,\nand records skipped contracts and coverage gaps in `tapp-pr-plan.json`. A selected contract that\ndoes not execute blocks the merge. Set `pr-selection: \"false\"` only when intentionally running the\nfull contract set.\n\nChanged weakly covered surfaces are not limited to direct web URLs. Reviewed Task source ownership\ncan compile one bounded native target (or up to five web targets) through observed UI Map edges,\nwith condition waits and stable target evidence. Missing or failed targets make the run\ninconclusive; Tapp does not guess a path from a screen name.\n\nThe first successful, conclusive run on `main` seeds a repository-scoped Actions cache and a\n90-day baseline artifact. Both are keyed by platform and stable application-model target id. Pull requests automatically restore it and fail only on **new**\nhigh/critical findings or broken Flows—not pre-existing debt. No baseline commit or PAT is required.\nIf you prefer a reviewed, durable baseline, run `tapp baseline create` and commit the generated\n`.tapp/baselines/<platform>/<target-id>.json`; `tapp ci install` wires its explicit path into the\ncorresponding job. The legacy `.tapp/baseline.json` is still recognized. Automatic baseline restore and the PR comment need `actions: read` and\n`pull-requests: write` as shown above. Secrets are unavailable to workflows from forks, so\nauth-gated apps should either use a non-secret UI-testing launch argument or skip the gate for\nuntrusted forks.\n\nAlready build the simulator app in another job, or use another CI provider? The portable command\naccepts that `.app`, detects its bundle id, writes report artifacts, and exits non-zero when the\ngate fails:\n\n```bash\nnpx -y @aarwitz/tapp@latest ci --app path/to/MyApp.app \\\n  --project-dir . --pr-base origin/main --pr-head HEAD \\\n  --target-key target_ios_myapp \\\n  --pr-plan-out tapp-pr-plan.json \\\n  --baseline path/to/last-main-report.json \\\n  --json-out tapp-report.json --md-out tapp-report.md\n```\n\nSee the self-test at\n[.github/workflows/tapp-gate-example.yml](.github/workflows/tapp-gate-example.yml) for\nFlows, auth inputs, and other controls. GitHub-hosted iOS runs require a macOS runner; the first\nrun also builds the XCUITest harness, so budget roughly 5–10 minutes depending on app size.\n\nAndroid CI runs on Linux with an emulator/device already connected. The Action can build the APK\nor accept a prebuilt one:\n\n```yaml\n- uses: aarwitz/tapp@v0.17.4 # or pin the reviewed release commit SHA\n  with:\n    platform: android\n    android-app-id: com.acme.app\n    android-project: android\n    android-task: :app:assembleDebug\n    flows: android/.tapp/flows/*.yml\n```\n\nFor web, pass `platform: web` plus `web-target:` and Tapp uses the application model to run its\nlockfile-backed install/build, start a detected package script or read-only static server, wait for\nreadiness, gate it, and stop it even on failure. Pass `url:` instead for an already-running owned\nenvironment. Add\n`scenarios: .tapp/scenarios/*.yml` to gate isolated cross-account journeys; see\n[`docs/scenarios.md`](docs/scenarios.md). Automatic\nbaselines are isolated by platform and target, so two same-platform apps are never compared.\n\n## Make your repo agent-verified\n\nDrop this into your repo's `AGENTS.md` (read by Codex, Cursor, Copilot, Devin, Zed, …) so\nyour agent proves its UI work instead of claiming it:\n\n```markdown\n## Verifying UI changes\nThis repo uses tapp (https://github.com/aarwitz/tapp) to verify UI work on a real app surface\n(iOS simulator, Android emulator/device, or a browser for web). After any UI change, run `npx -y @aarwitz/tapp@latest open` from the\nrepo root (it finds and builds the Xcode project itself) and look at the screenshot it saves as\nproof. Before declaring a feature done, run `npx -y @aarwitz/tapp@latest explore` (or `explore <url>` for web)\nand report the findings + evidence. A change is not \"done\" until it has been seen working.\n(If the tapp MCP server is connected, the tapp_* tools do the same with inline screenshots —\ntapp_build builds + installs the app and returns the bundle id for tapp_explore.)\n```\n\n## How it works\n\nEvery driver speaks one protocol: structured `OCQA_*` markers (state, actions, issues,\ntransitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.\nOn **iOS**, a generic **XCUITest harness** attaches to any app by bundle id — no SDK or app code\nchanges — and acts through the accessibility tree. On **Android**, ADB + UIAutomator provide the\nsame black-box driver contract. On **web** (beta), a deterministic **Playwright crawler** does the\nsame in a real browser. Same detectors' spirit,\nsame dedup, same regression gate, same honest `pass`/`fail`/`inconclusive` outcome. Core exploration,\nevidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI\nfeatures are explicit: finding enrichment requires `TAPP_ENABLE_REMOTE_AI=1` (an ambient\nAPI key alone never changes data handling), and AI flow generation / `assert_ai` only run\nwhen you invoke them; these send selected metadata (screen names, finding titles) to your\nconfigured model provider. Runtime configuration uses `TAPP_*` environment variables. Repository\nartifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. These are the only\nnames Tapp reads: the pre-rename `.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs are no longer\nsupported. If you still have an old directory or config, rename it to the `.tapp` names in a\nreviewed change—no secrets or evidence formats need to be rewritten.\n\nCommitted Flow replay, recording a driven session, autonomous exploration, exact assertions,\nregression comparison, and CI gating require **no API key and no coding agent at runtime**. AI is\nonly an optional authoring/enrichment layer (`tapp_flow_generate`, `assert_ai`, finding enrichment).\n\nThe first tool call builds the harness once (~2 min, cached in `~/.tapp`; rebuilt automatically\nif you switch simulators). All captures land in `~/.tapp/captures/`.\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 26785,
  "sha": "c0f8462d75d472414e11f2a8c4c06cdece52a86e5d5e6a149e1557f710056332",
  "repo_slug": "aarwitz/tapp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aarwitz_tapp_af3fa3ce/readme"
}