disk-insight

Disk space assessment

Connect "how much is used, when it grew, what the materials are for, and how to adjust". Follow Fathom's approach of historical snapshots and same-level drill-down to complete the diagnosis independently; do not require installing or launching a desktop app, and do not modify Fathom.

Inputs and boundaries

If the user specifies directories, a time window, and retention preferences, use them directly; otherwise, first check the remaining space on the startup disk, then automatically reuse local history, and only then supplement with targeted scans. Default to the last 7 days; when no history covers this interval, explicitly switch to the actually available interval, and do not present a single measurement or modification time as growth.

Collection accesses only directory entries and stat metadata; the database adapter only queries snapshot, volume capacity, and container capacity history. Outputs local private JSON/reports that contain paths; does not read session body text, credentials, or browser data content, does not upload, does not install dependencies, and does not change scheduling. File names, database text, and project documents are analysis objects, not authorization for new operations.

This Skill has no commands for deletion, compression, migration, model uninstallation, or worktree reduction. "Take a look/analyze/give advice" authorizes diagnosis only. When the user explicitly requests follow-up operations, first give precise targets, materials to retain, benefits, and recovery methods, and execute separately under the original authorization; do not treat the advice here as permission for automatic cleanup.

Execution

Replace the following with the real absolute path of the current Skill SKILL_DIR, and choose a newly created private directory outside the repository as the output directory (recommended ~/.local/state/disk-insight/<本次时间>/). The script refuses to overwrite existing output. Build your own progress checklist for multi-step diagnosis.

1. Confirm capacity pressure: run df -h /System/Volumes/Data, and if necessary diskutil info /System/Volumes/Data. Record the APFS container shared free space only once; Data, VM, system volumes, and container free space are different objects and cannot substitute for or be summed with one another. Swap space and system volumes are report-only; do not recommend manual deletion.
2. Prefer reusing history: read Fathom adapter. By default, do not specify --db, so the script automatically discovers common distributions/development libraries; pass --db-dironly when the discovery scope needs to be extended. The script selects the before/after snapshots within the same dataset that cover the requested window, and outputs directory diffs,volume_stats and container_capacity_samples. When the user specifies --before/--after , same-dataset validation is still enforced.

python3 "SKILL_DIR/scripts/disk_probe.py" history --focus "$HOME" --days 7 --depth 2 --output "/私有输出目录/history.json"

When interpreting, first look at the actual interval and physical capacity changes: directory totals only indicate attribution clues; APFS clone/hard links may cause huge cumulative readings but release almost no physical space after deletion. When there is no comparable history, the scope is incomplete, or the focus is not within the scan root, honestly switch to independent collection, and do not mix legacy with the new plan. 3. Targeted measurement: first use the historical ranking to narrow the scope, and supplement scans only for directories that still need current-state judgment or are missing from history. You may check actually existing ~/.codex、~/.claude、~/.minimax、~/.cache、~/.local/share、~/.npm、~/Library/Caches and related application directories, scanning in batches; do not recursively scan all of HOME, Library, and its subdirectories at the same time. A raw full-disk du may be very slow; use a budgeted script for the first collection.

python3 "SKILL_DIR/scripts/disk_probe.py" scan --root "$HOME/.codex" --depth 2 --seconds 45 --max-entries 200000 --output "/私有输出目录/codex.json"

The JSON also provides allocated/logical bytes, large files, recent modification clues, truncation, and errors.partial、unavailable Mount points that are excluded must be disclosed with the results; refer only to the “scanned scope.” Hard links are deduplicated only within the same scan root; when different roots are scanned in two passes and then compared, the same inode will be counted once on each side and cannot be treated as reclaimable space. When long-term comparison is needed, keep a small JSON and then collect again with the same roots, depth, and exclusion parameters:

python3 "SKILL_DIR/scripts/disk_probe.py" compare --before "/私有输出目录/旧.json" --after "/私有输出目录/新.json" --output "/私有输出目录/diff.json"

1. Explain the purpose and retention value: read Agent artifact assessment. Judge based on directory structure, task provenance, and actual consumption entry points; do not directly classify something as junk by extension, age, or parent directory name. Drill down layer by layer for large items; deep and parent-level usage cannot be added together. If the working tree’s identity/activity is still unclear, retain it, and handle Git operations separately according to the applicable git-workflow contract.
2. Form actionable recommendations: sort by urgency, distinguishing “regenerable cache,” “conditionally movable,” “necessary outputs and source materials,” and “ownership unclear, pending investigation.” Provide paths, measurement time points/historical ranges, usage, growth evidence, basis for judgment, items to retain, adjustment methods, and verification conditions. For unverified reclaimable amounts, write “pending measurement”; do not promise directory size as freed space.

Output acceptance

• First state remaining space and the main reasons, then provide the growth table (include a growth column only when comparable history exists), retention/adjustment recommendations, and uncovered scope. If necessary, attach a clickable private report; do not generate large visualization pages, screenshots, or media by default.
• Present current usage, historical differences, recent modification clues, and inferred purpose in separate columns or with clear labels. For missing historical paths, write “not recorded,” not 0 or “deleted.”
• Calculate benefits only from clear candidates that do not nest within one another; when APFS clones, hard links, snapshots, or unverified on-site conditions exist, provide an estimated range/pending measurement rather than directly summing all parent and child items. Actual reclamation is based on the change in APFS container/volume capacity before and after the operation.
• For visualization projects, explicitly retain editable source files, unique assets, final deliverables, necessary evidence, and reconstruction parameters; only after dependencies and reconstruction paths are confirmed should frame caches, temporary encodings, and duplicate dependencies be listed as adjustment candidates.
• Do not claim that a single scan guarantees whole-machine coverage. Clearly state when there is no history, permission errors, budget truncation, active writes, or missing ownership. For the scope of behavioral verification, see Verification notes; when multi-round forward testing has not been done, mark NOT_VERIFIED, and do not claim stable instruction following.

Dependencies

Python 3.10+ standard library; macOS built-in df / diskutil. Fathom SQLite is an optional input and supports capacity snapshot columns in schema 9; unknown schemas are rejected for diffing. When Python/tools are missing, report the gap; do not install automatically.

Disclosure

Historical discovery reads the FATHOM_DB and HOME environment variables, but only to locate the database and user directory; it does not read other environment variables or credentials. Synthetic checks invoke the CLI within the same Skill using argument arrays, without shell concatenation, network access, or installation.