Skip to content

About

Root-free MIUI-style sidebar for HyperOS - apps open in real freeform windows via Shizuku

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Sidebar for HyperOS / MIUI

A third-party, root-free side panel for Xiaomi tablets running HyperOS / MIUI — inspired by MIUI's native sidebar, but with one addition: apps open in a real freeform (floating window) via Shizuku.

中文说明请见 README.zh-CN.md

demo


Features

  • Edge handle pinned to the right edge: swipe left or tap to open
  • Drag-follow gesture — the panel tracks your finger and springs back if you release too early
  • App picker — choose exactly which apps appear; the panel is a narrow icon-only strip (MIUI-native look)
  • Freeform launch via Shizuku — apps open in a floating window; if Shizuku is unavailable it falls back to a normal full-screen launch automatically
  • Foreground service + auto-start on boot (needs the MIUI/HyperOS Autostart permission)
  • Quick Settings tile — start/stop the sidebar without opening the app
  • Self-healing recovery — opening the app re-starts the service automatically
  • No notification clutter — the mandatory foreground-service notification is posted on a hidden channel; no entry in Recents
  • Liquid-glass panel drawn entirely in code (chamfered/lensed edges, specular highlight — no system blur), plus an Arknights-inspired settings UI

Requirements

OS Android 13+ — developed and verified on Xiaomi Pad 8, HyperOS 3.0 / Android 16
Permission SYSTEM_ALERT_WINDOW (overlay)
Freeform Shizuku (optional — without it apps launch fullscreen)
Root Not required

Install & setup

  1. Build the APK (see Build) or grab one from Releases
  2. adb install app-debug.apk, or copy it to the device and tap it
  3. Open the app and, in order:
    • Grant overlay permission
    • Start the service
    • (optional) Install + activate Shizuku, then tap Authorize Shizuku in the app
    • (MIUI/HyperOS) Settings → Apps → Sidebar → Autostart → on Without this, the system silently drops BOOT_COMPLETED and auto-start will not work.
  4. Swipe left from the right edge, or tap the handle

Activating Shizuku without a PC

Shizuku → Start via wireless debugging → follow the on-device wizard. Shizuku (and therefore freeform launch) must be re-activated after every reboot — this is inherent to the no-root approach. The sidebar itself keeps working; only the freeform launch falls back to fullscreen until you re-activate.

How freeform launch works

The central question of this project was: can a normal third-party app launch another app into a freeform window without root?

Measured on HyperOS 3.0 / Android 16 (Xiaomi Pad 8):

Approach Result
FEATURE_FREEFORM_WINDOW_MANAGEMENT ✅ present (the device supports freeform)
ActivityOptions.setLaunchBounds() (public API) ❌ sets bounds only — cannot select windowing mode
ActivityOptions.setLaunchWindowingMode() ❌ hidden API, blocked for third-party apps
HyperOS's own "mini window" entry point ❌ not reachable by third-party apps
am start --windowingMode 5 executed as shell ✅ works — task reports mode=freeform
Specifying bounds ❌ neither am nor cmd accepts bounds on this build; the window uses HyperOS's default size/position

Conclusion: a normal app cannot do it; the shell identity provided by Shizuku can. So the app binds a Shizuku UserService (running as shell) and executes:

am start --windowingMode 5 -n <package>/<activity>

If anything fails (Shizuku not installed/inactive/not authorized, binder lost), the app re-binds and falls back to a normal launch — so the sidebar is never useless.

