Introducing a new way to review your PRs.

Read the announcement

rikkaapps / shizuku

Using system APIs directly with adb/root privileges from normal apps through a Java process started with app_process.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / manager-app-shell-home-settings

Manager app shell, home, settings, and lifecycle infrastructure

Overview

The manager Android application is configured by manager/build.gradle as the moe.shizuku.privileged.api app, with view binding enabled, Material theme generation, release resource shrinking, native packaging for the bundled starter/shell pieces, and a build dependency on the :shell release/debug artifacts. manager/…/AndroidManifest.xml wires the covered shell: .MainActivity is the exported launcher and is only a thin Java subclass of manager/…/HomeActivity.kt; .settings.SettingsActivity handles the application preferences intent; .receiver.BootCompleteReceiver handles locked/unlocked boot; .receiver.ShizukuReceiver receives legacy binder requests; and .ShizukuManagerProvider exposes the app's Shizuku provider authority ${applicationId}.shizuku.

Application-wide initialization lives in manager/…/ShizukuApplication.kt. Its companion initializer configures libsu shell stderr redirection, applies hidden API exemptions on Android P+, and loads the native adb library on Android 11+. onCreate() stores the global application instance, initializes ShizukuSettings, sets LocaleDelegate.defaultLocale, and sets AppCompatDelegate night mode. Settings are stored in device-protected shared preferences named settings by manager/…/ShizukuSettings.java, so the boot receiver and direct-boot components can read them before user unlock. If credential-encrypted preferences are unavailable, ShizukuSettings falls back to EmptySharedPreferencesImpl instead of crashing.

All covered UI activities share the same activity base classes under manager/src/main/java/moe/shizuku/manager/app/. AppActivity.kt delegates user theme selection to ThemeHelper.java, applies Android 12 dynamic color overlays when enabled, and tunes translucent navigation bars. AppBarActivity.kt installs manager/…/appbar_activity.xml or appbar_fragment_activity.xml, both of which include manager/…/appbar.xml; child activities add their content below that toolbar. ThemeHelper.java reads light_theme, black_night_theme, and use_system_color from ShizukuSettings, returning either the normal theme overlay or ThemeOverlay.Black from manager/…/themes_overlay.xml. The default light/dark base themes and card attributes are defined in manager/…/themes.xml and manager/…/styles.xml, with manager/…/styles.xml switching AppTheme to the dark base.

The home screen is orchestrated by manager/…/HomeActivity.kt. It inflates manager/…/home_activity.xml, attaches a HomeAdapter, observes HomeViewModel.serviceStatus, observes the management AppsViewModel.grantedCount, and registers Shizuku binder-received/dead listeners. On a successful status load it refreshes the adapter and persists the last launch mode as root when the Shizuku server UID is 0, otherwise adb; this saved mode is later consumed by boot startup. The options menu in manager/…/main.xml opens settings, shows an about dialog backed by manager/…/about_dialog.xml, or asks Shizuku to exit.

manager/…/HomeViewModel.kt turns the remote Shizuku binder into the local ServiceStatus model in manager/…/ServiceStatus.kt. It pings the binder, reads server UID, API version, patch version, optional SELinux context, and tests whether the remote side has android.permission.GRANT_RUNTIME_PERMISSIONS. It also performs a remote permission transaction against Manifest.permission.API_V23 and the build application id so a stale server without manager permission is treated as unusable. ServiceStatus.isRunning is intentionally not just a data flag; it recomputes uid != -1 && Shizuku.pingBinder() whenever UI holders bind.

manager/…/HomeAdapter.kt constructs the home card list from that status. It always shows ServerStatusViewHolder; when adb/root permission is usable, it shows application management and terminal cards. If the server is running but the permission probe failed, it shows AdbPermissionLimitedViewHolder. For the primary Android user it adds root startup when EnvironmentUtils.isRooted() finds su, wireless adb startup on Android 11+ or when an adb tcp port property is already set, and the manual adb command card. values/values.xml uses a linear layout manager for phones, while values-sw600dp/values.xml switches the same recycler view to a staggered grid.

The individual home cards are small entry points into other flows. ServerStatusViewHolder.kt binds the running/not-running icon and version/update copy. ManageAppsViewHolder.kt launches ApplicationManagementActivity and shows the count supplied by AppsViewModel. TerminalViewHolder.kt launches ShellTutorialActivity; the terminal export flow depends on the bundled manager/src/main/assets/rish script, which locates rish_shizuku.dex, removes write permission from the dex on Android 14+, and runs rikka.shizuku.shell.ShizukuShellLoader via app_process. StartRootViewHolder.kt starts StarterActivity with EXTRA_IS_ROOT=true; StartAdbViewHolder.kt displays, copies, or shares Starter.adbCommand; and StartWirelessAdbViewHolder.kt either opens wireless adb discovery/pairing dialogs on Android 11+ or starts StarterActivity against the configured tcp port on older releases.

