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 执行。

Android Use v0.7.1 — A steadier live screen. Now a Claude Code plugin

Android Use v0.7.1

A steadier live screen. Now a Claude Code plugin.

The live phone view no longer restarts its video every time the panel is briefly hidden, an authentication pause can be ended from the panel, and the repository now loads directly as a Claude Code plugin. All 26 MCP tools, keyless host decisions, optional Jev and the existing Dim / Codex integrations are unchanged.

English README · 中文 README · Native installation and rollback · Source upgrades

What's changed

• The encoder lingers for 30 seconds after the viewer is hidden. Previously capture stopped 5 seconds after the last frame request, so switching away from the panel and back cost a full encoder restart, about 3 seconds of "waiting for a new picture" on the test phone. Frames stop being served as soon as the viewer is hidden, a hidden viewer never starts an encoder, and an authentication pause or a locked phone still stops capture at once.
• Stopping video no longer blocks frame requests. Phone-side recorder cleanup runs outside the preview lock. It used to hold that lock for up to several seconds, stalling every open panel.
• One failed lock-state read is not a disconnect. The stream now stops only after three consecutive failures. Tap and swipe are disabled from the first failure until the state is known again.
• Resume from the panel. During an authentication pause the panel shows 我已完成，恢复预览. It clears the same shared flag as aua_resume, so a pause left behind by a closed agent session no longer strands every preview. A locked phone still resumes only after it is unlocked on the device.
• Claude Code plugin. .claude-plugin/ adds a plugin manifest and a marketplace entry. The manifest's own MCP entry uses ${CLAUDE_PLUGIN_ROOT}; the existing .mcp.json for Codex and Dim is unchanged. /android-use:screen opens the live screen in a local browser, because the Claude Code terminal cannot embed it. The plugin ZIP includes the manifest and the release check now covers its version.

Preview daemons from earlier versions are replaced automatically, keeping the same local address, the first time the screen is opened after updating.

Install in Claude Code

Requires uv, ADB and ffmpeg on the computer the phone is connected to.

/plugin marketplace add arcships/android-use
/plugin install android-use@arcships

The first start creates the Python environment with uv and needs network access. To load a source checkout or the extracted android-use-0.7.1-plugin.zip instead, start Claude Code with claude --plugin-dir /absolute/path/android-use.

Dim Agent, Codex and other MCP clients install as in v0.7.0; asset names are the same with the new version number.

Validation and scope

• 487 Python tests and 25 browser tests are in the suite, with Ruff and the UI build. Seven of them are new and cover the lingering encoder, lock-free stop, the lock-probe threshold and panel resume.
• The preview changes were exercised on one physical phone (Android 16, HyperOS 3, USB): returning to a hidden viewer inside the linger window served a frame immediately without a second encoder start, and no recorder process was left on the phone afterwards.
• The Claude Code plugin passed claude plugin validate and connected its MCP server when loaded with --plugin-dir on macOS with Claude Code 2.1.321. Installation from the hosted marketplace and Windows / Linux hosts have not been exercised.
• 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.7.1 artifacts.
• While the encoder lingers, the phone keeps recording for up to 30 seconds after the panel is hidden. Frames stay in memory only and are not written to disk.

中文

v0.7.1 让实时手机画面更稳，并新增 Claude Code 插件。26 个 MCP 工具、宿主决策、可选 Jev，以及 Dim / Codex 的集成方式保持不变。

• 面板隐藏后录屏保留 30 秒。 此前停止取帧 5 秒就会停流，切走再切回要重新起流，测试机上约 3 秒看不到新画面。现在隐藏后立即停止提供画面，隐藏期间不会新启动录屏；认证暂停或手机锁屏仍会立刻停流。
• 停流不再阻塞取帧。 手机端录屏清理移到预览锁之外执行。
• 单次锁屏状态读取失败不再判定为断连。 连续 3 次失败才停流；第一次失败起禁用点击和滑动，直到状态恢复。
• 在面板中恢复。 认证暂停时面板显示「我已完成，恢复预览」，清除的是与 aua_resume 相同的共享标记；手机锁屏仍需在手机上解锁。
• Claude Code 插件。 新增 .claude-plugin/，原有 .mcp.json 不变。运行 /plugin marketplace add arcships/android-use 和 /plugin install android-use@arcships 安装；/android-use:screen 在本机浏览器中打开实时画面。

