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

Analysis Tools

Advanced

---

Tech Stack

---

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

1. Fork and clone the repo
2. Run flutter pub get
3. Run flutter gen-l10n to generate localizations
4. Run dart run build_runner build to generate freezed/drift code
5. 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.

应用内更新 / 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