Live reload with --watch
Watch mode turns android_scaffold into a live prototyping loop. Save a Kotlin file and, a few seconds later, the app relaunches on the emulator or your phone with the change in place.
Key takeaways
--watchboots a device once, then rebuilds, reinstalls and relaunches on every save.- A "save all" across several files triggers one reload, not several.
- Compile errors don't stop the watcher. Fix and save again.
Start watching
python3 android_scaffold.py tap-counter --watchThe first launch does a full build, install and launch. After that the terminal waits:
[*] Watching 'tap-counter' for Kotlin changes. Press Ctrl+C to stop.
[*] Changed: MainActivity.kt
[+] Reloaded in 2.8s. Watching for changes...What happens on every save
- Detect. The source folder is checked once a second for added, removed or modified
.ktfiles. - Settle. It waits until nothing has changed for half a second, so an editor's "save all" becomes a single reload.
- Sync. Only the changed files are copied into
android_build/. New Activities are registered and deleted files removed. - Build. Gradle rebuilds incrementally. The Gradle daemon stays running between builds, so it is already warm.
- Relaunch. The APK is reinstalled with
adb install -rand the launcher Activity is restarted witham start -S.
When a save breaks the build
The Gradle error is printed as usual and the watcher keeps going:
[!] APK build failed with exit code 1.
[*] Reload failed. Still watching. Fix the error above and save again.The last working version of the app stays on the device, so you can keep comparing while you fix it.
App state resets on each reload
Each reload is a fresh install and launch, so in-memory state starts over. That is a feature for small-screen work: it constantly tests the cold start your users will see after the system kills your app in the background. If something important disappears, it would have disappeared for them too. See designing for interruptions.
Seed realistic sample data on first launch, as the Thumb Inventory example does, so every reload opens on a screen worth looking at.
Watch on a real phone
Plug in a phone with USB debugging enabled and --watch installs to it instead of booting an emulator. Then hold the phone the way your users will: one hand, standing up, maybe outdoors. Every reload is a chance to check thumb reach, target sizes and readability in real light, which an emulator on a big monitor can't show you.
Keeping reloads fast
- Keep files small and focused, so a change touches fewer compilation units.
- Leave the watcher running: the Gradle daemon and emulator stay warm.
- Use a recent x86_64 or arm64 emulator image that matches your computer's CPU.
- Close Android Studio's own Gradle sync on the same project, so two builds don't compete.
Frequently asked questions
Is this the same as Compose hot reload or Live Edit?
No. Live Edit patches code into a running app inside Android Studio and can keep state. android_scaffold's --watch does a fast incremental rebuild and a real reinstall and relaunch, so it works from any editor and always tests the real app, at the cost of resetting in-memory state.
How do I stop watch mode?
Press Ctrl+C in the terminal. The emulator keeps running, so the next --watch or --run starts faster.
Does --watch pick up new files and screens?
Yes. New .kt files are synced, new Activities are added to the manifest, and deleted files are removed from the generated project.