验证范围： 套件共 487 项 Python 测试、25 项浏览器测试。预览改动在一台 Android 16 真机上通过 USB 验证；Claude Code 插件在 macOS 上通过清单校验并以 --plugin-dir 加载连接成功，托管市场安装及 Windows / Linux 尚未验证。原生安装、升级和回滚验收最近一次针对 v0.7.0 执行，打标签前未针对本版本重跑。

Android Use v0.7.0 — Your environment. Your installation choice

Android Use v0.7.0

Your environment. Your installation choice.

Android Use now offers optional native packages for macOS, Linux and Windows alongside the existing source plugin. Your Agent inspects the host, reuses a healthy installation and chooses the appropriate route. A standalone runtime is not required. All 26 MCP tools, keyless host decisions, optional Jev and live-screen integration remain available.

English README · 中文 README · Native installation and rollback · Source upgrades

What's new

• Optional standalone runtime: includes CPython, locked Python libraries, ADB, minimal FFmpeg, the compiled UI and UiAutomator control JAR. No separate Python/uv, Node.js or JDK setup is needed on this route. Reuse an existing source environment when it already works.
• Opt-in lightweight Dim plugins: select the matching platform ZIP for first-use installation. Use Android Use in Dim Agent, describe a phone task, and follow the live phone view beside the chat. The README now shows an actual Dim Agent screenshot.
• Verified updates and rollback: check downloads and archive paths, probe bundled tools and a real MCP session, then promote one atomic pointer. Existing sessions keep running; the next MCP connection uses the new version. Failed updates retain the active version. Rollback rechecks the previous version and pauses automatic updates.
• Optional macOS OCR: omitted from the default native package. Install the separate precompiled component only when local text recognition is needed; no Swift compiler is needed by its users. Tree interaction, Agent screenshot inspection and Jev do not depend on this helper.
• Optional interaction variation: bounded timing and selector-point variation with reproducible seeds and existing execution guards. Disabled by default; it does not hide automation or guarantee avoidance of app detection.
• Cross-platform fixes: Windows preview resources use UTF-8, original license bytes survive CRLF-configured Git checkouts, and the Windows bootstrap hashes/extracts through .NET without depending on optional PowerShell functions.
• Distribution notices: the project's MIT copyright is attributed to Archship. Dependency licenses remain separate. Archives include CPython/package notices, certifi source form, corresponding FFmpeg source/build options and native inventories; known optional DBM/readline risks are blocked at build time. Thanks to iPhone Use for the inspiration.

Pick a download

Asset	Use it for
android-use-0.7.0-plugin.zip	Existing source/Codex installation, or any local stdio MCP client using Python/uv. Requires host ADB and ffmpeg for live video.
android-use-0.7.0-PLATFORM-dim-plugin.zip	Opt-in native bootstrap plugin for Dim Agent. Choose your platform below.
android-use-runtime-PLATFORM.zip	Manual/offline native installation, or a stable local MCP command for other clients.
android-use-ocr-macos-arm64.zip, android-use-ocr-macos-x86_64.zip	Optional macOS local OCR components.
SHA256SUMS	Checksums for every installation ZIP.

PLATFORM is macos-arm64 (Apple Silicon), macos-x86_64 (Intel Mac), linux-x86_64, or windows-x86_64. Native Linux packages are built on Ubuntu 22.04. These are desktop packages, not Android APKs.

Download the selected ZIP and SHA256SUMS from this release. Compare its SHA256 with the matching line before extracting or running it. The repository may require GitHub authentication; use the browser while signed in or, for example:

gh release download v0.7.0 --repo arcships/android-use \
  --pattern android-use-runtime-macos-arm64.zip --pattern SHA256SUMS
# macOS, verifying only the ZIP downloaded above:
awk '$2=="android-use-runtime-macos-arm64.zip"' SHA256SUMS | shasum -a 256 -c -
# Linux: replace shasum -a 256 with sha256sum.

On Windows, certutil -hashfile FILE.zip SHA256 can display the value to compare with SHA256SUMS.

Install in Dim Agent

Ask your Agent:

Install Android Use from https://github.com/arcships/android-use. Inspect my existing environment and choose source setup or the optional native package. Reuse healthy installations, preserve my settings and other MCP servers, verify the release checksum, register the returned local stdio command, then check READY and open the live phone view. I will handle USB authorization and unlocking. Leave Jev disabled until I configure it.

