FreeformShell 🚀

FreeformShell is an experimental system-level window manager overlay and helper utility operating directly on native Android windowing components. Leveraging system-level APIs via Shizuku, direct Binder reflection, and fallback ADB shell utilities, FreeformShell adds custom window controls, display scaling configurations, and helper overlays for Android devices running Android 11 (API 30) up to Android 15+ (API 35+).

🎯 Target Audience: Who is FreeformShell for?

FreeformShell is a specialized power-user tool developed with a specific target audience and socio-economic purpose in mind. It is not designed for every Android user.

🚫 Who does NOT need this?

• Samsung & Flagship OEM Users: If you are using a premium Samsung flagship with Samsung DeX, or a device from an OEM that already bundles a robust, feature-rich desktop mode (with built-in window title bars, drag handles, and desktop panels), you do not need this utility.

🎯 Who is this built for?

• OEM Feature Compensation (e.g. Sony, Motorola, etc.): Many OEMs (such as Sony) allow you to launch applications in Android's native freeform mode, but strip out window title bars, borders, and multi-window resizing controls—often limiting you to just a single floating app at a time. FreeformShell injects those missing title bar frames, drag-to-resize borders, side-snapping guidelines, and minimized floating bubbles back into the OS to restore fully functional multitasking.
• The "Phone-First" Workstation (Bridging the PC Cost Gap): For many people worldwide, their smartphone is their primary or only computing device. With hardware inflation, supply shortages, and high costs making desktop PCs unaffordable, FreeformShell empowers users to bridge the gap—transforming a powerful smartphone they already own into a fully functional desktop station.
• Power Users with Scrcpy & ADB: Ideal for users who have a high-spec or second-hand phone supporting Type-C video output (DisplayPort Alt Mode), but only have access to an older or low-power PC. By leveraging scrcpy and ADB wireless, power users can cast a beautiful, window-managed Android desktop workspace directly to their large monitors.
• Restricted Tablet Users: Large-screen and Android tablet users who want a rich, desktop-like multitasking environment, but whose device manufacturer did not bundle any desktop interface in their software.

⚠️ Important Pre-requisites: Third-Party Launchers

📖 Quick Start & User Guide

Follow this step-by-step guide to get FreeformShell configured on your device:

1️⃣ Step 1: Install the APK

1. Navigate to GitHub Releases.
2. Download the latest compiled asset:
   • FreeformShell-debug.apk (Recommended for developers/testers).
   • Freeform-Beta-[Version]-debug.apk (Standard beta branch build).
3. Install the APK on your Android device (ensure "Allow Installation from Unknown Sources" is enabled in settings).

2️⃣ Step 2: Establish the Binder Connection

FreeformShell uses system Binder connections to manage overlays safely.

• Option A: Using Shizuku (Recommended — On-Device):
  1. Install Shizuku from Google Play.
  2. Open Shizuku and follow the on-screen instructions to start it via Wireless Debugging (no computer required!).
  3. Open Freeform Beta, click on Shizuku Permission under the status dashboard, and grant permission in the popup.
• Option B: Using ADB Shell (Computer Fallback): If Shizuku is not running, connect your phone to a computer with USB Debugging enabled, and start Shizuku's binder service manually:

  adb shell sh /sdcard/Android/data/moe.shizuku.privileged.api/start.sh
  

3️⃣ Step 3: Enable the Accessibility Service

To display desktop window frames and drag handles on top of normal Android apps:

1. Open the Freeform Beta App.
2. Click the Accessibility Service chip under status dashboard.
3. System settings will open. Locate Freeform Beta / FreeformShell, toggle On, and accept overlay warnings.

4️⃣ Step 4: Master the Window Controls & Gestures

Once set up, launching apps via your companion launcher (e.g. Taskbar) or FreeformShell widgets will trigger the overlay frames:

• Drag & Move: Hold the colored title bar at the top of a floating app to move it anywhere.
• Resize: Grab the corners or bottom/side borders of a window to resize it.
• Minimize Bubble: Click the _ icon on the window frame. The window shrinks into a floating bubble on the screen edge. Tap the bubble to expand it back instantly!
• Maximize: Click the [] icon to expand the window to fullscreen.
• Split-Snapping: Drag a window toward the left or right edge of the display. A visual snapping guideline appears—release to snap the app to exactly half-screen, creating a split productivity workspace.
• Close: Tap the X button on the title frame to close the task.

✨ Core Features Tour

Explore the main configuration screens of FreeformShell designed to help you customize your window overlay experience:

📊 1. Dashboard & Diagnostics

• Status Telemetry: Monitor status checks of the Shizuku Binder Service, active binder permissions, and Accessibility Service.
• Display Enumerator: Displays names, IDs, hardware resolutions, and default densities of all active displays (built-in phone screen + connected external monitors).
• System Diagnostics: Provides a real-time console log of underlying shell activity, command execution diagnostics, and ADB connection status.

