ShadowDroid v2.0.3

ShadowDroid 2 puts the whole Android development loop in your agent's hands,
with no IDE in the middle. It applies each code change to the running app,
debugs Kotlin, Java, C and C++ on its own debuggers, inspects layouts and
coroutines from inside the app, and opens a live device viewer in Claude Code
so you can watch, point and record. This is the first 2.x release; it includes
everything since v1.3.0.

Highlights:

• Apply Changes from the CLI: app apply puts each edit on the device the
  cheapest correct way, usually in place in about two seconds with app state
  kept.
• Its own debuggers: Java/Kotlin over JDWP and native C/C++ over the NDK's
  LLDB, with no Android Studio.
• The ShadowDroid runtime: layout trees, Compose recomposition counts and
  coroutine dumps from any debuggable app, with no build changes.
• Plugins for Claude Code and Codex, including a live device viewer with
  annotations and tap-to-test recording.
• Windows support for the CLI, debuggers, runtime and viewer.
• Breaking: the Android Studio integration and the in-app AAR are removed,
  ShadowDroid moved to the shadowdroid-dev organization, and it is now
  distributed as binaries only.

Apply Changes

shadowdroid app apply builds incrementally, compares the new code with what
the device runs, and picks how the change reaches the app:

• hot: redefines the changed classes in the running app and recomposes
  only the composables you edited, keeping state above them. On API 30+ new
  methods, fields and classes apply in place too.
• restart_activity: when code that already ran changed (lifecycle,
  ViewModel init, a started flow).
• reinstall: when nothing safer is possible, with the reason.

The result reports action, reasons, takes_effect, what changed on
screen, crashes, Compose composition errors, errors the app logged and failed
requests. It covers library modules, lists, dialogs, Views and fragments.

Debuggers

This release gives ShadowDroid its own debuggers and removes the Android
Studio integration. An agent can now attach to a debuggable app, stop it, read
its state and step through it, in Kotlin, Java, C and C++, using only the adb
connection ShadowDroid already owns and, for native code, the NDK's LLDB. No
IDE is involved.

• Java/Kotlin debugger: the debug verbs talk JDWP to the app through
  adb, held by a small per-process daemon. Attach to a running app, or launch
  it under the debugger with debug attach --wait-for-launch --break File.kt:LINE so breakpoints are in place before the first line runs.
  Line, exception and method breakpoints support conditions, pass counts,
  temporary and disabled states, and lambda selection with --variant.
  Logpoints have a bounded, cursored event stream and are rate-limited.
  Stepping, stacks, threads, variables, eval and inspect with object
  handles work, as do watches, coroutine listing and crash capture with
  run-until-crash. See debugging.
• Native and mixed debugging: debug attach --mode native debugs C and
  C++ code on the NDK's LLDB, and --mode mixed attaches both engines to one
  process. Attach to a running app or at launch (--wait-for-launch).
  Symbols come from the project's unstripped Gradle outputs, matched by
  build-id, or from --symbols. Line, function, address and data
  (watchpoint) breakpoints, native logpoints in the same event stream as Java
  ones, stack, threads, variables with C++ STL types rendered, eval, and
  debug native registers|memory|disassemble|modules|symbols|step-instruction.
  Real crashes stop at the faulting frame with suspend_reason: "crash" and
  the signal; ART's own SIGSEGV/SIGBUS use passes through untouched
  (--signal-policy smart, the default). Detaching lets Android write the
  tombstone (debug tombstones list|pull). In mixed mode verbs route by file
  extension, breakpoint id, session id or --engine java|native, and Java
  verbs fail fast with native_engine_stopped while LLDB holds the process.
  snapshot, run-until-crash, auto, record and watch include the
  native engine. Needs an NDK on the host (SHADOWDROID_NDK,
  ANDROID_NDK_HOME, ... or <sdk>/ndk/<version>); works on Linux, macOS
  and Windows. See the "Native and mixed debugging" section of
  debugging.
• Method calls are opt-in: --invoke lets eval, conditions, logpoints,
  watches and coroutine snapshots call methods such as toString(), getters
  and Kotlin properties. A thrown exception comes back as a result. Without
  the flag, nothing runs app code.
