emulator-tools/README.md

emulator-tools

Everything this machine uses to drive an Android emulator, in one place: which emulator a command means, whether there is room to start it, reading a screen as text, and taking a screenshot that does not cost a thousand tokens.

./install.sh

symlinks bin/* into ~/.local/bin and share/ui-trace into ~/.local/share, so editing this repo is editing what runs. It keeps anything it replaces as <name>.bak.

What is here

emu	this checkout's emulator: name, serial, list, up, down
adb	adb, aimed at this checkout's emulator, with screenshots scaled
ui-trace	records a screen as text at 60Hz, and drives it
lib/project-avd.sh	the rules all three share
share/ui-trace/	the device recorder (UiTrace.java) and its build

One emulator per checkout, named after it

emu and adb both work out which AVD you mean from the enclosing git checkout: in ~/repos/ai-app-2 that is ai-app-2. Nothing has to be configured, and AVD_NAME overrides it where the guess is wrong.

This is the rule that lets several agent sessions work here at once. The emulator used to be the one resource that could not be parallelised: taking it meant messaging the other sessions, waiting, and handing it back — and installing an app onto somebody else's running emulator steals the foreground from whatever they were looking at.

It is also why adb fills in -s. With two emulators attached, a bare adb shell pm list packages comes back empty rather than failing, which reads as the app having been uninstalled rather than as the question being ambiguous. An explicit -s, ANDROID_SERIAL, or a subcommand that is not about one device (adb devices) all turn the defaulting off, and nothing is guessed when this checkout's emulator is not running: adb's own error is better than a wrapper picking a stranger's device.

Refusing to start one

emu up checks MemAvailable first and refuses if starting an emulator would leave the machine short, printing what is attached, what is large, and what usually frees enough. EMU_FORCE=1 overrides it.

The reason is a real incident rather than tidiness. On 2026-08-30 an emulator was started on this box with 2.8 GB available; the OOM killer ran, and what it took was not the emulator that had just started — it walked the user slice and killed pipewire, dbus-broker and another session's emulator first. The cost of one too many lands on somebody else's work, minutes later, looking like an unrelated crash.

Measured numbers behind the defaults: a headless x86_64 AVD is about 3.8 GB resident, this VM has 23 GB with a swap that is routinely full, two emulators are comfortable, and three were not.

Reading a screen without screenshots

ui-trace drives a small resident recorder on the device and samples the accessibility tree at 60Hz, so an animation or a settling layout is visible rather than happening between two samples.

ui-trace record -d 3000 --do 'tap 540 800' -o /tmp/t.txt
ui-trace elements /tmp/t.txt              # what is on screen, to pick from
ui-trace show /tmp/t.txt                  # what moved
ui-trace show /tmp/t.txt -m 'Send|Stop' --field box

Bounds come out in device pixels, so they feed straight back into a --do tap. Prefer this to a screenshot for anything positional: two buttons that measured identically at 171x105 looked different in a screenshot, because the filled one read as larger than the disabled grey one. Screenshots are for appearance — colour, weight, whether it looks right.

adb exec-out screencap -p still works and comes back scaled to 800px on its long edge, which is ~380 tokens to read instead of ~1460 and still legible for layout, contrast and small labels. ADB_SCREENCAP_MAX_EDGE raises it for one call.

Using it from a project

A project's own run-android.sh should build and install; the emulator half belongs here:

SERIAL=$(emu up)
./gradlew :androidApp:assembleDebug
adb install -r <apk>          # already aimed at this checkout's emulator