If choosing the lightweight native plugin, extract the matching android-use-0.7.0-PLATFORM-dim-plugin.zip, then install that directory through Dim's plugin management or:

dim plugin install /absolute/path/to/extracted-dim-plugin

First-use bootstrap needs network access and OS download/unzip utilities. A private release additionally needs GitHub CLI plus ANDROID_USE_GITHUB_TOKEN with asset read access; alternatively install the native archive offline first. Never put tokens in a chat or committed configuration. After native installation, updates use the bundled HTTP client rather than GitHub CLI.

Manual native installation / other MCP clients

macOS example (replace the platform for Intel Mac or Linux):

unzip android-use-runtime-macos-arm64.zip -d android-use-runtime
./android-use-runtime/app/android-use-runtime install \
  --archive android-use-runtime-macos-arm64.zip \
  --sha256 REPLACE_WITH_THE_MATCHING_64_HEX_VALUE_FROM_SHA256SUMS

Windows PowerShell:

Expand-Archive .\android-use-runtime-windows-x86_64.zip .\android-use-runtime
& .\android-use-runtime\app\android-use-runtime.exe install `
  --archive .\android-use-runtime-windows-x86_64.zip `
  --sha256 REPLACE_WITH_THE_MATCHING_64_HEX_VALUE_FROM_SHA256SUMS

Copy the returned mcp_config.command and all mcp_config.args into the client's local stdio MCP settings. Dim can use its MCP management; Claude Desktop/Cursor use mcpServers, while VS Code uses servers. Keep existing env settings and the intended state directory. Disable duplicate Android Use registrations. The native directory defaults to ~/.local/share/android-use/runtime; keep it after deleting the downloaded ZIP/extraction.

Reconnect MCP, discover the 26 tools, then call aua_setup(action="status"), start only if needed, verify aua_ready and open aua_screen. The phone still needs debugging authorization, unlocking and a supported recording capability. Jev remains optional and can be configured in the screen's Jev settings.

Source / Codex installation

Extract android-use-0.7.0-plugin.zip. Prepare uv and ADB; ffmpeg is needed for live video. From the extraction root:

uv run --no-project --python 3.13 python scripts/install.py doctor
uv run --no-project --python 3.13 python scripts/install.py install --source . --codex

For Dim or another MCP client, omit --codex and register the returned mcp_config. For a recognized older manual/Codex registration, review diagnostics and explicitly use --migrate-codex; already-managed installations can use the ordinary install command. Source installation remains supported and does not provision a native runtime automatically.

Update, OCR and rollback

For native macOS/Linux installations:

/bin/sh "$HOME/.local/share/android-use/runtime/launcher.sh" update
/bin/sh "$HOME/.local/share/android-use/runtime/launcher.sh" install-ocr  # optional, macOS only
/bin/sh "$HOME/.local/share/android-use/runtime/launcher.sh" rollback

On Windows, use the returned native command and its --root ROOT arguments; replace the final auto-serve argument with the management command. Automatic checks occur at most once per 24 hours; ANDROID_USE_AUTO_UPDATE=0 disables them. Rollback pauses checks until an explicit successful update. Original runtime versions and settings are retained. Moving from source to native is an explicit installation choice; the source launcher's private environment file is not silently imported.

A full desktop restart is not intrinsic to a runtime upgrade, but an existing MCP process is not hot-replaced. Reconnect/reload tools to start the selected version. Publishing this release does not update an already-running local installation.

Validation and scope

The standalone implementation passed 481 Python regressions, 24 browser tests and Ruff. Native acceptance passed 15 scenarios on each macOS architecture and 13 each on Linux and Windows: real stdio MCP/UI resources, install/upgrade/rollback, active sessions during promotion, bad-update preservation, private settings, bundled H.264 decoding, optional Mac OCR and packaged public/private bootstrap. The release pipeline repeats acceptance with the v0.7.0 binaries before publication.

These package checks perform no phone actions or model calls. Earlier device/Jev acceptance is separate. Bootstrap transport was stubbed in CI; live release-download smoke checks are reported separately. Packages are unsigned: new-user OS security prompts and OEM USB drivers are outside CI acceptance. Forced termination can leave a lock; verify the process has exited before cleaning it. SHA256 protects transfer integrity, not a compromised publisher. See the validation record and license audit for the exact boundaries.

Post-publication verification

On macOS ARM64, downloaded the published source/native/Dim packages and verified their checksums. All 11 ZIP digests match GitHub's uploaded-asset records. The sou...