Known limitations

  • MIUI's "Clear all" (一键清理 / OneKeyClean) force-stops the app, and the sidebar disappears with it. A force-stop is the OS's highest-privilege termination: it kills every process, cancels alarms and marks the package as stopped, so an app cannot block it or restart itself. Recovery paths built into this app:
    • Open the app — it re-starts the service by itself
    • Quick Settings tile — pull down the shade and tap 侧边栏 (add the tile once via the tile editor; MIUI ignores programmatic tile registration)
    • If you'd rather be protected from the cleaner, re-enable one of the two things this app hides by design: keep the foreground-service notification, or keep the app in Recents so you can lock its task (MIUI does not kill locked tasks). Both are deliberate trade-offs — the default build stays quiet instead.
  • System gesture area: the rightmost ~20 dp of the screen belongs to HyperOS's back-gesture region, which sits above overlay windows. A swipe that starts at the very edge may be consumed by the system while an app is in the foreground. Start slightly inside the handle. (On the launcher there is no such conflict.)
  • Shizuku re-activation after each reboot (see above).
  • The system posts its own "displaying over other apps" notification for any app holding the overlay permission. It is posted by the system process and can only be disabled in the system notification settings.
  • Freeform window bounds are not controllable on this build (see table above).
  • Auto-start additionally needs the MIUI/HyperOS Autostart permission; a reboot is required to verify.

Build

Requirements: JDK 17, Android SDK with platforms;android-35 and build-tools;35.0.0.

./gradlew assembleDebug
# output: app/build/outputs/apk/debug/app-debug.apk

⚠️ The AIDL step breaks if the project path contains non-ASCII characters (e.g. a Chinese folder name) — the AIDL compiler fails with MalformedInputException. Clone into an ASCII-only path, or create a junction/symlink and build through it:

mklink /J C:\dev\SidebarApp "D:\some\中文\path\SidebarApp"
C:\dev\SidebarApp\gradlew.bat assembleDebug --project-dir C:\dev\SidebarApp

A GitHub Actions workflow (.github/workflows/build.yml) builds a debug APK on every push and uploads it as an artifact.

Engineering notes (HyperOS gotchas)

Findings that cost real debugging time — documented in case someone builds something similar:

  1. The "collapse flash" is a window-destruction artifact. Removing an overlay window makes SurfaceFlinger replay it for 1–2 frames at its untransformed position (full-open state). Frame-by-frame brightness analysis of screen recordings showed a constant +11/255 spike exactly at removal. Fix: never destroy the panel window — park it instead (same size/position, FLAG_NOT_TOUCHABLE).
  2. FLAG_BLUR_BEHIND on an overlay window can freeze the whole device on HyperOS. Real background blur is not viable here; the glass look is drawn with gradients instead.
  3. FLAG_DIM_BEHIND produces an over-bright frame when the dim layer is removed — another single-frame flash source.
  4. HyperOS reserves the right screen edge (GestureStubRight, ~54 px wide, above overlays) for the back gesture.
  5. NOT_TOUCHABLE overlay windows can swallow touches on MIUI/HyperOS: a parked (invisible) panel window may prevent a lower overlay window from receiving input. Keep the parked window out of the touch area, and remove FLAG_WATCH_OUTSIDE_TOUCH while parked.
  6. Overlay windows are clamped on-screen — negative x with Gravity.END and off-screen positions with Gravity.START are both clamped back into the display, so a window cannot be parked off-screen.
  7. Hidden API: don't reach for setLaunchWindowingMode reflection — shell + am start is the supported-enough path.
  8. Android 11+ package visibility: without a <queries> element for MAIN/LAUNCHER, queryIntentActivities returns only a handful of system apps.
  9. Shizuku UserServiceArgs requires processNameSuffix() (a missing suffix throws NullPointerException: process name suffix must not be null). Also: if you never unbind the user service, one :shell process (≈100 MB RSS) leaks per service lifecycle — unbind it in onDestroy. Note that a force-stop skips onDestroy entirely (MIUI's Clear-all does exactly that), so give the user service an idle self-exit watchdog as well.
  10. Boot auto-start needs RECEIVE_BOOT_COMPLETED and the MIUI "Autostart" permission; MiUI also delays the broadcast by ~10–20 s.

License

Apache-2.0

The UI style is inspired by the design language of Arknights; no game assets are included, and this project is not affiliated with or endorsed by HyperOS/MIUI, Xiaomi, or Hypergryph.

About

Root-free MIUI-style sidebar for HyperOS - apps open in real freeform windows via Shizuku

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages