Android App

Connecting to a Device

Wireless Debugging (Android 11+, no USB needed)

IMPORTANT: Pairing codes expire quickly - have Claude ready before opening the pairing dialog.

1. On phone: Settings → Developer options → Wireless debugging → Enable
2. Tap "Pair device with pairing code" - note the pairing IP:port and code
3. On Mac (pass code as argument, not interactively):

   adb pair <ip>:<pairing-port> <pairing-code>
   

4. Back on phone, note the connection IP:port under "Wireless debugging" (different port!)
5. Connect:

   adb connect <ip>:<connection-port>
   

Gotchas:

• After pairing, adb devices shows TWO entries (IP:port and mDNS name). Always use the IP:port form with -s flag - the mDNS entry sometimes fails:

  adb -s 10.1.1.209:42917 install app/build/outputs/apk/debug/app-debug.apk
  

• Some phones disable wireless debugging on reboot - re-enable in Developer options
• Connection drops on sleep/network change - just adb connect again (port may change)

USB Connection

1. Enable Developer options (tap Build number 7 times in About phone)
2. Enable USB debugging in Developer options
3. Connect USB cable
4. On phone: tap "Allow USB debugging" when prompted (or adb devices shows "unauthorized")
5. Check connection: adb devices

Building a Simple App

Version Compatibility

This skill uses AGP 8.2.0 + Gradle 8.4 + Java 17 - a tested compatible combination.

• AGP (Android Gradle Plugin) version determines required Gradle and Java versions
• See AGP compatibility table if updating

Project Structure

Create all files:

mkdir -p /tmp/myapp/app/src/main/java/com/example/myapp
mkdir -p /tmp/myapp/app/src/main/res/drawable
mkdir -p /tmp/myapp/app/src/main/res/mipmap-anydpi-v26
mkdir -p /tmp/myapp/gradle/wrapper
cd /tmp/myapp

File List

/tmp/myapp/
├── settings.gradle.kts
├── build.gradle.kts
├── gradle.properties
├── gradle/wrapper/
│   └── (generated by gradle wrapper)
└── app/
    ├── build.gradle.kts
    └── src/main/
        ├── AndroidManifest.xml
        ├── java/com/example/myapp/
        │   └── MainActivity.java
        └── res/
            ├── drawable/
            │   └── ic_launcher_foreground.xml
            └── mipmap-anydpi-v26/
                └── ic_launcher.xml

settings.gradle.kts

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "myapp"
include(":app")

build.gradle.kts (root)

plugins {
    id("com.android.application") version "8.2.0" apply false
}

gradle.properties

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
android.useAndroidX=true

app/build.gradle.kts

plugins {
    id("com.android.application")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="My App"
        android:icon="@mipmap/ic_launcher"
        android:theme="@android:style/Theme.Material.Light">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

app/src/main/java/com/example/myapp/MainActivity.java

package com.example.myapp;

import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;
import android.view.Gravity;

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        TextView tv = new TextView(this);
        tv.setText("Hello World!");
        tv.setTextSize(24);
        tv.setGravity(Gravity.CENTER);
        setContentView(tv);
    }
}

app/src/main/res/drawable/ic_launcher_foreground.xml

Design a unique icon for each app. The icon should visually represent what the app does. Use vector drawables with simple shapes - they scale perfectly and keep APK size small.

Example structure (customize colors and pathData for each app):

<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="108dp"
    android:height="108dp"
    android:viewportWidth="108"
    android:viewportHeight="108">
    <!-- Background shape (circle, rounded rect, etc.) -->
    <path
        android:fillColor="#3DDC84"
        android:pathData="M54,54m-40,0a40,40 0,1 1,80 0a40,40 0,1 1,-80 0"/>
    <!-- Foreground symbol -->
    <path
        android:fillColor="#FFFFFF"
        android:pathData="M44,44L64,54L44,64Z"/>
</vector>

Icon design tips:

• Viewport is 108x108, but keep content within center 72x72 (safe zone for adaptive icons)
• Use simple geometric shapes: circles (M cx,cy m-r,0 a r,r 0 1,1 2r,0 a r,r 0 1,1 -2r,0), rectangles, triangles
• 2-3 colors max for clarity at small sizes
• Common symbols: play triangle, gear, chat bubble, checkmark, music note, camera

app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@android:color/white"/>
    <foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>

Build

cd /tmp/myapp
gradle wrapper --gradle-version 8.4

# Must use Java 17 (AGP 8.2.0 requirement)
JAVA_HOME=/opt/homebrew/opt/openjdk@17 \
ANDROID_HOME=/Users/kim/Library/Android/sdk \
./gradlew assembleDebug

