android

Orchestrates Android development tasks including project creation, deployment, SDK management, and environment diagnostics using the `android` command-line tool.

Use to find stuck coroutines, leaked jobs, and suspended awaits with no resumer — the concurrency bugs that don't crash but cause hangs, missing UI updates, or memory creep. Ephemerally add `kotlinx-coroutines-debug`, install `DebugProbes` in `Application.onCreate`, run the suspect flow, dump active coroutines with stack traces, fix, then remove the dependency and the install/dump calls. Reach for this when `Log.d` shows a `launch` ran but `collect` never received, or a screen leaves and something keeps running.

Use to flush out intermittent crashes and ANRs ("it crashes sometimes," "fails on slow devices," "happens after rotation a few times") by scripting the trigger sequence with `adb shell input` and running it in a shell loop against a cleared logcat, stopping on first match for `FATAL EXCEPTION` or `ANR in`. Inject deterministic stress (rotation, slow network, low memory) to surface latent races. The empirical answer to "is this still a bug, and under what conditions?"

Use to extract concrete numbers and slice-level evidence from a `.perfetto-trace` captured by `android-perfetto-capture`. Run SQL queries against the trace via the `trace_processor` binary, then hand the (small) result file to a Sonnet sub-agent for verdict — never read raw trace data inline. This is where "the app feels slow" becomes "frame 42 missed budget by 8.3 ms because `MainActivity.onResume` ran 18 ms on `main` while the IO dispatcher was idle." The analysis half of the perfetto loop.

Use to capture Perfetto system traces from a connected Android device — the input for any timing, threading, jank, or "is this on the main thread?" investigation. Writes a self-contained `.perfetto-trace` file to `/tmp` that downstream skills (`android-perfetto-analyze`, `android-trace-sections`) read with the `trace_processor` SQL backend. Pick the strategy that matches the question (one-shot, repeated, on-the-fly), drive the suspect flow during the recording window, and verify the trace contains the expected slices before declaring capture done.

Use when you need empirical proof a code path actually executed — branch entries, callback fires, coroutine continuations, suspect early returns. Insert temporary `Log.d` calls with a unique sentinel tag, redeploy, drive the app, read filtered logcat, then remove every probe before declaring done. The default investigation skill when the question is "did this run, in what order, with what values?"

Use INSTEAD of git bisect when investigating a regression between two refs (releases, branches, "it worked yesterday") — especially when builds are slow or the bug is hard to reproduce. Hand the full `git diff <good> <bad>` to a Sonnet sub-agent along with the bug description and let it surface suspect areas. Bisect exists because humans can't reason about thousands of lines at once. LLMs can. No builds, no waiting — minutes instead of an hour of compiling.

Use BEFORE fixing any non-trivial bug. Write a test that fails because of the bug, watch it fail, then fix the bug until the test passes. Forces the agent to demonstrate the bug exists in code before guessing at fixes — and leaves a regression guard. Trigger whenever you'd otherwise edit production code based on a stack trace, user report, or "I think the issue is…" hypothesis.

Use to flip framework-level diagnostics without code changes — verbose framework logging (`log.tag.<Tag> VERBOSE`), view-bounds overlay (`debug.layout`), overdraw flashes, frame-time bars, slow-animation toggles. Set via `adb shell setprop` for the duration of an investigation, then reset every flag. Reach for this when the question is about framework behavior or rendering — and code changes feel like overkill for a quick look.

Use to prove (or disprove) that a state actually changed between two points — "did the dialog dismiss?", "did this navigation actually leak memory?", "did my fix do anything?". Capture a snapshot bundle (layout JSON, dumpsys meminfo, getprop, screenshot) at point A, perform the action, capture at point B, diff. The empirical answer to "did anything change?" — useful when the agent suspects its own fix is a no-op.

Use to surface invisible main-thread I/O, leaked closeables, leaked activities, and other policy violations that don't crash but cause jank, ANRs, or memory creep. Temporarily install StrictMode in `Application.onCreate` with `.penaltyLog()`, drive the suspect flow, read logcat for `StrictMode policy violation`, fix the violations, then remove the StrictMode setup. Trigger when the symptom is "feels slow," "occasionally janks," "leaks across rotations," or any concern about silent main-thread work.

Use to answer questions logging can't — "did this run, on what thread, for how long, in what overlap with frame boundaries?" Wrap suspect operations in `Trace.beginSection("AGENT_TRACE_<id>")` / `Trace.endSection()`, capture a Perfetto trace, inspect the named slice. Better than `Log.d` when the question is about timing, threading, or whether a block fits inside a frame budget. Reach for this for jank, slow startup, dropped frames, and "is this on the main thread?" investigations.

Use when the user wants to scaffold, bootstrap, or create a new Android project from scratch. Produces an opinionated single-module Compose app with Metro DI, Circuit (Slack) state/architecture, Material You theming, Coil 3 images, kermit logging, Ktor networking, and Firebase Crashlytics — plus a CLAUDE.md/AGENTS.md pair and ergonomic runDebug/runRelease Gradle tasks.

Use FIRST when verifying any UI state on an Android emulator or device — checking that elements rendered, text appears, state is correct, or a fix landed. Reads the structured JSON tree from `android layout`, which is faster and cheaper than a screenshot for almost everything except WebViews, animations, and purely visual checks (color, font, image content).

Use when verifying an Android UI state requires a real screenshot — WebView content, animations, visual fidelity (color, font, image content, alignment), or finding an element by appearance when you don't know its resource id. For everything else, prefer `verify-android-layout` first — JSON is cheaper and more precise. Triggers whenever you'd otherwise read a PNG from `android screen capture` in the main thread.