Android Use v0.8.0 — Edit code, see it on the phone: hot swap for apps under development

Android Use v0.8.0

Edit code, see it on the phone: hot swap for apps under development.

A new tool, aua_hot_swap, pushes source edits into a running debuggable app without reinstalling or restarting it. An agent that is developing an Android app from local source can change a line, call the tool once, and read the updated screen from the same call. The 26 existing MCP tools, keyless host decisions, optional Jev and the Dim / Codex / Claude Code integrations are unchanged; the tool count is now 27.

English README · 中文 README · Hot swap · Native installation and rollback

What's new

• aua_hot_swap(project=...). Compiles the files that changed, finds the classes whose bytes differ from what the process runs, and has a small JVMTI agent redefine them in place. Edited resources are relinked with stable IDs and loaded into the process the same way. It uses the JDK and the Android SDK directly; nothing is added to the app's build.
• UI state is kept. Compose functions run again over their existing state, so remember values and scroll positions stay. View screens are rebuilt with their saved state plus scroll offsets, typed text in fields without an ID, and the keyboard. The process, its statics and the back stack are untouched.
• Gradle projects need no setup. Pass the Gradle root or a module directory. Gradle keeps doing the full builds and the swaps reuse the classpath and compiler flags it exports. Settings and caches go to the project's build/ directory; project files are not modified. A plain project can describe itself in a hotswap.json.
• One call, explicit outcomes. The result is swapped, installed or unchanged. Whatever cannot be swapped (first call, app not running, manifest or build file change, deleted source, a swap the runtime refuses) falls back to a full build, install and launch, with the reason. A compile error returns compile_failed with the compiler output and leaves the app as it was. observe returns the tree or a screenshot after the swap; action=status reports the host toolchain and what the next call would do, changing nothing.
• Authentication handoff applies. A paused device refuses swap and build.

Requirements

• A debuggable build (android:debuggable="true", the default for debug variants) on Android 8 or later; resource edits need Android 11 or later.
• On the computer: a JDK on PATH and the Android SDK with build-tools and a platform. The NDK is needed once per device ABI to compile the agent, which is then cached. macOS and Linux.
• The standalone runtime includes the tool but not a JDK or the Android SDK.

Installation and asset names are as in v0.7.1, with the new version number.

Validation and scope

• 497 Python tests and 25 browser tests are in the suite, with Ruff and the UI build. Ten are new and cover project detection, the tool's arguments, takeover, and failure reporting.
• On one physical phone (Android 16, HyperOS 3, USB), through a real MCP stdio session: a one-line Java edit was swapped in 0.55 to 0.64 seconds and the returned tree showed the new text; the whole call took about 1.4 seconds. A full build of the plain lab app took 4.7 seconds.
• The end-to-end suite script/hotswap/verify.py edits two lab apps and reads the app's own log to confirm what the process executes: method bodies, added methods, fields and classes, lambdas, Kotlin inline functions, resource values, colours, new resources, and kept text, scroll and Compose state. On the phone the plain app passed 22 of 22 checks. The Compose sample passed all of its checks in the preceding run; that run's single failure was the plain app's scroll check reading its baseline during a fling, which was then fixed in the test, and the Compose half was not repeated afterwards. An Android 15 emulator passed 31 of 31 before the code moved into the package.
• Not exercised: automatic Gradle detection on a device (unit tests only; the sample uses a hand-written configuration), Windows hosts, the standalone runtime build with this tool, annotation processors that must rerun for an edit (kapt, KSP, Hilt, Room), edits spanning several Gradle modules, and Kotlin 2.x.
• Known limits: a structural change to a composable resets that function's state; activity instance fields are lost when a View screen is rebuilt; the first Gradle build can take minutes and may exceed a client's tool timeout, in which case call again.
• Native install, upgrade and rollback acceptance was last run for v0.7.0 and has not been repeated for this version before tagging; the release pipeline re-runs its package checks on the v0.8.0 artifacts.

中文

v0.8.0 新增热更新工具 aua_hot_swap：Agent 在本机开发 Android App 时，改完代码调用一次，改动约一秒内进入运行中的可调试 App，不重装、不重启。原有 26 个 MCP 工具及各客户端集成方式不变，工具数变为 27。

• 进程内替换。 只编译改动的文件，对比出字节有变化的类，由 JVMTI agent 在进程内重定义；资源以稳定 ID 重新链接后加载。直接使用 JDK 和 Android SDK，不向 App 的构建添加任何东西。
• 保留界面状态。 Compose 保留 remember 状态和滚动位置；View 页面重建后保留滚动位置、已输入的文字和键盘；进程、静态变量和返回栈不变。
• Gradle 工程免配置。 传 Gradle 根目录或模块目录即可，设置和缓存写在工程的 build/ 下，不改工程文件。
• 一次调用，结果明确。 swapped、installed（自动退回完整构建并说明原因）或 unchanged；编译错误返回 compile_failed 和编译器输出，App 保持原状；observe 在同一次调用返回更新后的界面；action=status 只读。
• 要求： debug 构建，Android 8 及以上（资源热更新需 Android 11）；主机需 JDK 和 Android SDK，NDK 仅在首次为某个设备 ABI 编译 agent 时需要。支持 macOS 和 Linux。

验证范围： 套件共 497 项 Python 测试、25 项浏览器测试。一台 Android 16 真机上经真实 MCP 会话验证，单行 Java 改动热更新耗时 0.55–0.64 秒；端到端套件普通 App 部分 22/22 通过，Compose 样例在此前一轮全部通过，测试修正后未重跑。Gradle 自动识别仅有单元测试，Windows 主机、独立运行包、kapt/KSP/Hilt/Room、多模块 Gradle、Kotlin 2.x 尚未验证。原生安装、升级和回滚验收最近一次针对 v0.7.0 执行。