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.

| Term | Definition | |------|------------| | all-local | Whole-Mac audit scope: home folders, cloud roots, /Volumes/*, caches, dev/AI stores, containers, VMs, and report-only app libraries | | dry-run | Tool-native preview or read-only simulation before any mutation | | approved plan | User-confirmed plan naming exact operation classes, paths, savings, risks, and restore path | | manifest | JSON operation log under ~/.files-buddy/manifests/ used for undo and verification | | progress snapshot | Live JSON at ~/.files-buddy/runs/{run-id}/progress.json | | blast radius | File count, local bytes, cloud bytes, directories, and operation classes affected | | protected path | Hard-blocked or escalated-confirmation path from references/protected-paths.md | | offload candidate | File or directory that can free local bytes while preserving recoverability elsewhere | | repercussion | Concrete consequence: re-download, rebuild, re-index, app breakage, sync delete, quota impact, or lost snapshot | | dependency evidence | Git refs, process refs, app library ownership, package/cache ownership, cloud state, or model/runtime references | | exact duplicate | Same content hash and distinct inode/link identity | | similar-media group | Perceptual image/video/audio candidates; never auto-trash | | cloud-safe | No automatic synced deletion; materialize only with approval; verify provider sync state | | dashboard | Static report plus optional live-refresh progress view built from the shadcn/ui + Tailwind v4 + Recharts source contract |

Dispatch

| $ARGUMENTS | Mode | Destructive? | Primary reference | |--------------|------|--------------|-------------------| | storage-audit all-local | Whole-Mac storage audit | No | macos-storage-map.md | | storage-audit / audit | Scoped storage audit | No | scan-performance.md | | cleanup-plan / clean | Ranked cleanup plan | No | dependency-impact.md | | offload-plan --to | Local-byte offload plan | No | offload-recommendations.md | | dedupe --exact | Exact duplicate plan | No | duplicate-detection.md | | dedupe --similar-media | Similar image/video/audio review | No | duplicate-detection.md | | cache-audit [all-local|dev|ai|containers|xcode] | Cache dependency/savings report | No | macos-storage-map.md | | organize | Organize plan/execution | Yes after approval | organization-strategies.md | | rename | Batch rename plan/execution | Yes after approval | rename-patterns.md | | archive | Archive plan/execution | Yes after approval | dependency-impact.md | | sanitize | Filename cleanup plan/execution | Yes after approval | tool-integrations.md | | find | Read-only search | No | tool-integrations.md | | watch [rules] | Auto-organize watcher | Yes after approval | organization-strategies.md | | progress | Show run progress | No | progress-reporting.md | | dashboard | Render dashboard | No writes report | dashboard-app.md | | execute | Execute previously approved plan | Yes | safety-workflow.md | | undo | Reverse manifest operations | Yes restores | safety-workflow.md | | Empty or unrecognized | Gallery and mode menu | No | — |

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:

| Field | Requirement | |-------|-------------| | Action | trash, offload, archive, dedupe, cache-prune, review, or skip | | Local bytes | Estimated bytes freed on this Mac | | Cloud bytes | Estimated cloud quota impact or 0 | | Confidence | High/medium/low with evidence | | Dependency evidence | Repos, package managers, running processes, app owners, cloud state, or model references | | Repercussions | What breaks, rebuilds, redownloads, re-syncs, or becomes slower | | Restore path | Undo command, app-native restore, cloud restore, or reinstall command | | Dry-run proof | Command output or report that proves no mutation occurred | | Approval tier | Low, Medium, High, or Critical |

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

| Scope | Strategy | |-------|----------| | --output

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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wyattowalsh](https://github.com/wyattowalsh)
- **Source:** [wyattowalsh/agents](https://github.com/wyattowalsh/agents)
- **License:** MIT
- **Homepage:** https://agents.w4w.dev

Install and usage instructions live in the source repository linked above.