🎨 2. Window Customization & Style

• Visual Adjustments: Tune transparent window overlays, borders, and dimming backdrops to match your styling preference.
• Interactive Corner Sliders: Adjust window corner roundness (0dp sharp up to 32dp rounded) and border thickness in real-time.
• Title Bar & Stroke Opacities: Customize handle transparency to make overlays bleed seamlessly into the background.
• HSL Accent Color Picker: Integrates an HSL-based color selector to style overlay title frames, snap indicators, and minimized bubbles. Includes a real-time Interactive Window Preview within the app so you see styles apply instantly.

📐 3. Display Safe Area Offsetter

• Notch & Camera Offset: Compensate for rounded corners, camera notches, or punch-hole cameras by defining safe-area insets.
• Multi-Monitor Customization: Configure top, bottom, left, and right safe boundaries independently for each connected display panel.

⚙️ 4. Display Density (DPI) Scaling & Presets

• Scaling Down Focus: Pack more information on screen! Presets focus on scaling down, including 120 DPI (Ultra Compact), 160 DPI (Desktop mdpi), 240, 320, 360, Physical Default, and 480 DPI.
• Allow Unsafe Extreme DPI: Technical users can toggle an override option to unlock extreme custom values down to 100 DPI.
• Windows-Style Reversion Shield: To prevent touch soft-locks, applying density changes triggers a 15-second overlay countdown timer with a 50% backdrop dimming effect. If unconfirmed, it automatically rolls back safely to your previous DPI.
• Unrestricted Secondary Displays: Custom scale external desktop screens (e.g. mock monitors, USB-C docks, virtual displays) instantly without safe boundary limits or warning interruptions.

🚫 5. Application Blacklist Manager

• Compatibility Safety Valve: Select specific applications (like mobile-only banking apps, camera software, or heavy fullscreen games) to blacklists. Blacklisted applications will launch in standard native fullscreen rather than freeform mode.

🧩 6. Interactive Home Screen Widgets

• One-Click Launches: Pin specialized widgets to your Android launcher to launch pre-selected workspaces or specific apps directly into a floating freeform window.

🛠️ Developer & Contributor Guide

Welcome to the development center! Below are instructions on how the codebase is structured, compiled, and maintained using automated pipelines and AI-guided boundaries.

📂 Project Structure

├── .agents/                 # Developer Guidelines & AI Agent instructions
│   └── rules/
│       ├── compatibility.md  # Key Android 11-15+ compatibility boundaries
│       └── graphify.md       # Knowledge Graph navigation rules
├── .github/
│   └── workflows/
│       └── release.yml      # CI/CD Automated Gradle builder & Release drafter
├── app/                     # Main Android Application module
│   ├── src/main/java        # Source files (MainActivity, Services, Core managers)
│   └── build.gradle.kts     # Build definitions & Shizuku dependencies
├── docs/                    # Architectural plans & mermaid diagram snapshots
├── LICENSE                  # Apache 2.0 Open-Source License
└── NOTICE                   # Primary human-AI co-development attribution shield

🧩 Tech Stack & Architecture

• Language: Modern Kotlin
• UI Framework: Jetpack Compose (Material 3) with customized harmonized HSL-based styling
• System Core:
  • Shizuku / Rikka API — For ultra-low latency direct Binder connection.
  • LSPosed HiddenApiBypass — Safely bypass reflection limits on Android 14+.
  • Defensive Fallbacks — Seamless transition between Binder commands and ADB shell commands.

🤖 AI-Human Co-Development & "Vibe-Coding"

This project is built using a modern AI-Human Co-Development paradigm. We check in the .agents/ folder and graphify-out/ into the Git repository to enable seamless agentic collaboration:

• .agents/rules/: Any future developer's AI agent (like Cursor, Claude, Antigravity) will instantly read compatibility.md on startup, preventing them from introducing breaking changes or breaking API backwards compatibility.
• graphify-out/: Houses the codebase's semantic relation graph, helping AI tools navigate and map class dependencies with zero latency.

For more information on contributing, see our CONTRIBUTING.md guide.

🚀 Building & Running Locally

Ensure you have Android Studio installed and a device/emulator connected with ADB enabled.

1. Compile the App

Compile the project directly via Gradle in your terminal:

./gradlew compileDebugKotlin

2. Install to Connected Device

Install the debug APK on your device:

./gradlew installDebug

📦 Automated Release Pipeline (CI/CD)

FreeformShell includes a fully automated build pipeline. Simply push a version tag to GitHub to trigger the release workflow:

git tag v1.4.0
git push origin v1.4.0

GitHub Actions will automatically spin up, build the Debug and Unsigned Release APKs, compile changelogs from your commit history, and draft a release containing the downloadable files!