• Property watches without slowing the app: Kotlin properties are watched
  through their setter or getter. A field with no setter is watched at the
  instructions that write it, found in the app's dex files, so the app keeps
  full speed. A real field watch, which slows the whole app, needs
  --accept-slowdown and expires after --duration-ms.
• ANRs: a stop in an app that was already running can trigger Android's
  "not responding" dialog. The session reports it and suggests
  debug attach --relaunch, which restarts the app under the debugger with the
  same breakpoints. Apps launched under the debugger never raise ANRs.
• debug clients, debug record and watch: these now run on the
  standalone debugger. debug clients lists the device's debuggable
  processes and the sessions attached to them; debug record and watch
  take debugger state and logpoint hits from the debugger daemons.
• Debugger reads during other commands: read-only debugger verbs
  (debug status, stack, ...) keep working while another command runs,
  such as a ui tap blocked on an app stopped at a breakpoint. Debugger verbs
  that need the device lock wait up to 10 s for it.
• ui tap on an unresponsive app: a click the app never answers within
  about 4–5 s (main thread busy or stopped at a breakpoint) now returns
  tap_unconfirmed instead of tap_failed. The click is queued and may still
  run, so do not repeat it blindly; input_delivered is unknown,
  app_unresponsive is true, no coordinate fallback is injected, and the next
  actions point at debug status.
• Doctor: an advisory debugger check reports whether the standalone
  debugger can run, whether the app is debuggable and who holds it. An
  advisory native check reports the NDK, LLDB and an lldb-server for the
  app's ABI.
• Testing: CI jobs run the debuggers end to end on an emulator:
  scripts/e2e-jdwp-debugger.sh, and scripts/e2e-native-debugger.sh for
  native and mixed debugging against the sample app's new Native Lab.

Android Studio integration removed

Breaking: the Android Studio plugin, the Studio debugger backend and the
Studio Layout Inspector bridge are gone. Every debug verb runs on
ShadowDroid's own debuggers, and layout data comes from the
ShadowDroid runtime. Android Studio still works as
your IDE alongside ShadowDroid; it is just not a backend. JDWP allows one
debugger per process, so ShadowDroid's and Studio's debuggers cannot attach to
the same process at once.

• shadowdroid init installs the agent skills only. --no-studio-plugin,
  --install-studio-plugin, --studio and --plugin are hidden and ignored,
  so old scripts keep working.
• shadowdroid studio, debug attach --dialog, and the backend auto-routing
  (backend_reason) are removed. The hidden debug --backend still accepts
  auto and jdwp; studio is rejected.
• Config keys studio_url, android_studio, studio_plugin, debugger,
  debug_backend and run_configuration are deprecated and ignored. They
  still parse so configs load, and config validate warns.
  debug_mode still sets the default attach mode, now java, native or
  mixed.
• doctor no longer checks Studio or the plugin.

ShadowDroid runtime

Layout inspection, Compose recomposition counts and coroutine dumps no longer
need Android Studio or an app dependency: the CLI attaches its own in-process
runtime to any debuggable app, the mechanism Android Studio's Layout Inspector
uses.

• runtime attach|status|detach: a JVMTI agent (libshadowdroid_agent.so,
  published per ABI and verified by checksum) is copied in with run-as and
  loaded with attach-agent, or at process start with --startup. A
  per-process host daemon talks to it over an adb abstract socket that accepts
  only adbd and requires a per-attach token. Detach restores every hooked
  class.
• Layout on the runtime: layout snapshot --compose/--semantics/--source-map,
  layout recompositions, layout source, ui dump --deep and
  ui tap --fallback-id read the app's own Compose inspector (version-matched
  from the app's Compose UI dependency) and a built-in view inspector, and
  attach on demand. Source files resolve under --project-root, with the
  Compose package hash telling same-named files apart. Results carry
  backend: runtime and backend_reason.
• runtime coroutines: live coroutines (state, context, suspension and
  creation stacks) from the app's kotlinx DebugProbes, with no build changes;
  runtime attach --startup --restart --coroutine-probes tracks from process
  start.
