A judgment-driven storage investigator for Claude Code and Codex.
Install · See an example · Safety model

TidyMac finds what occupies a Mac, investigates why it exists, and gives the decision first:

Nothing changes until you approve the exact action.

Ask:

$tidymac

Get:

Clean up · 14.8 GB
  Package downloads       9.9 GB  Redownloaded only if needed
  Old diagnostic logs     4.6 GB  Old troubleshooting history
  Browser cache           0.3 GB  Regenerates silently

Optional · 11.2 GB
  Project build output    6.1 GB  Requires a rebuild
  Local model             5.1 GB  Requires a redownload

Keep
  Photos library                  Personal originals
  Active runtime volume           Stateful and in use

_{Synthetic example. Real findings come from the audited Mac.}

Choose a group or finding. TidyMac rechecks it, shows the exact command or native action, asks once for informed approval, runs only the selection, and measures what changed.

npx skills add azohra/tidymac -a claude-code -a codex

Invoke it with your host’s syntax:

Node.js only copies the skill. TidyMac has no runtime package, Python, Node.js, daemon, compiled helper, service, or API dependency.

mkdir -p "$HOME/.claude/skills" "$HOME/.agents/skills"
cp -R /path/to/tidymac/skills/tidymac "$HOME/.claude/skills/tidymac"
cp -R /path/to/tidymac/skills/tidymac "$HOME/.agents/skills/tidymac"

Finding a large directory is easy. Deciding whether it is disposable is contextual.

An 8 GB cache may regenerate silently, require a six-hour download, accelerate active work, or be mislabeled state. Application Support may be abandoned settings—or the only local copy of a workflow.

TidyMac correlates native inventories, dry-runs, owners, activity, manifests, receipts, timestamps, and current documentation. Size finds the suspect; evidence decides the action.

The audit starts broad, follows detected evidence, and lowers its scan floor until another pass no longer changes the explanation or recommendation.

No storage vocabulary is required:

Why is my Mac full?

Tell me what to clean, what is optional, and what to keep.

I need 20 GB. Find the least painful way to get it.

Free as much space as you reasonably can without disrupting my work.

On hosts with rich output, TidyMac can generate an interactive report from the same records and arithmetic as the text answer.

It shows decision totals first, then coverage, reconciliation, and individual findings. Finding size means observed local allocation—not promised recovery. Selecting findings prepares exact previews; it cannot execute commands or count as approval.

A standalone report uses the bundled offline HTML template with no remote assets or command bridge.

• Audits are read-only by default.
• Every mutation is tied to an exact approved finding and action.
• Unknown data stays out of cleanup groups.
• Personal content remains aggregate context unless deeper review is requested.
• The current project tree is excluded from path cleanup.
• Native cleanup, cloud eviction, relocation, Trash, synced deletion, reset, and permanent deletion remain separate scopes.
• Direct-path cleanup uses a revalidated Trash move, never improvised recursive deletion.
• Trash is staged space until reviewed and emptied.
• Stateful volumes, backups, archives, and opaque VM disks receive individual treatment.

Understanding is automatic. Changing the machine is explicit.

• macOS
• Claude Code or Codex
• A strong reasoning model for a full-machine audit

Optional tools such as brew, docker, and xcrun are used only when already installed and relevant. TidyMac does not call its own service, transmit the audit, or bundle credentials.

TidyMac uses semantic GitHub releases: patch for fixes, minor for backward-compatible behavior, major for incompatible contracts.