How it works

android_scaffold reads your Kotlin files, works out the packages and screens, and writes a standard Android Gradle project around them. Nothing is hidden: the output is a normal project you can open, read and keep.

Key takeaways

Your source folder stays clean. Everything generated goes into android_build/.
Packages, the application ID, the launcher and the manifest all come from your code.
Reruns are incremental: unchanged files are not rewritten, removed files are cleaned up.

What you write versus what it writes

You'd normally…	android_scaffold…
Choose and match AGP, Kotlin and Compose versions	Uses a known-good set with Jetpack Compose and Material 3
Create the `com/example/app/` folder tree	Puts each file in the right folder based on its `package` line
Register every Activity in `AndroidManifest.xml`	Finds your Activities and registers them, with `MainActivity` as the launcher
Choose an application ID	Uses the package of your `MainActivity`
Install Gradle, or commit a wrapper	Creates the Gradle wrapper for you
Point the build at your SDK	Finds the SDK on macOS, Windows or Linux and writes `local.properties`
Remember `adb` and `emulator` commands	Runs them, and prints a cheat sheet in case you want to run them by hand
Clean up code pasted from a chat	Removes leftover Markdown code fences

The generated project

android_build/
├── settings.gradle.kts           repositories, project name
├── build.gradle.kts              plugin versions
├── gradle.properties             JVM flags, AndroidX switches
├── local.properties              path to your SDK
├── gradlew  gradlew.bat          wrapper launchers
├── gradle/wrapper/…              wrapper jar and properties
└── app/
    ├── build.gradle.kts          SDK levels, Compose, dependencies
    └── src/main/
        ├── AndroidManifest.xml   every Activity, launcher intent
        ├── res/drawable/…        launcher icon
        └── java/com/example/app/ your Kotlin files, by package

That's the dozen files and roughly 220 lines of configuration you no longer write by hand.

Versions and SDK levels

Setting	Value
Gradle	9.9.0 (through the wrapper)
Android Gradle Plugin	9.5.1
Kotlin Compose compiler plugin	2.4.21
`compileSdk` / `targetSdk`	36
`minSdk`	26 (Android 8.0), which covers the vast majority of phones in use
Java target	17
Libraries	Compose BOM, Material 3, Activity Compose, AndroidX Core and AppCompat, Kotlin coroutines

The versions live as named constants at the top of android_scaffold.py if you need to change them.

How packages and the application ID are chosen

Every .kt file under the source folder is read (files ending in .gradle.kts are skipped).
The base package is the package of the file that declares MainActivity. If there is no MainActivity, the shortest declared package is used, and if no file declares one, com.example.singlefileapp.
Files without a package line get the base package added at the top.
The base package becomes both the Gradle namespace and the applicationId.

How Activities are found

Any class that extends ComponentActivity, AppCompatActivity, FragmentActivity or Activity is registered in the manifest. The one named MainActivity is the launcher; if none is named that, the first one found is. The launcher also gets intent filters so other apps can send it text and open CSV files with it, which is how the example app receives shared data without a backend.

All Activities declare configChanges for orientation and screen size, so rotating the phone doesn't recreate the screen. You should still save state properly, because the system can end your process in the background at any time.

Permissions

The generated manifest requests INTERNET, ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE, which are normal permissions granted at install time. They let apps move data between phones over local Wi-Fi or a hotspot. No runtime permission prompts are added.

Incremental by default

Every file is written only when its content changes, so Gradle's incremental build stays fast. Kotlin files deleted from your source folder are removed from the project. That is what makes live reload quick.

Frequently asked questions

Can I open the generated project in Android Studio?

Yes. android_build/ is a standard Gradle project. Open it in Android Studio to use the debugger, profiler or layout inspector, and keep editing your original source folder.

Should I commit android_build/ to Git?

No. It is regenerated from your source folder on every run, so add android_build/ and apk/ to .gitignore and commit only your Kotlin files.

Can I add my own dependencies?

The dependency list is part of the generated app/build.gradle.kts template inside android_scaffold.py. Add a line there and rerun the script; it is plain Python string formatting.