• Doctor: doctor --app <pkg> adds an advisory runtime check (run-as,
  API level for attach and startup attach).

Removed, with no compatibility shims:

• The in-app debug AAR, its OkHttp companion, and the aar verbs
  (install/status/remove/agent/capture/intercept/resume/drop/coroutines),
  including the Gradle dependency rewriting and the coroutine-probes ASM
  block. Coroutine dumps moved to runtime coroutines; interception stays on
  the net proxy, and in-process network capture is planned for the runtime.
• The Android Studio plugin's Layout Inspector routes (/v1/layout/*).
• --studio-url on layout and ui dump/tap, and the hidden
  --studio-wait-ms alias (use...

ShadowDroid v1.3.0

ShadowDroid v1.3.0

This release adds fault injection, deeper Android Studio integration and
incremental UI reads. It also includes a full audit and a release-wide QA pass
with more than 90 reliability fixes since v1.2.0.

• Fault injection: shadowdroid fault puts the device or app into 37
  failure conditions and undoes them reliably: network (airplane mode, network
  flaps, DNS failure), power (Doze, standby buckets, low battery), lifecycle
  (process death, don't-keep-activities), configuration (font scale, display
  size, locale, orientation), resources, interruptions (calls, SMS, PiP) and
  emulator-only kinds. Each fault records how to undo itself before touching the
  device, verifies it took effect, and shows up in watch and why.
  Proxy faults (http-errors, http-latency, bandwidth, connection-reset,
  truncated-response, tls-failure) mark every request they hit and pick
  requests from a seed. fault run replays seeded multi-step scenarios.
  See shadowdroid commands --guide faults.
• Android Studio: layout snapshots link elements to their Compose source,
  layout recompositions can show only the nodes that recomposed, and layout
  commands open the device in Running Devices and turn on Layout Inspector
  themselves. studio status and debug status report installed and running
  plugin versions and which Studio internals the plugin can reach. Debugger
  steps wait for their pause, all suspended threads are listed, method,
  exception and Kotlin field breakpoints work, breakpoint files are found by
  name, and reads right after a pause wait for Studio to settle it instead of
  failing.
• UI: ui dump --since <screen_hash> reports only what changed. Taps
  resolve focus on the intended target, and watch stdin taps accept selectors.
• Network: captures record the HTTP version on both legs and the origin's
  content-encoding when the proxy decodes a body. HAR exports carry query
  strings, cookies and redirect URLs. curl exports replay HEAD requests, quote
  methods, never read local files named by a body, and flag replays that cannot
  resend the app's body. Upstream errors keep their cause, a crashed proxy
  daemon recovers, and net replay --clear stops serving fixtures.
• Verification: journey steps retry a guarded action the server refused
  before injecting anything, instead of failing while the screen settles after
  text entry, and ui wait decides on a consistent snapshot. Commits that leave
  the verified sources unchanged no longer make results stale.
• Safer defaults: interrupted operations quarantine a device only when a
  mutation's outcome is unknown, doctor without --fix is read-only and only
  repairs state ShadowDroid owns, cross-signed server installs recover
  automatically, and captured bodies, reports and logs are written owner-only.
• Agent contract: more failures carry typed codes instead of the generic
  fallback, and usage errors name the missing arguments. Contradictory or no-op
  flags are refused rather than ignored, and a rule or override with no matcher
  warns that it hits all traffic. The catalog lists every guide topic and root
  flag.
• Supply chain and release: the ADB client now speaks the ADB protocol
  in-tree, which removes adb_client and its rsa dependency, and
  cargo audit passes without exceptions. Releases publish only after CI
  passes on the tagged commit.

Compatibility: the root --session driver token is no longer a global flag.
Pass it before the subcommand (shadowdroid --session TOKEN ui dump), as the
documentation already did, or set SHADOWDROID_SESSION. Placed after a
subcommand it used to leak into that subcommand's own --session.

Fault injection changes real device settings; destructive kinds need
--allow-physical on a phone. Layout Inspector stays on after layout commands,
and Studio then injects its inspector agent into each app launch; turn it off
in Studio before timing- or crash-sensitive runs.

Validation includes 814 Rust tests, strict Clippy, Studio plugin tests, and an
API 36 emulator sweep across lifecycle, UI, apps, permissions, files, video,
debugging and watch. An isolated Android Studio ran debugger, logpoint and
layout checks. Every fault kind was injected, verified and cleared live, and
the fault contracts were checked. The verification, Android surface and
reliability end-to-end suites also passed.

Install or upgrade on macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/download/v1.3.0/shadowdroid-installer.sh | sh -s -- --version v1.3.0

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/download/v1.3.0/shadowdroid-installer.ps1 | iex"

Homebrew: brew upgrade andriyo/tap/shadowdroid. Scoop: scoop update shadowdroid
with the ShadowDroid bucket configured. APKs, agent AARs, Studio plugin, installers,
CLI archives, checksums and release provenance accompany this GitHub release.
Crates.io and IDE marketplace publication are separate distribution channels.

ShadowDroid v1.2.0

ShadowDroid v1.2.0

This release adds experimental requirement verification and coordinated local
agent sessions. It also includes the reliability fixes developed since v1.1.0.

• Verification plans and evidence: versioned requirement/check mappings,
  bounded execution, JUnit ingestion and baseline regression comparison,
  durable evidence, source/artifact freshness and explicit unresolved outcomes.
• Android behavior checks: guarded journeys, distinct lifecycle experiments,
  configuration matrices with owned-state restoration, SQLite/Room snapshots,
  visual comparison bundles and accessibility findings.
• Build and platform contracts: fresh APK build/install identity, resolved
  Gradle dependencies, source constraints, and named instrumentation assertions
  for intents, MediaSession release, widget updates and Picture-in-Picture.
• Concurrent agents: one driver per device, passive observers, independent
  crash subscriptions, explicit handoff, interrupted-operation quarantine and
  recovery. Independent devices can proceed concurrently.
• Agent guidance and evaluation: shadowdroid commands --guide verification,
  independent Android acceptance tests, and a frozen local coding-agent trial
  harness that retains unsuccessful and timed-out attempts.
• TLS dependency fix: rustls 0.23.45 addresses
  RUSTSEC-2026-0285.
• Reliability: preserve unknown network observations, verify proxy teardown,
  normalize JSON discovery, bound target contention, and release CA leases
  explicitly when concurrent child processes inherit file descriptors.
  Journey keys use guarded input and mandatory observed postconditions, without
  replaying Android's ambiguous injection results.
  Font-scale recovery waits for delayed framework configuration writes to settle.
  Theme restoration preserves custom schedule and bedtime modes.

The new adapters remain experimental. Local cooperative sessions do not fence
direct ADB/HTTP/IDE clients. Pixel comparison is not a semantic visual judge;
SQLite checks stop the app; platform assertions cover only their named tests.
Camera/Wear, distributed coordination and deeper headless inspection remain
conditional work. No Android Bench score or agent-performance uplift is claimed.

Validation includes positive/defective emulator fixtures, two-device concurrency
and interruption recovery, 701 Rust tests, Android lint/unit tests, strict
Clippy, minimum Rust 1.91, and package/consumer checks. Both two-minute coding
trial patches passed independent Android checks; both agents timed out without
completion claims. Workflow outcomes and public artifact validation are recorded
in the release's companion documentation after publication.

Read the verification guide
and session guide.

Install or upgrade on macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/download/v1.2.0/shadowdroid-installer.sh | sh -s -- --version v1.2.0

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/download/v1.2.0/shadowdroid-installer.ps1 | iex"

Homebrew: brew upgrade andriyo/tap/shadowdroid. Scoop: scoop update shadowdroid
with the ShadowDroid bucket configured. APKs, agent AARs, Studio plugin, installers,
CLI archives, checksums and release provenance accompany this GitHub release.
Crates.io and IDE marketplace publication are separate distribution channels.

ShadowDroid v1.1.0

ShadowDroid 1.1

ShadowDroid 1.1 adds correlated investigation evidence, recording coverage, and more precise network failure experiments, with fixes that keep credentials redacted and failed requests visible.

Highlights

• Capture evidence checkpoints that correlate UI, network, video, and selected private app state, then build a timeline across checkpoints. Missing sources are reported as partial evidence.
• Inspect recording coverage, missing segments, and marker ranges without treating host timestamps as exact video positions.
• Apply guarded, one-shot JSON response edits matched to request operations, clear HTTP interception explicitly, and abort downstream transport when simulating a lost response.
• Use bounded lifecycle-lock waits and executable local recovery handles for redacted device references.

Fixes

• Preserve source keys and sensitive ancestors before projecting evidence values. Passwords, opaque tokens, configured sensitive fields, and known-value aliases stay redacted; fingerprints and explicit JWT claims continue to use original input.
• Persist ordinary HTTP drops and fail-closed timeout drops exactly once, including the synthetic response sent to the app.
• Record OkHttp failures before a response returns, preserving request metadata and duration while rethrowing the original exception.
• Honor the selected device when attaching to or listing Android clients, reject unsupported capture host filters before setup, and remove hidden idle waits from guarded actions and screen reads.
• Upgrade quick-xml to 0.41.0 to resolve RUSTSEC-2026-0194 and RUSTSEC-2026-0195, preserve SharedPreferences entity handling, and update the yanked chacha20 dependency to 0.10.2.
• Retire stale duplicate managed skills while preserving custom guidance.
• Bundle the evidence driving guide inside the CLI crate so packaged source builds compile without the repository's outer documentation directory.

Install

macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/download/v1.1.0/shadowdroid-installer.sh | sh -s -- --version v1.1.0

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Then connect to an attached device or running emulator:

shadowdroid connect

The release includes CLI archives for five host targets, the Android server APK pair, Android Studio plugin, core agent AAR, and optional OkHttp companion AAR. SHA256SUMS covers the published artifacts; RELEASE_PROVENANCE.json records their source commit and workflow run.

Full changelog: v1.0.0...v1.1.0

Release source mapping

After a commit metadata correction on 2026-09-09, v1.1.0 points to d43208b001a177e3220bb8a775bb6fbb5f2f8f04. Its source tree is identical to the original build commit 1cce703bb3cfb099ff1bd9d1c75e25b1aacb44f2. The published artifacts, checksums and RELEASE_PROVENANCE.json are unchanged; provenance continues to identify the original build commit and workflow run.

ShadowDroid v1.0.0

ShadowDroid 1.0

ShadowDroid 1.0 establishes the stable agent-facing contract for Android automation and debugging: observable preconditions, explicit effects, structured failures, and verifiable postconditions across UI, app state, debugger, layout, and network workflows.

Highlights

• Added first-class non-suspending debugger logpoints with replay cursors, filtering, redaction, and deterministic cleanup.
• Made UI action guards authoritative and app-state recovery crash-safe.
• Added machine-readable command/effect contracts so agents can inspect side effects before execution.
• Made network fixture replay exact, rule sets typed and explainable, publication atomic, and persisted metadata redacted.
• Added WebSocket protocol evidence and deterministic model/property tests for the network stack.
• Expanded the Field Lab and CI to exercise real CLI/APK journeys on Android 16/API 36 phone and TV surfaces.
• Hardened the release pipeline with cross-platform installer smoke tests, checksums, and release provenance.

Install

macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Then connect to an attached device or running emulator:

shadowdroid connect

Every published artifact is covered by SHA256SUMS; RELEASE_PROVENANCE.json records the source commit and release workflow run.

Full changelog: v0.16.1...v1.0.0

ShadowDroid v0.16.1

ShadowDroid v0.16.1

Install macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Install Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Run:

shadowdroid connect

ShadowDroid v0.15.0

ShadowDroid v0.15.0

Install macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Install Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Run:

shadowdroid connect

ShadowDroid v0.14.0

ShadowDroid v0.14.0

Install macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Install Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Run:

shadowdroid connect

ShadowDroid v0.13.0

ShadowDroid v0.13.0

Install macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Install Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Run:

shadowdroid connect

ShadowDroid v0.12.0

ShadowDroid v0.12.0

Install macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.sh | sh

Install Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/andriyo/ShadowDroid/releases/latest/download/shadowdroid-installer.ps1 | iex"

Run:

shadowdroid connect