Wireless adb UI is split across AdbDialogFragment.kt, AdbPairDialogFragment.kt, and WadbNotEnabledDialogFragment.kt. AdbDialogFragment.kt discovers the TLS connect service with AdbMdns, optionally enables wireless adb globals when the app has WRITE_SECURE_SETTINGS, and starts StarterActivity with host 127.0.0.1 and the discovered port. AdbPairDialogFragment.kt discovers the TLS pairing port, validates the pairing port and code, creates an AdbKey in PreferenceAdbKeyStore(ShizukuSettings.getPreferences()), and runs AdbPairingClient; on multi-window/multi-display devices it allows direct dialog pairing, otherwise the card links to AdbPairingTutorialActivity. User-facing text for these flows is in manager/…/strings.xml, and the dialog layouts are manager/…/adb_dialog.xml and adb_pair_dialog.xml.

Settings are defined by manager/…/settings.xml and implemented by manager/…/SettingsActivity.kt plus SettingsFragment.kt. SettingsActivity is an AppBarFragmentActivity that applies the Rikka Material3 preference overlay and installs SettingsFragment. The fragment forces preference storage to device-protected settings, binds the boot component switch to the enabled state of BootCompleteReceiver, builds the generated locale list from rikka.shizuku.manager.ShizukuLocales, recreates the activity when locale/night/dynamic-color changes require it, hides black theme when night mode is forced off, hides dynamic colors before Android 12, and links translation actions to manager/…/strings_untranslatable.xml. IntegerSimpleMenuPreference.java is the custom integer-backed simple menu used for night_mode; its entries and values come from manager/…/arrays.xml and map directly to AppCompatDelegate constants (MODE_NIGHT_NO, MODE_NIGHT_YES, MODE_NIGHT_FOLLOW_SYSTEM).

Lifecycle receivers keep the manager connected to the service outside the foreground UI. manager/…/BootCompleteReceiver.kt accepts only locked/unlocked boot actions, ignores secondary users and already-running binders, and restarts Shizuku only when the last successful launch mode permits it. Root restart checks libsu root access and runs Starter.internalCommand; adb restart is Android 13+ only, requires WRITE_SECURE_SETTINGS, enables the relevant adb globals, discovers the TLS connect port with AdbMdns, and runs the internal starter command through AdbClient. manager/…/ShizukuReceiver.kt handles rikka.shizuku.intent.action.REQUEST_BINDER broadcasts by delegating to ShellBinderRequestHandler. manager/…/ShizukuManagerProvider.kt customizes ShizukuProvider.call() for sendUserService, attaching a user-service binder after Shizuku binder receipt and returning the current Shizuku binder in a BinderContainer.

Release packaging has two resource/name-shrinking safeguards in this area. manager/proguard-rules.pro keeps Parcelable creators, native methods, and main methods for rikka.shizuku.server.ShizukuService, moe.shizuku.starter.ServiceStarter, and moe.shizuku.manager.shell.Shell; these are invoked outside ordinary Android component lookup and must survive minification. manager/aapt2-resources.cfg marks selected Material color resources as #no_obfuscate for the custom collapseReleaseResourceNames task in manager/build.gradle, which runs after release resource optimization.

Coupling

Risks

  • manager/…/BootCompleteReceiver.kt can only auto-start adb mode on Android 13+ with WRITE_SECURE_SETTINGS; otherwise it logs “No support start on boot.” The manifest requests a protected permission but normal installs will not receive it, so changes that present adb boot startup as generally available will silently fail on most devices. History shows this path has been patched before (58e8bfd Fix start on boot for root is broken) and recently expanded (a9ee6ce Add WRITE_SECURE_SETTINGS permission).
  • manager/…/AdbPairDialogFragment.kt launches pairing with GlobalScope and stops only the mdns listener in ViewModel.onCleared(). If the dialog/activity is destroyed while AdbPairingClient.start() is running, callbacks can still post into stale LiveData, so lifecycle-sensitive edits to pairing should avoid adding UI/context work inside that coroutine.
  • manager/…/IntegerSimpleMenuPreference.java assumes the bound preference row contains android.R.id.empty and throws if it does not. Any preference item layout/theme change under manager/…/settings.xml or the Rikka preference styles must preserve that anchor or opening the night-mode menu will crash.
  • manager/proguard-rules.pro keeps external entry-point main() methods for the server, starter, and shell. Removing or renaming those keep rules can produce a release APK that builds but cannot start Shizuku through root/adb because those entry points are invoked from native/shell commands rather than normal Android component references.