# APK at: app/build/outputs/apk/debug/app-debug.apk

Installing on Device

# Install (use -s if multiple devices; always prefer IP:port form)
adb -s <device-id> install app/build/outputs/apk/debug/app-debug.apk

# Reinstall/update existing app
adb -s <device-id> install -r app/build/outputs/apk/debug/app-debug.apk

# Launch the app
adb -s <device-id> shell am start -n com.example.myapp/.MainActivity

# Uninstall
adb uninstall com.example.myapp

Self-Update from GitHub Releases

For apps distributed via GitHub releases, add a self-update mechanism:

Required permissions and setup

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

<!-- Inside <application>, for sharing the downloaded APK with the installer -->
<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

<!-- res/xml/file_paths.xml -->
<paths><cache-path name="apk_updates" path="updates/" /></paths>

Version tracking

Use version.properties alongside build.gradle.kts:

VERSION_CODE=1
VERSION_NAME=1.0

Read in gradle:

val versionProps = java.util.Properties().apply {
    load(file("version.properties").inputStream())
}
defaultConfig {
    versionCode = versionProps["VERSION_CODE"].toString().toInt()
    versionName = versionProps["VERSION_NAME"].toString()
}

Update flow

1. Fetch https://api.github.com/repos/OWNER/REPO/releases/latest
2. Find the .apk asset URL from the assets array
3. Validate the host — must be github.com, *.github.com, or *.githubusercontent.com
4. Download to getCacheDir()/updates/app-update.apk
5. Verify the APK signature (see below)
6. Use FileProvider.getUriForFile() + ACTION_VIEW intent to launch the system installer

TOFU signature verification

After downloading, verify the APK is signed with the same certificate as the installed app. This prevents installing a tampered APK if the GitHub release is compromised.

// Get SHA-256 digest of a signing certificate
private static String certSha256(android.content.pm.Signature sig) {
    byte[] digest = java.security.MessageDigest.getInstance("SHA-256").digest(sig.toByteArray());
    StringBuilder sb = new StringBuilder(digest.length * 2);
    for (byte b : digest) sb.append(String.format("%02x", b & 0xff));
    return sb.toString();
}

// Compare installed vs downloaded APK certs
// Use GET_SIGNING_CERTIFICATES on API 28+, GET_SIGNATURES on older
// Use PackageManager.getPackageArchiveInfo() to read the downloaded APK's certs
// If no cert digest matches, delete the APK and abort

Why TOFU, not hardcoded cert digests? The hardcoded digest lives in the APK itself — an attacker who can replace the APK can patch the digest too. TOFU is equally secure and doesn't break on signing key rotation. This is exactly how Android's own package update system works.

See kim-em/claude-chat for a complete working implementation.

Useful ADB Commands

# Check connected devices
adb devices

# View device logs (filter by package)
adb logcat --pid=$(adb shell pidof com.example.myapp)

# Push file to device
adb push local-file.txt /sdcard/Download/

# Pull file from device
adb pull /sdcard/Download/file.txt ./

# Open shell on device
adb shell

# Take screenshot
adb exec-out screencap -p > screenshot.png

# List installed packages
adb shell pm list packages | grep myapp

Troubleshooting

"more than one device/emulator":

• Use adb -s <device-id> to specify which device
• Run adb devices to see device IDs
• Prefer the IP:port form over mDNS names

Build fails with Java version error:

• AGP 8.2.0 requires Java 17 (not newer like Java 21/25)
• Set JAVA_HOME=/opt/homebrew/opt/openjdk@17 before building

"unauthorized" in adb devices:

• Check phone for "Allow USB debugging?" prompt and tap Allow
• If no prompt, revoke USB debugging authorizations in Developer options and reconnect

"no devices/emulators found":

• For wireless: ensure same WiFi network, re-enable wireless debugging if rebooted
• For USB: try different cable (some are charge-only)

"INSTALL_FAILED_UPDATE_INCOMPATIBLE":

• Uninstall first: adb uninstall com.example.myapp

"INSTALL_FAILED_VERSION_DOWNGRADE":

• Increment versionCode in app/build.gradle.kts, or uninstall first

Notes

• Debug APKs are automatically signed with a debug key
• minSdk 24 = Android 7.0 (covers ~95% of devices)
• Pure Java is simpler than Kotlin for minimal apps (fewer dependencies)
• Build in /tmp to avoid cluttering project directories
• If you change compileSdk, install matching platform: sdkmanager "platforms;android-XX"