DroidMind

# Chapter 4: Application Management DroidMind equips your AI assistant with a comprehensive suite of tools for managing applications on your Android devices. This chapter details how to list installed packages, install and uninstall apps, control their lifecycle (start, stop, clear data), and inspect various application details like manifests, permissions, and activities. Remember to replace `emulator-5554` or `your_device_serial` with your target device's serial, and use correct package names (e.g., `com.example.myapp`) in your queries. ## 4.1 Listing Installed Packages Discover what applications are installed on a device. **How to ask your AI assistant:** > "List all installed third-party apps on `emulator-5554`." > "Show me all packages, including system apps, on `your_device_serial`." > "What applications are on `emulator-5554`?" **Expected DroidMind Action:** DroidMind will use the `list_packages` tool. - `include_system_apps` (optional, default `False`): Set to `True` to include system applications in the list. Otherwise, only third-party (user-installed) apps are shown. **Example Response from AI:** ``` Okay, here are the installed third-party packages on `emulator-5554`: # Installed Packages | Package Name | APK Path | |-----------------------|-----------------------------------------------| | `com.example.app1` | `/data/app/~~random_string==/com.example.app1-another_random==/base.apk` | | `com.example.another` | `/data/app/~~different_string==/com.example.another-more_random==/base.apk` | | `org.thirdparty.util` | `/data/app/~~and_another==/org.thirdparty.util-random_again==/base.apk` | ``` ## 4.2 Installing Applications (APKs) Your AI assistant can install applications using their APK files. The APK file must be accessible from the machine where DroidMind is running. **How to ask your AI assistant:** > "Install the app from `/Users/bliss/Downloads/new_app.apk` on `emulator-5554`." > "On `your_device_serial`, install `C:\APKs\utility.apk`, reinstall if it exists, and grant all permissions." **Important:** The `apk_path` you specify must be a local path on the machine where the DroidMind server process is running. **Expected DroidMind Action:** DroidMind will use the `install_app` tool. - `apk_path`: The local path to the APK file. - `reinstall` (optional, default `False`): Set to `True` to allow reinstallation (equivalent to `adb install -r`). - `grant_permissions` (optional, default `True`): Set to `True` to grant all declared permissions at install time (equivalent to `adb install -g`). **Example Response from AI:** ``` I'm installing `/Users/bliss/Downloads/new_app.apk` on `emulator-5554`... ✅ Successfully installed APK on device emulator-5554 ``` Or if it failed: ``` ❌ Failed to install APK: INSTALL_FAILED_INSUFFICIENT_STORAGE ``` ## 4.3 Uninstalling Applications Remove applications from a device. **How to ask your AI assistant:** > "Uninstall the package `com.example.oldapp` from `emulator-5554`." > "Remove `com.thirdparty.bloatware` from `your_device_serial` but keep its data." **Expected DroidMind Action:** DroidMind will use the `uninstall_app` tool. - `package`: The package name of the app to uninstall. - `keep_data` (optional, default `False`): Set to `True` to keep the app's data and cache directories (equivalent to `adb uninstall -k`). **Example Response from AI:** ``` Uninstalling package `com.example.oldapp` from `emulator-5554`... ✅ Successfully uninstalled `com.example.oldapp` from device `emulator-5554` ``` Or, if keeping data: ``` ✅ Successfully uninstalled `com.thirdparty.bloatware` from device `your_device_serial` (keeping app data) ``` ## 4.4 Starting Applications Launch an application on the device. You can start its default main activity or specify a particular activity. **How to ask your AI assistant:** > "Start the app `com.example.myapp` on `emulator-5554`." > "Launch the activity `.ui.SettingsActivity` for package `com.example.myapp` on `your_device_serial`." > "Open `com.android.settings` on `emulator-5554`." **Expected DroidMind Action:** DroidMind will use the `start_app` tool. - `package`: The package name of the app. - `activity` (optional): The specific activity to start. If empty, DroidMind attempts to launch the default main activity. Activity names can be relative (e.g., `.MainActivity`) or fully qualified (e.g., `com.example.myapp.MainActivity`). **Example Response from AI:** ``` Starting app `com.example.myapp` on `emulator-5554`... ✅ Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.example.myapp/.MainActivity } ``` If an error occurs (e.g., app not found, activity not found): ``` ❌ Error: Activity not started, component specified did not match any known component ``` ## 4.5 Stopping Applications (Force Stop) Forcefully stop a running application. **How to ask your AI assistant:** > "Stop the app `com.example.myapp` on `emulator-5554`." > "Force stop `com.thirdparty.service` on `your_device_serial`." **Expected DroidMind Action:** DroidMind will use the `stop_app` tool. **Example Response from AI:** ``` Stopping app `com.example.myapp` on `emulator-5554`... ✅ Force stopped `com.example.myapp` ``` ## 4.6 Clearing Application Data and Cache Reset an application to its default state by clearing its data and cache. **How to ask your AI assistant:** > "Clear the app data for `com.example.myapp` on `emulator-5554`." > "Reset `com.example.anotherapp` on `your_device_serial` by clearing its data." **Expected DroidMind Action:** DroidMind will use the `clear_app_data` tool. **Example Response from AI:** ``` Clearing data for app `com.example.myapp` on `emulator-5554`... ✅ Successfully cleared data for package `com.example.myapp` ``` If it fails: ``` ❌ Failed to clear data for package `com.example.myapp`: Package not found ``` ## 4.7 Getting Detailed App Information Retrieve a summary of information about a specific installed application. **How to ask your AI assistant:** > "Get detailed information about the app `com.android.settings` on `emulator-5554`." > "Show me info for `com.example.myapp` on `your_device_serial`." **Expected DroidMind Action:** DroidMind will use the `get_app_info` tool. **Example Response from AI:** ``` # App Information for com.android.settings - **Version**: 12.0 - **Install Path**: /system/priv-app/SettingsProvider/SettingsProvider.apk - **First Install**: 2022-01-01 10:00:00 - **User ID**: 1000 - **App Size**: 5.3M (from du -sh) - **Status**: Running ## Permissions - android.permission.ACCESS_NETWORK_STATE - android.permission.WRITE_SETTINGS ... ``` ## 4.8 Inspecting App Manifests The `AndroidManifest.xml` file contains essential information about an app, including its components, permissions, and features. DroidMind can retrieve and parse this for you. **How to ask your AI assistant:** > "Show me the manifest for `com.example.myapp` on `emulator-5554`." > "Get the AndroidManifest for `com.android.settings` on `your_device_serial`." **Expected DroidMind Action:** DroidMind will use the `get_app_manifest` tool. **Example Response from AI:** ``` # App Manifest for com.example.myapp ## Package Information - **Version Code**: 101 - **Version Name**: 1.0.1 - **Min SDK**: 23 - **Target SDK**: 33 - **Install Path**: /data/app/~~...==/com.example.myapp-...==/base.apk - **First Install**: 2023-01-15 10:00:00 - **User ID**: 10123 ## Permissions ### Declared Permissions No declared permissions. ### Requested Permissions - `android.permission.INTERNET` - `android.permission.ACCESS_FINE_LOCATION` ## Components ### Activities - `com.example.myapp/.MainActivity` Intent Filters: - Action: android.intent.action.MAIN - Category: android.intent.category.LAUNCHER - `com.example.myapp/.SettingsActivity` ### Services - `com.example.myapp/.background.MyBackgroundService` ### Content Providers No Content Providers found. ### Broadcast Receivers - `com.example.myapp/.receivers.BootCompletedReceiver` Intent Filters: - Action: android.intent.action.BOOT_COMPLETED ``` ## 4.9 Retrieving App Permissions Focus specifically on the permissions declared and requested by an application, including their runtime status. **How to ask your AI assistant:** > "What permissions does `com.example.myapp` use on `emulator-5554`?" > "Show the permission details for `com.android.camera` on `your_device_serial`." **Expected DroidMind Action:** DroidMind will use the `get_app_permissions` tool. **Example Response from AI:** ``` # Permissions for com.example.myapp ## Permissions ### Declared Permissions No declared permissions. ### Requested Permissions - `android.permission.INTERNET` - `android.permission.ACCESS_FINE_LOCATION` ## Runtime Permission Status ``` runtime permissions: android.permission.ACCESS_FINE_LOCATION: granted=true, flags=[ GRANTED_BY_DEFAULT|REVIEW_REQUIRED ] ``` This app has requested Internet and Fine Location access. Fine Location is currently granted. ``` ## 4.10 Listing App Activities List all the activities defined within an application and identify the main launchable activity. **How to ask your AI assistant:** > "List the activities for `com.example.myapp` on `emulator-5554`." > "What are the defined activities in `com.android.settings` on `your_device_serial`?" **Expected DroidMind Action:** DroidMind will use the `get_app_activities` tool. **Example Response from AI:** ``` # Activities for com.example.myapp Found 2 activities: - `com.example.myapp/.MainActivity` Intent Filters: - Action: android.intent.action.MAIN - Category: android.intent.category.LAUNCHER - `com.example.myapp/.SettingsActivity` ## Main Activity ``` com.example.myapp/.MainActivity ``` The main launchable activity is `.MainActivity`. ``` --- Up next, we'll cover how to execute general shell commands on your device in **[Chapter 5: Shell Command Execution](shell_commands.md)**.