Skip to content

README.md

Latest commit

 

History

History
164 lines (115 loc) · 4.94 KB

README.md

File metadata and controls

164 lines (115 loc) · 4.94 KB

diskcopilot-cli

Fast macOS disk scanner and query tool. Scans your filesystem, caches metadata in SQLite, and lets you query it instantly.

Designed for two consumers:

  • Humans — via Yazi file manager plugin or CLI
  • AI agents — via --json output on all query commands

Performance

  • ~12s to scan a home directory with 1.4M files on APFS
  • Uses macOS getattrlistbulk(2) for bulk metadata retrieval (3-6x faster than readdir+stat)
  • Falls back to jwalk on non-APFS volumes
  • Size accuracy matches DaisyDisk/Finder (decimal units, APFS firmlink handling)

Install

# One-line install (Apple Silicon)
curl -fsSL https://github.com/bluedusk/diskcopilot-cli/releases/latest/download/diskcopilot-cli-aarch64-apple-darwin.tar.gz | tar xz && sudo mv diskcopilot-cli /usr/local/bin/

# Intel Mac
curl -fsSL https://github.com/bluedusk/diskcopilot-cli/releases/latest/download/diskcopilot-cli-x86_64-apple-darwin.tar.gz | tar xz && sudo mv diskcopilot-cli /usr/local/bin/

Or build from source (requires Rust 1.70+):

git clone https://github.com/bluedusk/diskcopilot-cli
cd diskcopilot-cli && make install

Usage

Scan

diskcopilot-cli scan ~/Downloads              # files >= 1MB (default)
diskcopilot-cli scan ~ --full                 # all files
diskcopilot-cli scan / --force --full         # full drive (--force for system paths)

Query

All query commands support --json for machine-readable output.

# Directory size tree
diskcopilot-cli query tree ~ --depth 2

# Largest files
diskcopilot-cli query large-files ~ --min-size 100M --limit 50

# Recently modified
diskcopilot-cli query recent ~ --days 3

# Old files
diskcopilot-cli query old ~ --days 180

# Dev artifacts (node_modules, target, .build, etc.)
diskcopilot-cli query dev-artifacts ~

# Files by extension
diskcopilot-cli query ext ~ --ext mp4

# Search by name
diskcopilot-cli query search ~ --name docker

# Cleanup summary report
diskcopilot-cli query summary ~

# Duplicate files (reads content for hashing — slower)
diskcopilot-cli query duplicates ~

# Scan metadata
diskcopilot-cli query info ~

Delete

diskcopilot-cli delete /path/to/file --trash       # move to Trash
diskcopilot-cli delete /path/to/file --permanent    # permanent delete

JSON output for AI agents

diskcopilot-cli query large-files ~ --json | jq '.[0]'
{
  "name": "big-video.mp4",
  "full_path": "/Users/you/Downloads/big-video.mp4",
  "disk_size": 4200000000,
  "modified_at": 1710000000
}

Yazi Plugin

A Yazi plugin that adds disk analytics to your file manager. See diskcopilot.yazi/README.md for setup.

Features:

  • S to scan current directory
  • d + key for analytics (large files, duplicates, dev artifacts, etc.)
  • Directory previewer showing size breakdown when hovering
make install-plugin    # install to ~/.config/yazi/plugins/

Architecture

scan → SQLite cache → query / Yazi plugin / AI agent
  • Scanner — two engines: getattrlistbulk(2) (macOS primary) and jwalk (fallback)
  • Cache — SQLite at ~/.diskcopilot/cache/<blake3-hash>.db, one DB per scan root
  • Query — SQL queries against the cache, with pretty-print or JSON output
  • Yazi plugin — Lua calling diskcopilot-cli via shell commands

See docs/scanning-algorithm.md for the scanner's evolution through 6 iterations.

Privacy & Security

diskcopilot-cli scans filesystem metadata only. It does not read file contents, connect to the internet, or send data anywhere.

What it collects:

  • File/directory names, sizes, timestamps, extensions
  • Inode numbers (for hardlink dedup during scan)

What it does NOT do:

  • Read file contents (exception: query duplicates reads content to compute blake3 hashes for dedup — hashes are stored locally only)
  • Make any network connections — there are zero networking dependencies
  • Send telemetry, analytics, or crash reports
  • Access keychain, credentials, or sensitive system data

All data is stored locally in ~/.diskcopilot/cache/ and is readable only by your user account.

Verify for yourself: the project has no networking crates — check Cargo.toml or run cargo tree | grep -i 'http\|reqwest\|hyper\|curl'.

Permissions

  • Works without elevated permissions for your home directory
  • Full Disk Access (System Settings > Privacy) is needed to scan system-wide
  • sudo gives filesystem access but not the same results as Full Disk Access (SIP-protected paths remain inaccessible)
  • System paths (/System, /usr, etc.) require --force flag as a safety measure

Development

cargo build --release       # release build
cargo test                  # all tests
cargo clippy                # lint
cargo fmt                   # format
make check                  # fmt + lint + test

License

MIT