An AI-powered Android file organization app — scan your storage, chat with Gemini AI, queue smart commands, preview every operation before it runs, and undo anything.
| Category | What it does |
|---|---|
| 🧠 AI Chat | Full multi-turn Gemini chat — ask in English or Swahili, get smart answers, code snippets, and queued command suggestions |
| 🗂️ 40+ Commands | Organize by type/date, move media by source, delete duplicates, clean APKs, caches, WhatsApp junk, dev build outputs, and more |
| 👁️ Preview (Dry Run) | Every command builds an ActionPlan first — see exactly which files will move or be deleted, uncheck anything you want to skip |
| ↩️ Undo | A persistent UndoLedger records every operation — tap Undo to reverse moves and restores from the in-app trash |
| 🗑️ Soft Delete | Nothing is hard-deleted immediately — files go to Organized/.trash/ and are auto-purged after 30 days via WorkManager |
| 🌙 Dark Mode | Full dark/light theme — all colors are semantic tokens in ThemeManager, zero hardcoded hex values in layout code |
| 🛒 Action Cart | Quick-action chips, AI suggestions, and the command browser all add to the same queue — one unified "Confirm" flow |
| 📊 Storage Stats | Live usage bar with used/free/total labels; color shifts orange → red as storage fills |
| 💀 Skeleton Loading | Shimmer placeholder cards replace the old "scanning…" text while indexing runs in the background |
(Coming soon — build and run on a physical device or emulator to see the UI)
| Home / Dashboard | AI Chat | Command Browser |
|---|---|---|
| Storage stats + Quick actions | Multi-turn Gemini chat | Searchable 40+ commands |
| Preview | Execution | Results + Undo |
|---|---|---|
| Per-file checkbox review | Live progress per command | Freed/moved summary + ↩ Undo |
app/src/main/java/com/willykez/fileorganizer/
│
├── AppState.java → State machine: EMPTY · SCANNING · IDLE · STAGING · EXECUTING · RESULTS
├── ThemeManager.java → Dark/light semantic color tokens + typography scale
├── UIFactory.java → Unified component factory (3 button styles, chips, cards, skeleton shimmer)
│
├── FileModel.java → File metadata + category classification (merged FileMetadata + FileCategoryDetector)
├── StorageManager.java → Recursive scan, delta load, device StorageStats (merged StorageScanner + MetadataManager)
│
├── ActionPlan.java → Dry-run model: list of PlannedOp (MOVE / SOFT_DELETE) with per-item toggle
├── CommandEngine.java → Parse commands (offline regex + Gemini AI), buildPlan(), executePlan(), multi-turn chat
├── CommandType.java → Enum of 40+ commands with emoji, description, category, cost, requiresRoot flag
│
├── FileSystemRouter.java → Safety layer: move(), trash() → .trash/, restore(), purgeExpiredTrash()
├── UndoLedger.java → Persistent undo stack (SharedPreferences JSON), push/pop snapshots
│
├── AppUtil.java → IO helpers, SHA-256 hashing, formatSize, permissions (merged FileUtil + SketchwareUtil + PermissionsHelper)
├── FileOrganizerApp.java → Application class, shared Gson instance
│
└── MainActivity.java → State-driven UI: empty state · skeleton · dashboard · 5 bottom sheets
User Input (Quick Action / AI Chat / Command Browser)
↓
addToCart(CommandType) ← Action Cart (unified queue)
↓
commandEngine.buildPlan() ← Dry-run on background thread
↓
Preview Sheet (user reviews) ← Per-op checkboxes
↓
commandEngine.executePlan() ← FileSystemRouter (soft-delete safe)
↓
undoLedger.push(reverseOps) ← Persistent undo
↓
Results Sheet + Snackbar
The ✨ AI FAB opens a full-screen Gemini-powered chat:
- Multi-turn context — full conversation history sent with every request
[SUGGEST:COMMAND_NAME]protocol — AI embeds a tag; app strips it from display and renders a tappable "AI Suggests → Queue" chip- "list all commands" — answered locally (instant, no API call) with categorized command list
- Code artifacts — triple-backtick blocks render with dark background, language label, monospace font, and a 📋 Copy button
- Inline markdown —
**bold**,*italic*,- bulletrendered as styled Views - Typing indicator — three animated bouncing dots while AI responds
- Offline graceful fallback — replies helpfully without crashing when disconnected
- Clear chat — wipes history with a confirmation dialog
- Swahili support — offline keyword matcher handles Swahili commands natively
| Category | Commands (sample) |
|---|---|
| 📂 Organize | By Type, By Date, Media by Source, Screen Recordings, Downloads by Date |
| 📦 Move | Screenshots, WhatsApp Images/Videos, Telegram, Audio, Videos, Documents, Large Files (>50 MB), Old Files (>180 days) |
| 🧹 Cleanup | Delete Duplicates (SHA-256), Empty Folders, Cache, APKs, Thumbnails, Temp Files, Crash Logs |
| 💬 Social | Clean WhatsApp Sent, TikTok Cache, Instagram Cache |
| 💻 Developer | Clean Gradle Cache, Remove node_modules, Clean Build Outputs |
| 📊 Analysis | Find Largest Files (Top 25), Find Unused Files (1+ yr), Analyze Storage Breakdown |
| 🤖 Automation | Auto Organize Daily, Nightly Cleanup |
- Android Studio Hedgehog or newer
- JDK 8+
- Android device / emulator (API 21+)
- Gemini API key (included in source for demo — replace in production)
git clone https://github.com/Willykez/FileOrganizerAI.git
cd FileOrganizerAI
# Open in Android Studio and sync Gradleimplementation 'androidx.appcompat:appcompat:1.7.1'
implementation 'com.google.android.material:material:1.12.0'
implementation 'com.google.code.gson:gson:2.10.1'<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" /> <!-- Android 11+ -->
<uses-permission android:name="android.permission.INTERNET" />The Gemini API key is embedded for demo purposes. For production:
- Get a key at aistudio.google.com
- Move it to
local.properties:GEMINI_API_KEY=your_key_here - Reference it via
BuildConfig.GEMINI_API_KEYinCommandEngine.java
- MediaStore API scanning — query OS-indexed media instead of full directory crawl (10x faster)
- FileObserver delta updates — listen for changes and update cache incrementally
- Perceptual hashing (pHash) — detect near-duplicate images (burst shots, lightly edited)
- WorkManager trash purge — auto-purge
.trash/older than 30 days without blocking launch - SAF / StorageAdapter — full SD card support via Android's Document File API
- Room database — replace Gson JSON persistence for better query performance
- Batch AI renaming — send 50 files per Gemini request for smart rename suggestions
- Root commands — isolated
RootShellContextfor Dalvik cache wipe, etc. - Widget — home-screen storage usage widget
MIT License — Copyright (c) 2025 Willykez
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software to use, copy, modify, merge, publish, distribute, and/or
sell copies of the Software, subject to the standard MIT terms.
Built with ❤️ for East African Android users · Swahili-first design