android-driver 0.0.1__py3-none-any.whl

android_driver/session.py

@@ -0,0 +1,144 @@
+"""Per-server session state: which device is selected, its driver, its last screen.
+
+The `#N` references handed out by `screen()` are only meaningful against the
+hierarchy they were produced from, so the session caches that snapshot and
+invalidates it after anything that could change the display. `resolve()` refreshes
+transparently when the cache is cold, which is what lets an agent call
+`tap(desc=...)` without a `screen()` call in front of it.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from . import adb, ui
+from .config import Config
+from .drivers import Driver, create
+from .log import log
+
+
+class Session:
+    def __init__(self, cfg: Config) -> None:
+        self.cfg = cfg
+        self._serial: str | None = None
+        self._driver: Driver | None = None
+        self._elements: list[ui.Element] = []
+        self._elements_fresh = False
+        self.run_dir: Path | None = None
+
+    # ── device ───────────────────────────────────────────────────────────────
+
+    @property
+    def serial(self) -> str:
+        if self._serial is None:
+            self._serial = adb.pick_device()
+            log("session", f"auto-selected device {self._serial}")
+        return self._serial
+
+    @property
+    def current_serial(self) -> str | None:
+        """The pinned serial, or None — unlike `.serial`, never picks a device."""
+        return self._serial
+
+    def select(self, serial: str) -> None:
+        online = adb.list_serials()
+        if serial not in online:
+            raise ValueError(f"{serial!r} is not attached. Available: {online or '(none)'}")
+        self._reset()
+        self._serial = serial
+        log("session", f"device pinned to {serial}")
+
+    def reconnect(self) -> None:
+        """Drop the device connection so the next call rebuilds it, keeping the device pinned.
+
+        Restoring a snapshot swaps the whole OS out from under us and takes the
+        on-device uiautomator server with it. The connection we are holding does
+        not notice: it fails on the *next* request with `RemoteDisconnected`,
+        which reads as a broken app rather than a stale session.
+        """
+        if self._driver is not None:
+            try:
+                self._driver.close()
+            except Exception as e:  # the far end is usually already gone
+                log("session", f"ignoring error while closing the driver: {e}")
+        self._driver = None
+        self.invalidate()
+
+    def _reset(self) -> None:
+        self.reconnect()
+        self._serial = None
+
+    @property
+    def driver(self) -> Driver:
+        if self._driver is None:
+            self._driver = create(self.serial, self.cfg.driver.backend, self.cfg.timing.click_settle_s)
+        return self._driver
+
+    # ── screen ───────────────────────────────────────────────────────────────
+
+    def invalidate(self) -> None:
+        """Mark the cached screen index stale. Call after anything that can redraw."""
+        self._elements_fresh = False
+
+    def refresh(self) -> list[ui.Element]:
+        self._elements = ui.parse(self.driver.dump_hierarchy())
+        self._elements_fresh = True
+        return self._elements
+
+    def elements(self, refresh: bool = False) -> list[ui.Element]:
+        if refresh or not self._elements_fresh:
+            return self.refresh()
+        return self._elements
+
+    def header(self) -> str:
+        app = self.driver.current_app()
+        width, height = self.driver.screen_size()
+        return (
+            f"device={self.serial} app={app['package'] or '?'}/{app['activity'] or '?'} "
+            f"screen={width}x{height} driver={self.driver.name}"
+        )
+
+    def resolve(self, **selector) -> ui.Element:
+        """Find one element, retrying once against a fresh snapshot before failing.
+
+        A stale cache is the single most common cause of a "not found" here, and
+        re-reading is far cheaper than making the agent debug it.
+        """
+        try:
+            return ui.find(self.elements(), **selector)
+        except LookupError:
+            if self._elements_fresh:
+                raise
+            return ui.find(self.refresh(), **selector)
+
+    def wait_for(self, timeout_s: float, poll_s: float = 0.5, **selector) -> ui.Element:
+        deadline = time.monotonic() + timeout_s
+        last: Exception | None = None
+        while True:
+            try:
+                return ui.find(self.refresh(), **selector)
+            except LookupError as e:
+                last = e
+                if time.monotonic() >= deadline:
+                    raise LookupError(f"{e} (waited {timeout_s}s)") from last
+                time.sleep(poll_s)
+
+    def wait_until_gone(self, timeout_s: float, poll_s: float = 0.5, **selector) -> None:
+        """Block until nothing matches `selector`. Raises TimeoutError if it stays."""
+        deadline = time.monotonic() + timeout_s
+        while True:
+            try:
+                element = ui.find(self.refresh(), **selector)
+            except LookupError:
+                return
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"{element.label()!r} was still on screen after {timeout_s}s")
+            time.sleep(poll_s)
+
+    def screen_text(self) -> str:
+        """The compact screen index, for pasting into a failure message."""
+        try:
+            return ui.render(self.elements(), header=self.header())
+        except Exception as e:  # a failure report must never fail
+            return f"(could not read the screen: {type(e).__name__}: {e})"

android_driver/ui.py

@@ -0,0 +1,261 @@
+"""UI hierarchy → a compact, agent-readable screen index.
+
+The single biggest practical problem with driving Android from an LLM is that a
+raw `uiautomator dump` is 50-200 KB of XML per screen. Handing that to a model
+burns tens of thousands of tokens for information it mostly cannot use, and the
+agent runs out of context after a handful of screens.
+
+This module renders the same hierarchy as one line per *actionable or readable*
+element, with a stable `#N` reference the agent can tap:
+
+    #1 [Button] "Sign in" desc=login_button @(540,1320)
+    #2 [EditText] "" desc=text_field_Email hint="Email" @(540,980)
+    #3 [Text] "Forgot password?" @(540,1450)
+
+That is roughly two orders of magnitude smaller, and it reads like a menu. Raw
+XML stays available through a separate, explicitly-named tool for the rare case
+where the agent genuinely needs the tree.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+
+BOUNDS_RE = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]")
+
+# Widget classes that are always worth showing even with no text or description:
+# the agent needs to know an empty input or an unlabelled toggle is there.
+ALWAYS_INTERESTING = {
+    "android.widget.EditText",
+    "android.widget.Button",
+    "android.widget.ImageButton",
+    "android.widget.CheckBox",
+    "android.widget.RadioButton",
+    "android.widget.Switch",
+    "android.widget.SeekBar",
+    "android.widget.Spinner",
+    "android.widget.RatingBar",
+}
+
+# Friendlier names for the classes that dominate a typical dump.
+CLASS_ALIASES = {
+    "android.widget.TextView": "Text",
+    "android.widget.EditText": "EditText",
+    "android.widget.Button": "Button",
+    "android.widget.ImageButton": "ImageButton",
+    "android.widget.ImageView": "Image",
+    "android.widget.CheckBox": "CheckBox",
+    "android.widget.RadioButton": "Radio",
+    "android.widget.Switch": "Switch",
+    "android.widget.SeekBar": "SeekBar",
+    "android.widget.ScrollView": "Scroll",
+    "android.widget.HorizontalScrollView": "HScroll",
+    "androidx.recyclerview.widget.RecyclerView": "List",
+    "android.widget.ListView": "List",
+    "android.view.View": "View",
+    "android.view.ViewGroup": "Group",
+    "android.widget.FrameLayout": "Frame",
+    "android.widget.LinearLayout": "Row",
+    "android.widget.RelativeLayout": "Rel",
+    "android.widget.Toast": "Toast",
+}
+
+
+@dataclass
+class Element:
+    ref: int
+    cls: str
+    text: str
+    desc: str
+    rid: str
+    hint: str
+    bounds: tuple[int, int, int, int]
+    clickable: bool
+    scrollable: bool
+    checkable: bool
+    checked: bool
+    enabled: bool
+    focused: bool
+    password: bool
+    pkg: str
+
+    @property
+    def center(self) -> tuple[int, int]:
+        x1, y1, x2, y2 = self.bounds
+        return (x1 + x2) // 2, (y1 + y2) // 2
+
+    @property
+    def short_class(self) -> str:
+        return CLASS_ALIASES.get(self.cls, self.cls.rsplit(".", 1)[-1])
+
+    def label(self) -> str:
+        """Best human-facing name, used in error messages."""
+        return self.text or self.desc or self.rid.rsplit("/", 1)[-1] or self.short_class
+
+    def render(self) -> str:
+        parts = [f"#{self.ref}", f"[{self.short_class}]"]
+        if self.text or self.cls == "android.widget.EditText":
+            parts.append(f'"{_clip(self.text)}"')
+        if self.desc and self.desc != self.text:
+            parts.append(f"desc={_token(self.desc)}")
+        if self.rid:
+            parts.append(f"id={_token(self.rid.rsplit('/', 1)[-1])}")
+        if self.hint:
+            parts.append(f'hint="{_clip(self.hint)}"')
+        flags = []
+        if self.checkable:
+            flags.append("checked" if self.checked else "unchecked")
+        if self.scrollable:
+            flags.append("scrollable")
+        if not self.enabled:
+            flags.append("disabled")
+        if self.focused:
+            flags.append("focused")
+        if self.password:
+            flags.append("password")
+        if flags:
+            parts.append(f"({','.join(flags)})")
+        x, y = self.center
+        parts.append(f"@({x},{y})")
+        return " ".join(parts)
+
+    def to_dict(self) -> dict:
+        x, y = self.center
+        return {
+            "ref": f"#{self.ref}",
+            "class": self.short_class,
+            "text": self.text,
+            "desc": self.desc,
+            "id": self.rid,
+            "center": [x, y],
+            "bounds": list(self.bounds),
+            "clickable": self.clickable,
+            "enabled": self.enabled,
+        }
+
+
+def _clip(value: str, limit: int = 80) -> str:
+    value = value.replace("\n", "\\n")
+    return value if len(value) <= limit else value[: limit - 1] + "…"
+
+
+def _token(value: str) -> str:
+    """Quote only when the value contains whitespace — keeps common lines short."""
+    return value if value and not re.search(r"\s", value) else f'"{_clip(value)}"'
+
+
+def _bool(node: ET.Element, attr: str) -> bool:
+    return node.attrib.get(attr) == "true"
+
+
+def _parse_bounds(raw: str) -> tuple[int, int, int, int] | None:
+    m = BOUNDS_RE.match(raw or "")
+    if not m:
+        return None
+    x1, y1, x2, y2 = (int(g) for g in m.groups())
+    return x1, y1, x2, y2
+
+
+def _is_interesting(node: ET.Element, bounds: tuple[int, int, int, int]) -> bool:
+    x1, y1, x2, y2 = bounds
+    if x2 <= x1 or y2 <= y1:
+        return False  # zero-area: laid out but not visible
+    cls = node.attrib.get("class", "")
+    if cls in ALWAYS_INTERESTING:
+        return True
+    if _bool(node, "clickable") or _bool(node, "long-clickable") or _bool(node, "checkable"):
+        return True
+    if _bool(node, "scrollable"):
+        return True
+    return bool(node.attrib.get("text") or node.attrib.get("content-desc"))
+
+
+def parse(xml_text: str) -> list[Element]:
+    """Extract the interesting elements from a hierarchy dump, in document order."""
+    try:
+        root = ET.fromstring(xml_text)
+    except ET.ParseError as e:
+        raise ValueError(f"could not parse UI hierarchy XML: {e}") from e
+
+    elements: list[Element] = []
+    ref = 0
+    for node in root.iter("node"):
+        bounds = _parse_bounds(node.attrib.get("bounds", ""))
+        if bounds is None or not _is_interesting(node, bounds):
+            continue
+        ref += 1
+        elements.append(
+            Element(
+                ref=ref,
+                cls=node.attrib.get("class", ""),
+                text=node.attrib.get("text", ""),
+                desc=node.attrib.get("content-desc", ""),
+                rid=node.attrib.get("resource-id", ""),
+                hint=node.attrib.get("hint", ""),
+                bounds=bounds,
+                clickable=_bool(node, "clickable"),
+                scrollable=_bool(node, "scrollable"),
+                checkable=_bool(node, "checkable"),
+                checked=_bool(node, "checked"),
+                enabled=_bool(node, "enabled"),
+                focused=_bool(node, "focused"),
+                password=_bool(node, "password"),
+                pkg=node.attrib.get("package", ""),
+            )
+        )
+    return elements
+
+
+def render(elements: list[Element], header: str | None = None) -> str:
+    if not elements:
+        body = "(no interactive or readable elements — the screen may still be rendering)"
+    else:
+        body = "\n".join(e.render() for e in elements)
+    return f"{header}\n{body}" if header else body
+
+
+def find(
+    elements: list[Element],
+    *,
+    ref: str | int | None = None,
+    text: str | None = None,
+    contains: str | None = None,
+    desc: str | None = None,
+    rid: str | None = None,
+    cls: str | None = None,
+    index: int = 0,
+) -> Element:
+    """Resolve a selector to exactly one element, or raise with a useful message.
+
+    Matching is deliberately strict-then-loose: `text`/`desc`/`rid` are exact so a
+    recipe cannot silently drift onto a different button, while `contains` exists
+    for the cases where the exact string is not known.
+    """
+    criteria = {"ref": ref, "text": text, "contains": contains, "desc": desc, "id": rid, "class": cls}
+    active = {k: v for k, v in criteria.items() if v is not None}
+    if not active:
+        raise ValueError("no selector given: pass one of ref / text / contains / desc / rid / cls")
+
+    candidates = elements
+    if ref is not None:
+        wanted = int(str(ref).lstrip("#"))
+        candidates = [e for e in candidates if e.ref == wanted]
+    if text is not None:
+        candidates = [e for e in candidates if e.text == text]
+    if contains is not None:
+        needle = contains.lower()
+        candidates = [e for e in candidates if needle in e.text.lower() or needle in e.desc.lower()]
+    if desc is not None:
+        candidates = [e for e in candidates if e.desc == desc]
+    if rid is not None:
+        candidates = [e for e in candidates if e.rid == rid or e.rid.endswith(f"/{rid}")]
+    if cls is not None:
+        candidates = [e for e in candidates if e.short_class.lower() == cls.lower() or e.cls == cls]
+
+    if not candidates:
+        raise LookupError(f"no element matches {active}. Call `screen` to see what is on screen.")
+    if index >= len(candidates):
+        raise LookupError(f"{active} matched {len(candidates)} element(s); index {index} is out of range")
+    return candidates[index]