💬 Join the Community

Connect with other power users, share your custom configurations, and get real-time assistance:

Why join our Discord? 🚀 Get Instant Help: Troubleshoot your Shizuku or ADB setup with other community members. 📐 Share Presets: Post your custom DPI layouts, safe area offsets, and display configurations. 💡 Suggest Features: Directly pitch system overlay improvements or launcher integrations. 🔄 Beta Updates: Get notified immediately when a new pre-release APK is compiled!

🛡️ License & Attributions

This project is open-sourced under the Apache License 2.0.

Under Section 4d of the Apache 2.0 license, any downstream forks or commercial adaptations must preserve and distribute the original NOTICE file unmodified. This legal shield guarantees that you, your AI tool creators, and future contributors receive lasting attribution:

See NOTICE for details.

🚀 Release v1.4 - Aluminum OS Top Panel, Task Manager, Quick Settings & Guides

Welcome to Version 1.4 of FreeformShell! This major update introduces a sleek Aluminum OS-inspired top bar, integrated Notification & Quick Settings sub-panels, an advanced Task Manager inspired by Windows 11, and interactive setup guides.

🌟 Major Features & Deep-Dive Insights

💎 1. Top Panel Inspired by Aluminum OS

• Aluminum OS inspired Status Bar: Translucent desktop header bar running across the display with live digital time/date, battery telemetry, and quick launcher triggers.
• Integrated Notification Center: Dedicated notification drawer with expandable notification cards, inline reply actions, clear-all triggers, and custom toast overlays.
• Quick Settings Flyout & Sub-Panels: Compact tile grid featuring one-tap system toggles (Wi-Fi, Bluetooth, Dark Mode, Flashlight, Hotspot, Rotation), dual interactive sliders for display brightness and media volume (with mute toggling), a dedicated media player card, and an active running apps inspector.
• Fluid Spring Morphing: Employs Compose spring physics (Spring.StiffnessLow) to smoothly interpolate container height transitions when switching between the main Quick Settings grid and detailed sub-panels.

📊 2. Task Manager Inspired by Windows 11

• Adaptive Desktop & Compact Layouts: Built on BoxWithConstraints layout logic. On desktop/tablet displays, it presents a permanent vertical navigation sidebar; on mobile screens, it transforms into an ergonomic bottom horizontal "Metric Strip" for easy thumb reachability.
• High-Density Telemetry Graphs: Multi-threaded real-time graphing for CPU core utilization, RAM memory pressure, GPU performance, Storage disk I/O, Network Wi-Fi throughput, and Battery discharge rates.
• High-Precision Unit Conversion Engine: Unified unit conversion math (8x bit-to-byte conversion) synchronizing axis labels, legend overlays, and tooltips across Mbps, MB/s, and B/s.
• Live Process Inspector: Integrated process view allowing users to inspect active background processes, analyze per-app RAM consumption, and manage running tasks.

📚 3. New Interactive Setup Guides & Quick Start

• Shizuku Pairing & Authorization Guide: Step-by-step visual tutorial demonstrating wireless debugging pairing, port detection, and Shizuku permission authorization with embedded video/image previews.
• Taskbar & Launcher Setup Assistant: Detailed guide for configuring primary launcher settings, integrating third-party taskbars, and configuring window overlay permissions.
• Developer Options Helper: Guided walkthrough for unlocking Android developer settings, enabling Force activities to be resizable, Enable freeform windows, and Enable desktop mode.

📶 4. Wi-Fi & Bluetooth Control Refactoring

• Wi-Fi Sub-Panel: Dynamic height bounds (no container stretching), 1:1 skeleton shimmer loading cards, frequency/generation badges (5 GHz, Wi-Fi 6), inline accordion details, and pure Kotlin QR code sharing with full-screen preview.
• Bluetooth Engine: Reliable svc bluetooth toggling, 14-second auto-restart discovery scanning, cross-referenced active connection checks, and thread-safe device pairing.

⚠️ Important Testing Note & Feedback

🗺️ Future Roadmap & Upcoming Features

Here is what we are working on for upcoming releases:

• ⚡ Titlebar & Window Performance: Optimizing drag-resize and titlebar responsiveness on other Android OS versions and custom OEM ROMs (OneUI, MIUI, OxygenOS).
• 📦 APK Size Reduction: Cleaning up bundled media assets to significantly cut down on overall app installation size.
• 🔒 Desktop Mode Lock Screen: Adding a dedicated lock screen experience tailored for desktop windowing mode.
• 🎥 Desktop Screen Recording with Internal Audio: Expanding screen recording capabilities to capture system internal audio (currently video recording works, but audio is omitted).

📦 Download

Download Freeform-Beta-v1.4.apk from the Assets section below!