XClean

utopiafar

0.3.1 · GitHub

Download APK

File management Android 8.0+ 2 weeks ago Proprietary

130 ShizuStore

370 GitHub

5 Stars

61 MB Size

More about this app

Rule-based cleaner with Normal, Shizuku and Root engines for clearing app junk.

XClean

A lightweight, powerful, and privacy-focused file cleaner for Android.
No ads. No tracking. Open source.

🇨🇳 中文 README

Why XClean?

Most "cleaner" apps on the Play Store are bloated with ads, aggressive upselling, and excessive permissions. XClean takes a different approach:

Rule-based cleaning – Define exactly what gets cleaned and when.
Preview before delete – See every file before it's removed. Never accidentally delete something important.
No ads, no tracking – Your data stays on your device.
Open source – Fully transparent. Audit the code, fork it, contribute.
Lightweight – Minimal resource usage, no background bloat.

Features

Core Cleaning

Feature	Description
🔍 One-Key Scan	Scan with all enabled rules and preview results before cleaning
📋 Rule System	Flexible rules with scope, conditions (filename, extension, size, modified time, subfile count), and actions
🗑️ Preview & Select	Grid preview with thumbnails for images and videos; bulk select/deselect
📁 Preset Rules	Thumbnail cache, empty folders, download temp files, log files, app residual, APK installers
✏️ Custom Rules	Create your own rules with custom paths, conditions, and engines
🕒 Auto Clean Tasks	Schedule periodic cleaning with customizable conditions

Analysis Tools

Feature	Description
📊 Storage Overview	Visual ring chart showing used/available space
🐘 Large File Analysis	Find files by size threshold (default 500MB, adjustable 100MB–5GB)
📝 Cleanup History	Detailed logs with deleted file names, freed space, and execution time
🔧 Rule Management	Enable/disable rules, edit priorities, switch engines (Normal/Shizuku/Root)

Advanced

Feature	Description
🎬 Video Thumbnails	Native Android MediaMetadataRetriever for MP4/MKV/AVI/MOV preview
🛡️ Safety Policy	Minimum match count, excluded paths, require-preview-on-first-run
🔌 Multi-Engine	Normal (standard FS), Shizuku (ADB-level), Root (superuser)
🌍 Bilingual	English & 简体中文 (via ARB + flutter_localizations)

Tech Stack

Layer	Technology
Framework	Flutter 3.41+ / Dart 3.11+
State Management	flutter_riverpod
Database	Drift (SQLite) + drift_flutter
Routing	go_router
Serialization	freezed + json_serializable
Permissions	permission_handler (MANAGE_EXTERNAL_STORAGE)
Background Tasks	WorkManager (Android)
Notifications	flutter_local_notifications
Native Bridge	MethodChannel + EventChannel (Kotlin)

Installation

Requirements

Android 8.0+ (API 26+)
MANAGE_EXTERNAL_STORAGE permission (for full SD card access)

Build from Source

# Clone
git clone https://github.com/utopiafar/XClean.git
cd XClean

# Install dependencies
flutter pub get

# Generate code (freezed, drift, json_serializable, l10n)
flutter gen-l10n
dart run build_runner build --delete-conflicting-outputs

# Build debug APK
flutter build apk --debug

# Build release APK
flutter build apk --release

Pre-built APK

Download the latest release from GitHub Releases.

Architecture

lib/
├── core/           # Utilities (rule matcher, size formatter, localization)
├── data/
│   ├── local/      # Drift database (SQLite)
│   └── repositories/
├── domain/         # Entities (CleanRule, CleanLog, CleanResult)
├── platform/       # MethodChannels (File, Permission, Background)
├── presentation/
│   ├── providers/  # Riverpod providers
│   ├── screens/    # UI screens
│   └── widgets/    # Reusable widgets
└── routing/        # go_router configuration

Clean Flow

User taps "One-Key Scan"
    ↓
ScanNotifier.scanWithRules(enabledRules)
    ↓
For each rule → FileChannel.scanPath (Kotlin native scan)
    ↓
Dart rule matcher filters results
    ↓
PreviewScreen shows grid of matched files
    ↓
User selects files → taps "Clean"
    ↓
FileChannel.deleteFiles(paths) + log to database
    ↓
Show completion dialog + refresh dashboard

Testing

# Run all tests
flutter test

# Run specific test suites
flutter test test/core/utils/rule_matcher_test.dart
flutter test test/presentation/screens/

Current test coverage:

✅ Rule matcher (30+ conditions)
✅ Video/image file type detection
✅ Large file filtering logic
✅ Log detail parsing
✅ Widget tests for Rule List, Preview, Large File screens

Contributing

Contributions are welcome! Please read our Contributing Guide (coming soon) and submit PRs.

Development Setup

Fork and clone the repo
Run flutter pub get
Run flutter gen-l10n to generate localizations
Run dart run build_runner build to generate freezed/drift code
Open Android emulator or connect a device with MANAGE_EXTERNAL_STORAGE granted

Code Style

Follow existing Flutter/Dart conventions
Run flutter analyze before committing
Add tests for new features

Acknowledgements

Inspired by the best of the cleaner app ecosystem:

SD Maid – For the deep-cleaning philosophy and rule-based approach
Files by Google – For the clean, no-nonsense UI design
CCleaner – For the comprehensive system monitoring concept

License

MIT License © UtopiaFar

Built with ❤️ using Flutter

File-level storage changes

Save a metadata baseline, test an app, and scan again to compare added, disappeared and changed files. Includes coverage-aware snapshots, growth ranking, redacted summaries and disabled candidate rules that require review. See Storage changes for the first-release scope and limitations.

See in-app updates for GitHub Release checking, background APK downloads and installation.

How Shizuku is used

Can scan restricted folders, delete junk files and measure folder sizes via shell commands through Shizuku.

This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.

How this app uses Shizuku

Shizuku lets the cleaner reach restricted storage to find and clear app junk.

Scan restricted folders: files matching a cleaning rule are listed with size and date using the find and stat shell commands through Shizuku.
Delete junk files: selected files are removed using the rm shell command through Shizuku, with size checked and removal verified.
Measure folder sizes: folder size is calculated using the du shell command through Shizuku so reclaimable space can be shown.

Android APIs or commands used

find
stat
du -sb
rm -rf
test -e

Notable details

If Shizuku is not available, the same scan, delete and size requests run with standard storage access, which may not reach restricted folders.

Changelog

What's new for version 0.3.1

应用内更新 / In-app updates

设置中新增「检查更新」，查询官方 GitHub 最新稳定版并显示更新内容。
后台下载 APK，显示进度、支持取消，重新打开应用后恢复下载状态。
引导开启安装权限，由用户确认启动 Android 安装器。
安装前校验包名、版本、签名，以及 GitHub 提供的 SHA-256；阻止降级安装。
设置页版本号改为读取实际安装版本，支持中英文及明暗主题。

首次请手动安装本版本，此后可使用「设置 → 检查更新」获取新版本。仅在用户点击时检查、下载和安装，不会静默更新。

Verification

99 Flutter unit/widget tests passed.
2 Android 15 integration tests passed, including downloading the official Release APK, validating its checksum and rejecting a downgrade.
New update code static analysis passed.
Release APK signature verified; installation and update-page layout checked on emulator.
Package com.utopiafar.xclean, version 0.3.1+11.

Retains the repository's existing debug signing configuration.

SHA-256: b89d65fcfad2691411f745ac2327970d9c96cad013d2a3b81f7d8d471b8632de