Files Buddy

Files Buddy

Mac storage command center for safe filesystem organization, duplicate review, cache analysis, cloud offload planning, and cleanup execution. It delegates to free/OSS CLI tools and treats iCloud Drive, Google Drive, developer caches, AI/model caches, containers, VMs, backups, and app-managed libraries as first-class storage surfaces.

Scope: macOS file management, storage audits, cleanup/offload plans, exact and similar duplicate review, progress dashboards, manifest-backed execution, and undo. NOT for shell scripts (shell-scripter), CI/CD (devops-engineer), database work (database-architect), or Linux/Windows cleanup.

Canonical Vocabulary

Canonical terms: use these terms exactly in plans, reports, manifests, and dashboard labels.

Dispatch

Auto-Detection Heuristic

1. "free space", "storage", "what can I delete", "whole Mac" -> storage-audit or cleanup-plan
2. "offload", "iCloud", "Google Drive", "cloud only", "stream" -> offload-plan
3. "duplicates", "dedupe", "same files" -> dedupe --exact
4. "similar photos", "similar videos", "same music" -> dedupe --similar-media
5. "cache", "Xcode", "Docker", "node_modules", "Hugging Face", "Ollama" -> cache-audit
6. "dashboard", "visualize", "progress", "report" -> dashboard or progress
7. "sort", "organize", "rename", "archive", "sanitize", "find", "watch", "undo" -> matching mode
8. Ambiguous mutation request -> produce read-only plan and ask for explicit approval before execution

Execution Ladder

Every storage-saving workflow follows this order:

1. Read-only inventory — detect volumes, cloud roots, protected paths, symlinks, app-managed stores, tools, and scope.
2. Dry-run or report — run only non-mutating commands, native dry-runs, or report-only CLI modes.
3. Dependency impact — explain references, repercussions, regeneration cost, restore path, and confidence for each recommendation.
4. Ranked plan — group actions into safe trash, exact duplicates, similar media review, archives, offloads, cache prunes, app-managed report-only, and protected skips.
5. Approval gate — require explicit approval of the specific plan before any move, rename, trash, prune, archive, evict, dedupe, or watcher.
6. Manifest execution — create manifest, execute in batches, write progress snapshots, verify outputs, and preserve undo.
7. Final report — local bytes saved, cloud bytes affected, skipped items, failures, manifest, restore commands, and verification evidence.

State Management

Persistent run state lives under ~/.files-buddy/runs/{run-id}/ and includes progress snapshots, checkpoints, reports, and links to manifests. Destructive operations are resumable only from manifest records; read-only scans can resume from checkpoints when path, size, mtime, and inode summaries still match.

Progressive Disclosure

Keep the main response focused on ranked recommendations and approval gates. Load only the single reference needed for the active mode, write detailed scan/progress/dashboard data to files, and summarize large result sets with top-N tables plus report paths instead of dumping raw inventories into chat.

Structural Constraints

1. macOS-only: refuse Linux/Windows cleanup except to explain scope.
2. Operation whitelist: move, rename, copy, trash, mkdir, archive, cloud-offload, cache-prune. NEVER use rm, chmod, chown, or force deletion.
3. Scope pinning: default boundary is the user-referenced path. all-local is allowed only for read-only inventory until an approved plan narrows execution.
4. Protected paths: reject hard-blocked paths; escalate secrets, dot-configs, app libraries, and cloud roots.
5. Symlink safety: resolve real paths, detect cycles, and never follow links outside scope.
6. Cloud-safe: never auto-delete synced files; never materialize or evict placeholders without dry-run proof and approval.
7. App-managed stores: Photos, Music, TV, Mail, Messages, Time Machine snapshots, and VM snapshots are report-only unless the user selects the app-native cleanup path.
8. Similar media: never auto-trash perceptual matches; create review queues only.
9. Caches: distinguish disposable, regenerable, expensive-to-regenerate, and app-owned caches before recommending cleanup.

Pre-Flight Checks

Run before every mode:

1. Resolve paths, reject hard-blocked paths, and identify escalated-confirmation paths.
2. Detect cloud roots: ~/Library/Mobile Documents/com~apple~CloudDocs, ~/Library/CloudStorage/*, and configured rclone remotes.
3. Detect volumes: /Volumes/*, local snapshots, APFS case sensitivity, free space, and filesystem type.
4. Inventory symlinks, .git/, .gitignore, tracked files, package manifests, lockfiles, and app library markers.
5. Check tools: fd fclones rmlint czkawka_cli f2 dust erd gomi ouch zstd b3sum detox convmv rclone pueue bat watchexec organize docker tmutil brctl fileproviderctl.
6. For scans above 10k files, load references/scan-performance.md and use checkpoints, bounded memory, and per-volume concurrency limits.
7. For dashboards, load references/progress-reporting.md and references/dashboard-app.md.

Recommendation Contract

Each cleanup/offload recommendation must include:

Dashboard Requirements

Dashboard mode renders a static report and can refresh from progress.json during long runs.

1. Source contract: React + shadcn/ui component patterns + Tailwind CSS v4 tokens + Recharts visualizations. Read references/dashboard-app.md.
2. Packaged fallback: templates/dashboard.html must stay self-contained and must not require a CDN or network.
3. Required panels: run status hero, savings funnel, reclaimable-by-category chart, risk matrix, treemap, duplicate clusters, recommendation cards, cache impact, cloud offload board, progress timeline, manifest explorer.
4. Accessibility: semantic headings, keyboard-friendly tables, chart text fallbacks, high contrast, reduced-motion compatibility.
5. Data compatibility: support legacy keys (files, duplicates, directories, operations, cloud, summary) and v1.1 keys from progress-reporting.md.

Scaling Strategy

Reference Files

Load ONE reference at a time. Do not preload all references into context.

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py
python -m py_compile scripts/*.py
python scripts/dashboard-renderer.py --data <sample.json> --output <tmp.html>

Completion criteria:

1. scripts/check.py exits 0.
2. Dashboard smoke writes HTML; invalid JSON returns a JSON error.
3. No portable-CLI violations remain under this skill directory.

Critical Rules

1. Never delete, trash, prune, evict, move, archive, rename, or dedupe without explicit approval of a specific dry-run plan.
2. Never use rm or pipe finder output into deletion commands.
3. Never operate outside the approved scope pin.
4. Never modify hard-blocked paths.
5. Never follow symlinks outside scope.
6. Always show blast radius and repercussions before destructive operations.
7. Always create a manifest before the first approved operation.
8. Always record progress snapshots for long-running scans/executions.
9. Always separate exact duplicates from similar-media groups.
10. Always treat cloud synced deletion as Critical because it can sync loss to every device.
11. Always materialize cloud placeholders only after explaining local-space impact and receiving approval.
12. Always label Photos/Music/TV/Mail/Messages/Time Machine/VM snapshot recommendations as app-native or report-only unless explicitly approved.
13. Always include restore path and regeneration cost for cache cleanup recommendations.
14. Always verify BLAKE3 hashes, size, st_mode, and st_ino for finalized file operations when possible.
15. Always validate manifests stay under ~/.files-buddy/manifests/.
16. Always preserve .git/ and warn before touching tracked files.
17. Always load only the reference needed for the active mode.
18. Always report missing tools with free/OSS install commands and safe fallbacks.
19. Always use bounded-memory, checkpointed scans for huge trees.
20. Always run the validation contract before claiming the skill is complete.