imole

# iMole — iPhone Storage Cleaner Skill Help users slim down their iPhone storage. Scan media, back up files to the computer, delete verified files from the device, and guide users through the steps only Apple allows on the phone itself. Use this skill whenever the user says: "my iPhone is full", "clean up my iPhone", "free up iPhone storage", "back up iPhone photos/videos", "iPhone space is running out", or asks to delete old videos from their phone. --- ## Platform Support | Feature | macOS | Linux | Windows | |---------|:-----:|:-----:|:-------:| | USB scan (auto) | ✅ ImageCaptureCore | ✅ gphoto2 | ➖ use `--source` | | Scan via `--source PATH` | ✅ | ✅ | ✅ | | Backup (copy files) | ✅ | ✅ | ✅ | | Delete from device (USB) | ✅ ImageCaptureCore | ❌ planned | ❌ not supported | | Delete via mounted path | ✅ | ✅ (ifuse) | ✅ (iTunes mount) | | Device detection (`doctor`) | ✅ | ✅ | ✅ | ### macOS prerequisites - iPhone connected via USB, screen unlocked, "Trust This Computer" accepted. - `swift` available: `xcode-select --install` - ImageCaptureCore used automatically — no extra install needed. ### Linux prerequisites ```bash # Device detection and trust pairing sudo apt install libimobiledevice-utils # Scan via USB (gphoto2 — auto-detected) sudo apt install gphoto2 # Mount DCIM as filesystem (required for backup + delete workflow) sudo apt install ifuse idevicepair pair # trust the device (one-time) mkdir -p ~/iphone ifuse ~/iphone # mount iPhone DCIM ``` ### Linux full cleanup workflow ```bash # 1. Mount ifuse ~/iphone # 2. Scan what's on the phone imole scan --source ~/iphone/DCIM # 3. Backup (verifies every file with SHA-256) imole backup --source ~/iphone/DCIM --to ~/backup/iphone --only videos --older-than 90d # 4. Review what will be deleted imole report --manifest ~/backup/iphone/manifest.json # 5. Delete verified files directly from the mount (space freed immediately, no Recently Deleted) imole clean --manifest ~/backup/iphone/manifest.json --source ~/iphone/DCIM # 6. Unmount fusermount -u ~/iphone ``` ### Windows prerequisites - Install **iTunes** (provides USB drivers and the Apple Mobile Device service). - Connect iPhone, unlock it, tap "Trust This Computer". - Open **Windows Explorer** → This PC → [Your iPhone] → Internal Storage → DCIM. - Note the path (e.g. `\\Apple\iPhone\Internal Storage\DCIM`) or copy it to a local folder. - Use `--source` with that path: ```powershell imole.exe scan --source "\\Apple\iPhone\Internal Storage\DCIM" imole.exe backup --source "\\Apple\iPhone\Internal Storage\DCIM" --to C:\backup imole.exe clean --manifest C:\backup\manifest.json --source "\\Apple\iPhone\Internal Storage\DCIM" ``` --- ## Installation ### Option A — npm (recommended — works on macOS, Linux, Windows) ```bash npm install -g @getimole/imole ``` Works on all platforms with Node.js installed. Downloads the pre-built binary automatically. Verify with: ```bash imole --version ``` ### Option B — Install script (macOS / Linux) ```bash curl -fsSL https://raw.githubusercontent.com/chenhg5/imole/main/install.sh | bash ``` Installs the pre-built binary to `/usr/local/bin/imole`. Verify with: ```bash imole --version ``` ### Option C — Build from source ```bash git clone https://github.com/chenhg5/imole.git cd imole go build -o imole ./cmd/imole sudo mv imole /usr/local/bin/ ``` --- ## Full Cleanup Workflow (end-to-end) Follow these steps in order. Never skip the backup-and-verify step before cleaning. ### Step 1 — Check device and environment ```bash imole doctor --json ``` Expected: `"device"` block with `"connected": true`. If the device is not connected, ask the user to plug in the iPhone, unlock it, and tap "Trust" on the device screen. Use device storage pressure to decide how aggressive the cleanup plan should be: | Free space | Pressure | Agent response | |---:|---|---| | `< 5%` | Critical | Target immediate reclaim. Prefer large videos and old videos first. | | `5-10%` | High | Recommend a concrete backup target large enough to reach at least 15% free. | | `10-20%` | Moderate | Offer a conservative plan: oldest/large videos first, then app cleanup guidance. | | `> 20%` | Low | Diagnose only; do not push deletion unless user asks. | Useful fields: ```bash imole doctor --json --fields device.name,device.product_type,device.storage.total_data_capacity,device.storage.amount_data_available,device.storage.free_percent ``` ### Step 2 — Scan to understand what's taking space ```bash imole scan --summary --json ``` Key fields in the response: | Field | Meaning | |---|---| | `device.storage.free_percent` | Remaining device storage percentage | | `media.total_size` | Total media size (photos + videos) | | `media.video_size` | Videos only — usually the biggest offender | | `apps.total_size` | App storage estimate from iOS installation_proxy | | `top_video.size` | Largest video candidate | To show only the most useful subset: ```bash imole scan --summary --json --fields device.storage.free_percent,media.total_size,media.video_size,apps.total_size,top_video ``` To focus on videos older than 90 days: ```bash imole scan --summary --only videos --older-than 90d --json ``` If you already ran a scan recently and don't want to wait ~15 s for USB enumeration: ```bash imole scan --cache --summary --json ``` ### Step 3 — Inspect the biggest files ```bash imole scan --top 20 --only videos --json ``` Use this to show the user which specific videos are taking the most space. Let the user decide which age or size threshold to target. `scan`, `scan apps`, `doctor`, `report`, `history`, `schema`, and `guide` are read-only. Do not add `--dry-run` to them; `--dry-run` is only valid on `backup` and `clean`. ### Step 4 — Dry-run the backup (preview) Always dry-run before committing. This shows what would be backed up without touching anything. ```bash imole backup --to ~/imole-backup --only videos --older-than 90d --dry-run ``` Exit code `10` means dry-run passed — safe to proceed. Adjust `--only`, `--older-than`, and `--large-than` based on user preference. ### Step 5 — Run the backup ```bash imole backup --to ~/imole-backup --only videos --older-than 90d ``` This copies matching files from the iPhone to `~/imole-backup/`, verifies each file by size, and writes `~/imole-backup/manifest.json`. The manifest records every file's `source_rel` (path on device), `dest_rel` (local copy), `size`, and `verified` flag. **Only verified files are ever eligible for deletion.** ### Step 6 — Check the backup report ```bash imole report --manifest ~/imole-backup/manifest.json --json ``` Key fields: | Field | Meaning | |---|---| | `verified` | Number of files confirmed copied correctly | | `verified_size` | Total bytes confirmed | | `cleanable` | Files safe to delete from iPhone | | `cleanable_size` | Bytes that can be freed | Only proceed to clean if `verified == cleanable` (no failures). ### Step 7 — Dry-run the deletion (preview) ```bash imole clean --manifest ~/imole-backup/manifest.json --dry-run ``` Exit code `10` = safe to proceed. ### Step 8 — Delete verified files from iPhone ```bash imole clean --manifest ~/imole-backup/manifest.json --yes ``` - Only files with `verified: true` in the manifest are sent to the device for deletion. - Uses `ICCameraDevice.requestDeleteFiles` via a Swift helper (macOS ImageCaptureCore). - The iPhone **may show a confirmation prompt** on its screen — tell the user to accept it. ### Step 9 — Clear Recently Deleted (manual, on iPhone) Deleted files stay in "Recently Deleted" for 30 days and **still occupy space** until cleared. Tell the user: > On your iPhone: open **Photos** → **Albums** → scroll to **Utilities** → **Recently Deleted** → tap **Select** → **Delete All**. Space is freed only after this step. --- ## Command Reference ### `imole doctor` Check connectivity and dependencies. ```bash imole doctor --json imole doctor --json --fields device.name,device.connected ``` ### `imole scan` Unified scan command — summary, top N by size, or full result. ```bash # Compact stats (for a quick overview) imole scan --summary --json imole scan --summary --only videos --older-than 1y --json imole scan --summary --json --fields total_size_human,video_files,old_size_human # Top N largest files (replaces old `videos` command) imole scan --top 30 --only videos --json imole scan --top 10 --only photos --older-than 1y --json # Use cached scan to skip slow USB enumeration (< 1 h old) imole scan --cache --summary --json # Full scan report with next-step hints imole scan --json imole scan --only videos --older-than 90d --json imole scan --json --fields summary.total_files,summary.video_size # Limit result to first N items (largest first) after filtering imole scan --only videos --limit 20 --json # Metadata scan (GPS, taken date, dimensions) — first run ~30-60 s, cached 7 days imole scan --with-meta --summary --json # Filter by GPS country / region (auto-enables --with-meta) imole scan --country Japan --only photos --json imole scan --country CN --only videos --json # Filter by date range (YYYY-MM-DD) imole scan --taken-after 2024-01-01 --taken-before 2024-12-31 --only photos --json # Videos longer than N seconds imole scan --duration-gt 120 --only videos --json # Photos/videos with no GPS metadata imole scan --no-gps --only photos --json # Filter by file extension (no --with-meta needed) # On iPhone: .png ≈ screenshots, .heic = camera photos, .mov = videos imole scan --ext png --json # likely screenshots imole scan --ext heic --only photos --json # HEIC camera photos only # Filter by dimensions (requires --with-meta) # iPhone 15 Pro screenshot = 1179×2556; iPhone 14 = 1170×2532 imole scan --with-meta --ext png --min-width 1100 --min-height 2400 --json # precise screenshot detection imole scan --with-meta --min-width 4000 --only photos --json # high-res camera shots ``` ### `imole backup` Back up media to local disk with verification. ```bash imole backup --to /Volumes/External/iphone-backup --only videos --older-than 90d imole backup --to ~/backup --file DCIM/202507__/IMG_7523.MOV --dry-run imole backup --to ~/backup --only photos --older-than 1y --dry-run imole backup --to ~/backup --large-than 500MB --json # Back up at most N files (largest first) imole backup --to ~/backup --only videos --limit 10 --dry-run # Back up by GPS country (auto-enables --with-meta) imole backup --to ~/backup --country Japan --only photos imole backup --to ~/backup --country Australia --only videos --dry-run # Back up by date range imole backup --to ~/backup --taken-after 2024-01-01 --taken-before 2024-12-31 --only photos # Back up videos longer than 2 minutes imole backup --to ~/backup --duration-gt 120 --only videos # Back up items with no GPS (privacy-sensitive cleanup) imole backup --to ~/backup --no-gps --only photos # Back up screenshots (PNG files) imole backup --to ~/backup/screenshots --ext png --dry-run imole backup --to ~/backup/screenshots --ext png # Back up screenshots precisely: PNG + screen dimensions (auto-enables --with-meta) imole backup --to ~/backup/screenshots --ext png --min-width 1100 --min-height 2400 # iCloud placeholder handling: # Option A — skip thumbnails, only backup confirmed full-res files imole backup --to ~/backup --skip-placeholders --only photos # Option B — backup ONLY the placeholder files (to know what needs icloud download) imole scan --only-placeholders --json # Then fetch originals from iCloud: imole icloud --to ~/backup --username me@apple.com # Back up directly to cloud storage via rclone (rclone must be installed and configured) # Syntax: --to rclone:<remote_name>:<remote_path> imole backup --to rclone:gdrive:iPhone/backup --only videos imole backup --to rclone:s3:my-bucket/iphone --older-than 90d imole backup --to rclone:onedrive:iPhone --only photos --dry-run ``` **Incremental backup:** Re-running `backup` to the same `--to` directory is safe and efficient. Files already present in `manifest.json` with `verified: true` are skipped automatically — no re-download, no USB session overhead if everything is already backed up. **Cloud backup via rclone:** Use `--to rclone:<remote>:<path>` to sync to any rclone-supported cloud storage (Google Drive, S3, OneDrive, Dropbox, Backblaze B2, SFTP, and 70+ others). imole first copies files to a local staging area (`~/.imole/rclone-cache/`), then runs `rclone copy` to push them to the remote. Requires rclone to be installed and configured: ```bash rclone config # add a remote named e.g. "gdrive", "s3", "onedrive" ```