android_driver-0.0.1.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.5
+Name: android-driver
+Version: 0.0.1
+Summary: MCP server that turns an Android emulator into a deterministic, agent-drivable test harness.
+Project-URL: Homepage, https://github.com/earlzdev/android-driver
+Project-URL: Repository, https://github.com/earlzdev/android-driver
+Project-URL: Issues, https://github.com/earlzdev/android-driver/issues
+Project-URL: Documentation, https://github.com/earlzdev/android-driver#readme
+Author: earlzdev
+License: MIT
+License-File: LICENSE
+Keywords: adb,agent,android,emulator,mcp,testing,uiautomator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uiautomator2<4,>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# android-driver
+
+**Drive an Android emulator as a deterministic test harness — from Claude Code.**
+
+[![CI](https://github.com/earlzdev/android-driver/actions/workflows/ci.yml/badge.svg)](https://github.com/earlzdev/android-driver/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+You ask an agent to reproduce a bug in your Android app. It dumps 80 KB of accessibility XML into its
+own context, taps something that turns out to be the wrong element, and when the bug does not appear
+it cannot repeat what it just did — because the app is now three screens deep in a state nobody
+recorded.
+
+android-driver is built for that loop instead: **build → install → drive → assert → reset → repeat.**
+
+```
+> reproduce the crash when the bio field goes over 100 characters
+
+  snapshot_load("clean")                          1.9s
+  open_settings()                                 ok
+  type_text(id=text_field_Bio, text=110 chars)    ok
+  expect_log("StringIndexOutOfBoundsException")   ok — matched
+  expect_no_crash()                               FAILED — 1 crash record
+
+  runs/20260901-080304-repro-set-06/report.md
+  → java.lang.StringIndexOutOfBoundsException: begin 0, end 120, length 110
+      at ...screens.SettingsScreenKt.SettingsScreen$textFields(SettingsScreen.kt:149)
+```
+
+Three attempts from the same snapshot, three identical results, and a directory of evidence to point
+at. That is the whole idea.
+
+---
+
+## Install
+
+It is a Claude Code plugin: one install brings the tools, a skill that teaches Claude the loop, and
+three slash commands.
+
+```bash
+claude plugin marketplace add earlzdev/android-driver
+claude plugin install android-driver@android-driver
+```
+
+There is no venv to manage — the plugin builds the Python server from source on demand, and passes
+your project directory to it so your config is found wherever Claude was launched from.
+
+**Requirements:** `adb` and the Android SDK's `emulator` on `PATH`, Python ≥ 3.10. For the faster
+uiautomator2 backend run `python -m uiautomator2 init` once per device; without it the server falls
+back to a pure-adb backend that needs nothing installed on the device.
+
+Prefer a plain MCP server, or not using Claude Code at all? See
+[docs/installation.md](docs/installation.md).
+
+## Quickstart
+
+```
+/android-driver:setup
+```
+
+It checks your toolchain, finds your `applicationId` and build command, detects whether you are on
+Compose or Views, writes a starter `.android-driver.yaml`, boots an emulator and proves the loop
+works. Then:
+
+```
+/android-driver:smoke                    # build, install, walk the main flows, assert nothing broke
+/android-driver:repro <what is broken>   # reproduce it from a snapshot and leave evidence
+```
+
+Or just talk to it — the `android-testing` skill loads automatically when a task involves driving the
+app, so "check that login still works on a fresh install" does the right thing without ceremony.
+
+## Why it works this way
+
+Four decisions do most of the work.
+
+**Snapshots, so a repro is actually reproducible.** `snapshot_save` freezes the emulator's exact
+state; `snapshot_load` restores it and waits until the device is genuinely drivable again — 1.8–2.2s
+measured on a Pixel 7 AVD. Reinstalling and re-navigating costs 30–90s *and drifts a little each
+time*. An agent testing thirty variations of a hypothesis needs the cheap, identical option: the
+difference between two attempts only means something if everything else was the same.
+
+**A screen index instead of a wall of XML.** A raw `uiautomator dump` is 50–200 KB per screen — tens
+of thousands of tokens for a model that just wants to know what it can tap. `screen` returns this:
+
+```
+device=emulator-5554 app=com.example.app/.MainActivity screen=1080x2400 driver=uiautomator2
+#5  [Scroll]   id=settings_container (scrollable)     @(540,1236)
+#7  [Text]     "Settings"  id=homepage_title          @(235,472)
+#18 [EditText] "" id=text_field_Bio                   @(540,1018)
+```
+
+Then `tap(ref="#7")`. Two orders of magnitude smaller, and it reads like a menu. The raw tree is
+still there behind `dump_ui_xml` for when you genuinely need it.
+
+**Assertions that collect their own evidence.** `expect_visible` polls, so it is safe immediately
+after a tap and will not flake on an animation; when it fails it hands back the screen index that
+*was* there, plus a screenshot and hierarchy dump on disk. `expect_no_crash` reads the `crash` buffer
+as well as `main`, because a native abort never reaches `main` at all. Wrap a sequence in
+`run_start` / `run_end` and you get `runs/<id>/` holding a timeline, a report, the logcat slice for
+exactly that window, and every failure artifact — so an agent cites a directory instead of describing
+what it saw.
+
+**Your flows as first-class tools.** The six steps every test starts with — sign in, create an order,
+join a call — go into `.android-driver.yaml` once and become real MCP tools with typed parameters. An
+agent sees `login(email, password)` in its tool list rather than rediscovering the flow from a screen
+dump every session. Recipes run the same code path as the hand-driven tools, so the two cannot drift.
+
+<details>
+<summary>Plus the device knowledge that costs an afternoon each to learn</summary>
+
+- **Uninstall-then-install**, not `pm install -r` — debug APKs from different branches carry
+  different signing keys and otherwise fail with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
+- **Check `mInputShown` before pressing Back**, so dismissing the keyboard never dismisses the
+  dialog behind it.
+- **Write to Compose `TextField`s through the accessibility node**, not tap-then-type, which lands
+  text in the wrong field.
+- **Settle after a click** before the next query, or you read pre-animation state.
+- **An `appops` pass** for OEM permission overlays that keep blocking after `pm grant` reports
+  success.
+
+</details>
+
+## Configure
+
+`.android-driver.yaml` at your project root is what makes a generic tool specific to your app.
+`/android-driver:setup` writes a starter for you.
+
+```yaml
+app:
+  package: com.example.myapp
+  activity: .MainActivity          # optional; the launcher intent is resolved otherwise
+
+build:
+  command: ./gradlew :app:assembleDebug
+  apk_glob: app/build/outputs/apk/debug/*.apk
+
+driver:
+  backend: auto                    # auto | uiautomator2 | adb
+
+selectors:                         # scanned, so a typo is a warning rather than a mystery
+  sources: ["app/src/main/**/*.kt"]
+
+recipes:                           # each becomes an MCP tool with typed parameters
+  login:
+    params: {email: {required: true}, password: {required: true, secret: true}}
+    steps:
+      - launch:
+      - type: {desc: text_field_Email, text: "{{email}}"}
+      - tap: {desc: login_button}
+      - expect_visible: {desc: home_greeting, timeout_s: 20}
+```
+
+The file is optional: with no config every generic tool still works — you pass `pkg=` explicitly and
+lose `build_app` and recipes. It is found by walking up from your project and then, failing that, up
+to three levels *down*, so an app in `app/` or `android/` is discovered without configuration.
+
+Full reference: **[docs/configuration.md](docs/configuration.md)** · recipe and step syntax:
+**[docs/recipes.md](docs/recipes.md)** · worked examples for Compose and View projects:
+[`examples/`](examples/).
+
+## Tools
+
+45, plus one per configured recipe.
+
+| Group | Tools |
+|---|---|
+| Emulator | `list_avds` `start_emulator` `stop_emulator` `wait_for_boot` `snapshot_save` `snapshot_load` `snapshot_list` `snapshot_delete` |
+| Device | `list_devices` `select_device` `device_info` |
+| App | `build_app` `install_app` `uninstall_app` `app_info` `launch_app` `force_stop` `clear_app_data` |
+| UI | `screen` `tap` `tap_xy` `long_press` `type_text` `swipe` `scroll_to` `press_key` `screenshot` `dump_ui_xml` |
+| Assertions | `expect_visible` `expect_gone` `expect_log` `expect_no_crash` |
+| Runs | `run_start` `run_end` `run_list` `record_start` `record_stop` |
+| Recipes | `list_recipes` `run_recipe` `check_recipes` `list_selectors` `reload_config` |
+| Logs | `logcat_clear` `logcat_read` |
+| Shell | `shell` |
+
+> [!WARNING]
+> `shell` is unrestricted on purpose — this is a development tool, not a sandbox. It can wipe device
+> data, kill processes and read files. Point it at emulators and test devices, not at anything you
+> care about.
+
+### The loop, in tool calls
+
+```python
+start_emulator(avd="Pixel_7")   # reuses one that is already running
+install_app(build_first=True)
+launch_app()
+snapshot_save("clean")          # ← the state every attempt returns to
+
+run_start("issue 412: crash on empty search")
+  … login() / tap / type_text / expect_visible …
+  expect_no_crash()
+run_end()                       # → runs/<id>/report.md
+
+snapshot_load("clean")          # next variation, from identical state
+```
+
+[`docs/agent-guide.md`](docs/agent-guide.md) is a `CLAUDE.md` fragment you can drop into a project so
+an agent picks this up without being told.
+
+## Try it without your own app
+
+The repo ships **[FlakyDemo](test_app/)** — a Compose app with five screens and **27 deliberately
+planted bugs**, each documented in [`test_app/BUGS.md`](test_app/BUGS.md) with what was actually
+observed rather than what was intended. Crashes, races, state lost on rotation, a Save button that
+reports success and silently does nothing, and several bugs that only show up one run in three.
+
+Its flake generator is seeded, so `--el flake_seed 42` replays the same failures every time and
+`--ez flake_enabled false` turns them all off for a clean baseline. It ships with 11 recipes.
+
+It is the fastest way to see what the tool is for — and a fair test of whether it earns its keep,
+since a good number of the planted bugs are the kind a tap-and-screenshot agent cannot catch at all.
+The Settings screen alone reports "Saved" in the UI while the log says
+`outcome=noop reason=terms_not_accepted` and nothing was written.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest              # 129 unit tests against a fake driver, no device needed
+uv run ruff check src tests
+```
+
+Setup, the live suite, and the packaging pitfalls worth knowing about are in
+**[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+## Status
+
+Early, but working end to end. Emulator lifecycle, snapshots, both driver backends, the screen index,
+assertions, run bundles, screen recording, recipes and selector scanning are implemented and covered
+by tests; the live suite passes against a Pixel 7 AVD. Packaged as a Claude Code plugin with a skill
+and three commands.
+
+Not on PyPI — the plugin builds from source, so it does not need to be. Roadmap:
+[docs/roadmap.md](docs/roadmap.md). Issues and pull requests welcome.
+
+## License
+
+MIT