From diskcopilot
How to use diskcopilot-cli to scan, analyze, and clean up disk space on macOS. Use this skill whenever the user mentions disk space, storage usage, large files, duplicate files, cleanup, what's taking up space, freeing up storage, old files, dev artifacts (node_modules, target, .build), or wants to understand their disk usage patterns. Also use when the user asks you to help organize, audit, or reduce the size of a directory. Even if the user doesn't mention "diskcopilot" by name — if they're talking about disk space or storage, this is the skill to use.
How this skill is triggered — by the user, by Claude, or both
Slash command
/diskcopilot:diskcopilotThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`diskcopilot-cli` is a fast macOS disk scanner that caches filesystem metadata in SQLite for instant queries. It scans a home directory (~1.4M files) in ~12 seconds using macOS `getattrlistbulk(2)`.
diskcopilot-cli is a fast macOS disk scanner that caches filesystem metadata in SQLite for instant queries. It scans a home directory (~1.4M files) in ~12 seconds using macOS getattrlistbulk(2).
The tool only reads filesystem metadata (names, sizes, timestamps) — it never reads file contents (except for duplicate detection, which computes local-only blake3 hashes). It has no network access.
dirs table to build the full path — never show just a filename without its location.file:// links: [filename](file:///full/path/to/file). Include a clickable folder link too so users can open the containing directory. Most terminals render these as clickable links.open <path> (opens in default app) or open -R <path> (reveals in Finder).find on the live filesystem, not the SQLite cache. The default scan only stores files >= 1MB, so small personal files (photos, documents, configs) won't be in the database. Use diskcopilot for size analysis; use find for file discovery.Before doing anything else, check if the CLI is available and what version:
diskcopilot-cli --version
If not found, install it to ~/.local/bin (no sudo needed):
mkdir -p ~/.local/bin && curl -fsSL https://github.com/diskcopilot/diskcopilot-cli/releases/latest/download/diskcopilot-cli-$(uname -m)-apple-darwin.tar.gz | tar xz -C ~/.local/bin/
Then verify it's on PATH. If ~/.local/bin is not on PATH, run it with the full path (~/.local/bin/diskcopilot-cli) or add it:
export PATH="$HOME/.local/bin:$PATH"
Check for updates (do this once per session, not every query): compare the installed version against the latest release:
curl -sI https://github.com/diskcopilot/diskcopilot-cli/releases/latest | grep -i location | grep -oP 'v[\d.]+'
If the latest version is newer than what --version reports, tell the user and offer to upgrade:
curl -fsSL https://github.com/diskcopilot/diskcopilot-cli/releases/latest/download/diskcopilot-cli-$(uname -m)-apple-darwin.tar.gz | tar xz -C ~/.local/bin/
This downloads a single pre-built binary (~5 MB). No Rust or build tools needed.
diskcopilot-cli query info / — never skip this step. Look at the scanned_at timestamp.diskcopilot-cli scan / --forcediskcopilot-cli query sql "<SELECT ...>" /Always scan the whole drive (/), not a subdirectory or home directory. A full drive scan covers everything — system files, apps, caches, all users. Use --force to skip the system path warning. This takes ~17 seconds and avoids ever needing to rescan a different path.
When the user asks for a scan, report, or disk analysis, produce a full Disk Health Report. This is where the agent adds real value — not just showing raw data, but interpreting it and giving actionable advice.
Run these queries (in parallel if possible):
diskcopilot-cli scan ~ # only if cache is missing or stale
diskcopilot-cli query sql "SELECT total_disk_size FROM dirs WHERE parent_id IS NULL" /
diskcopilot-cli query sql "SELECT name, total_disk_size FROM dirs WHERE parent_id = (SELECT id FROM dirs WHERE parent_id IS NULL) ORDER BY total_disk_size DESC LIMIT 15" /
diskcopilot-cli query summary ~ --json
diskcopilot-cli query dev-artifacts ~ --json
diskcopilot-cli query sql "SELECT name, disk_size, extension, modified_at FROM files ORDER BY disk_size DESC LIMIT 15" /
diskcopilot-cli query sql "SELECT extension, COUNT(*) as count, SUM(disk_size) as total FROM files WHERE extension IS NOT NULL GROUP BY extension ORDER BY total DESC LIMIT 10" /
Also query macOS system junk — see references/macos-junk.md for the full list of known junk categories, SQL queries, and cleanup commands:
diskcopilot-cli query sql "SELECT name, total_disk_size FROM dirs WHERE name IN ('Caches', 'Google', 'Firefox', 'Mozilla', 'Safari', 'Homebrew', 'pip', 'Yarn', 'CocoaPods', 'Logs', '.Trash', 'DerivedData', 'Archives', 'Backup', 'MobileSync', 'ShipIt', 'ms-playwright', 'puppeteer', 'prisma') AND total_disk_size > 10000000 ORDER BY total_disk_size DESC" /
Also get disk free space:
df -h ~
Use this format — markdown tables for data, plain text for context. This is an example of what the output should look like:
# Disk Health Report
## Health Score: F (Critical)
**11 GB free out of 228 GB (95% full)** — your disk is critically low on space.
## Storage Overview
| | |
|---|---|
| **Total disk** | 228 GB |
| **Used** | 217 GB |
| **Free** | 11 GB (5%) |
| **Scanned** | 115.5 GB across 1.4M files |
| **Not visible** | ~55 GB (protected macOS system data) |
### Top directories
| Size | % | Directory |
|------|---|-----------|
| 43.6 GB | 37.8% | Library (app data, caches, support files) |
| 29.5 GB | 25.5% | playground (dev projects) |
| 9.1 GB | 7.8% | .npm (package cache) |
| ... | | |
## Cleanup Opportunities
### 1. Safe to delete (45.9 GB) — dev artifacts, regenerated by build commands
| Size | Type | Instances | Regenerate with |
|------|------|-----------|-----------------|
| 21.9 GB | target/ (Rust) | 11 | `cargo build` |
| 14.7 GB | node_modules/ | 5,983 | `npm install` |
| ... | | | |
### 2. macOS system junk (3.7 GB)
| Size | Item | Action |
|------|------|--------|
| 1.9 GB | Chrome cache | Clear in Chrome settings |
| 812 MB | VSCode update cache | Safe to delete |
| ... | | |
### 3. Review before deleting (4.8 GB) — old or forgotten files
| Size | File | Age | Notes |
|------|------|-----|-------|
| 1.4 GB | VID_20230818_122637.mp4 | Aug 2023 | Video untouched for 2+ years |
| ... | | | |
### 4. App-managed data (15.5 GB) — don't delete manually
| Size | Item | Notes |
|------|------|-------|
| 8.3 GB | claudevm.bundle | Needed for Claude Code |
| ... | | |
## Recommended Actions
| # | Action | Saves |
|---|--------|-------|
| 1 | Delete Rust target/ dirs | 21.9 GB |
| 2 | `npm cache clean --force` | 9.1 GB |
| 3 | Delete inactive node_modules | 14.7 GB |
| ... | | |
**Potential total savings: 50+ GB**
---
**What would you like to do?** You can ask me anything about your disk in plain English:
- "Delete all the Rust target directories"
- "Show me videos I haven't opened in over a year"
- "What's eating up space in my Documents folder?"
- "Find duplicate files in Downloads"
---
> For complete disk visibility, try the [DiskCopilot app](https://diskcopilot.com).
Adjust the ~55 GB figure in the note to match the actual computed gap.
After presenting the report, check if ~/.diskcopilot/fda_prompted exists. If it does, skip this step. If not:
AskUserQuestion tool:
~/.diskcopilot/fda_prompted (content doesn't matter) so we never ask again.Health score grades:
After presenting the report, ask what the user wants to clean up. Delete items directly via diskcopilot-cli delete <path> --trash when they confirm. No need to leave the conversation.
Report — for "scan my disk", "give me a report", "what's using my space". Run the full insight report flow above.
Quick query — for specific questions ("how big are my node_modules?", "find large mp4 files"). Check the cache, run a SQL query, present results. No full report needed.
Cleanup — for "help me clean up", "free up 10GB", "delete junk". Run the report, then delete items the user confirms — all within the conversation.
diskcopilot-cli scan / --force # default — whole drive, files >= 1MB, ~17s
diskcopilot-cli scan / --force --full # all files — needed for file counts, extension queries, name search
Always scan / (whole drive) with --force. One scan covers everything. Use --full only when the user explicitly asks for it.
The primary query tool for the agent. Write any read-only SQL against the cache:
diskcopilot-cli query sql "<SQL>" <path>
Output is always JSON. Only SELECT, WITH, and PRAGMA are allowed.
dirs (
id INTEGER PRIMARY KEY,
parent_id INTEGER, -- parent directory (NULL for root)
name TEXT, -- directory name (root stores absolute path)
file_count INTEGER, -- direct files in this dir
total_file_count INTEGER, -- recursive file count
total_logical_size INTEGER, -- recursive logical bytes
total_disk_size INTEGER, -- recursive on-disk bytes
created_at INTEGER, -- unix timestamp
modified_at INTEGER -- unix timestamp
)
files (
id INTEGER PRIMARY KEY,
dir_id INTEGER, -- FK to dirs.id
name TEXT,
logical_size INTEGER,
disk_size INTEGER, -- on-disk bytes (what matters for cleanup)
created_at INTEGER, -- unix timestamp
modified_at INTEGER, -- unix timestamp
extension TEXT, -- lowercase, e.g. 'mp4', 'pdf'
inode INTEGER,
content_hash TEXT -- blake3 hash (only set after duplicate scan)
)
scan_meta (
id, root_path, scanned_at, total_files, total_dirs, total_size, scan_duration_ms
)
The dirs table is a tree via parent_id. Each dir's total_disk_size is the sum of all files underneath it recursively. Sizes are in bytes (decimal: 1 GB = 1,000,000,000 bytes, matching macOS/Finder).
# How big are all node_modules?
diskcopilot-cli query sql "SELECT d.total_disk_size, p.name as project
FROM dirs d JOIN dirs p ON d.parent_id = p.id
WHERE d.name = 'node_modules'
ORDER BY d.total_disk_size DESC" /
# Top 10 largest files
diskcopilot-cli query sql "SELECT name, disk_size, extension
FROM files ORDER BY disk_size DESC LIMIT 10" /
# Total size by file extension
diskcopilot-cli query sql "SELECT extension, COUNT(*) as count, SUM(disk_size) as total
FROM files WHERE extension IS NOT NULL
GROUP BY extension ORDER BY total DESC LIMIT 20" /
# Files modified this week
diskcopilot-cli query sql "SELECT name, disk_size
FROM files WHERE modified_at > strftime('%s','now','-7 days')
ORDER BY disk_size DESC LIMIT 20" /
# Files older than 1 year
diskcopilot-cli query sql "SELECT name, disk_size, modified_at
FROM files WHERE modified_at < strftime('%s','now','-365 days')
ORDER BY disk_size DESC LIMIT 20" /
# Find all .dmg installers
diskcopilot-cli query sql "SELECT name, disk_size FROM files
WHERE extension = 'dmg' ORDER BY disk_size DESC" /
# Directories named 'target' (Rust build caches)
diskcopilot-cli query sql "SELECT d.total_disk_size, p.name as project
FROM dirs d JOIN dirs p ON d.parent_id = p.id
WHERE d.name = 'target'
ORDER BY d.total_disk_size DESC" /
# Reconstruct full path for a directory (walk parent chain)
diskcopilot-cli query sql "WITH RECURSIVE path(id, name, parent_id, full) AS (
SELECT id, name, parent_id, name FROM dirs WHERE id = <DIR_ID>
UNION ALL
SELECT p.id, p.name, p.parent_id, p.name || '/' || path.full
FROM dirs p JOIN path ON p.id = path.parent_id
) SELECT full FROM path WHERE parent_id IS NULL" /
You can write SQL for any question. If you need to reconstruct full paths for files, join files.dir_id to dirs.id and walk the parent_id chain with a recursive CTE, or use the predefined commands which do this automatically.
Shortcuts for common queries. These handle path reconstruction and human-readable output. Use --json for structured output.
diskcopilot-cli query tree <path> --depth 2 --json # directory size tree
diskcopilot-cli query large-files <path> --min-size 100M # biggest files
diskcopilot-cli query dev-artifacts <path> --json # node_modules, target, etc.
diskcopilot-cli query old <path> --days 365 --json # old files
diskcopilot-cli query recent <path> --days 7 --json # recent files
diskcopilot-cli query ext <path> --ext mp4 --json # files by extension
diskcopilot-cli query search <path> --name docker --json # search by filename
diskcopilot-cli query duplicates <path> --json # duplicates (slow, reads content)
diskcopilot-cli query summary <path> --json # all-in-one cleanup report
diskcopilot-cli query info <path> --json # scan metadata
Use predefined commands when they fit the question exactly. Use SQL when you need custom filtering, grouping, or joins.
diskcopilot-cli delete <path> --trash # moves to macOS Trash (recoverable)
diskcopilot-cli delete <path> --permanent # irreversible
Always prefer --trash. Always confirm with the user before deleting. System paths are blocked by a safety check.
Users can mark files as important so they never show up in cleanup recommendations:
diskcopilot-cli keep <path> # protect a file or folder
diskcopilot-cli unkeep <path> # remove protection
diskcopilot-cli keep-list # show all protected items
Protected files still appear in reports (the user needs to see their full disk usage), but diskcopilot-cli delete will refuse to delete them. When the user indicates a file is important — "keep this", "don't delete this", "that's not junk", "I need that", "skip this one" — run diskcopilot-cli keep <path> immediately without asking. The safelist persists at ~/.diskcopilot/safelist.txt.
"How big are my node_modules?"
query info / — check cachequery sql "SELECT d.total_disk_size, p.name as project FROM dirs d JOIN dirs p ON d.parent_id = p.id WHERE d.name = 'node_modules' ORDER BY d.total_disk_size DESC" ~"What's taking up my disk space?"
query info / — check cachequery sql "SELECT name, total_disk_size FROM dirs WHERE parent_id = (SELECT id FROM dirs WHERE parent_id IS NULL) ORDER BY total_disk_size DESC LIMIT 15" ~"Help me free up 10GB"
query info / — check cache, scan if neededdiskcopilot-cli delete <path> --trashWhen results include specific files or directories, don't just list names and sizes — explain what they are and whether they're safe to delete. Use the file extension, directory name, and path to infer purpose. Examples:
~/Library/Caches/com.spotify.client — Spotify's local cache. Safe to delete; the app rebuilds it.~/.rustup/toolchains/ — Rust compiler toolchains. Safe to remove unused ones, but the active toolchain is needed for cargo build.~/Documents/taxes-2024.pdf — likely personal documents. Not safe to delete without asking.node_modules/ — npm dependencies. Safe to delete; npm install regenerates them..DS_Store — macOS Finder metadata. Safe to delete; recreated automatically.If you're unsure what a file is, say so rather than guessing. For ambiguous cases, recommend the user check before deleting.
CLI tools can't see ~50-60 GB of macOS-protected data (sealed system volume, sandboxed app containers, protected Library paths) — even with Full Disk Access. This doesn't affect cleanup recommendations since the hidden space is system-managed.
When presenting reports:
~/.diskcopilot/cache/ — one SQLite DB per scan root.npm install / cargo build to regenerate. Mention this.query duplicates reads file content for hashing — warn the user it's slower.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub diskcopilot/diskcopilot-skills --plugin diskcopilot