For AI agents

Check and reclaim disk space from Terminal, or from your agent.

Disk Forecast comes with a diskforecast command. You, a script, or an AI agent like Claude Code or Codex can get the forecast, see what grew, and move what's safe to clear to the Trash, using the same data as the menu bar.

The short version

Install Disk Forecast with Homebrew and the diskforecast command is on your PATH. diskforecast status shows free space and the forecast, diskforecast changes --days 30 shows which folders grew, and diskforecast cleanup lists what can be reclaimed. diskforecast trash <id> shows what it would move, and --yes moves it to the Trash. Add --json to any command.

The commands

Command	What it does
`diskforecast status`	Free space, the forecast, a low-space warning, and how much is safe to clear
`diskforecast changes --days 30`	Which folders grew or shrank, down to the subfolder, and how much changed outside your home folder
`diskforecast cleanup`	What you can reclaim, grouped into Safe to clear and Worth a look, with an ID and explanation for each
`diskforecast trash <id or path>`	Shows what would move to the Trash; add `--yes` to move it
`diskforecast scan --wait`	Measures your home folder again and waits until it's done
`diskforecast open forecast`	Opens a window: forecast, cleanup, system-data, or settings

Add --json to any command for output a script or agent can parse. If Disk Forecast isn't running, the command opens it in the background first.

$ diskforecast status
142 GB free of 494 GB (29% free)
Full in ~30 days · using 4.7 GB a day
Safe to clear: 36 GB. See it with: diskforecast cleanup

Install it

Homebrew installs the app and links the command for you:

brew install --cask coreyhaines31/tap/diskforecast

If you installed Disk Forecast from the DMG, open Settings… › General and click Install… next to diskforecast command. macOS asks for your password. Or link it yourself in Terminal:

sudo mkdir -p /usr/local/bin
sudo ln -sf "/Applications/Disk Forecast.app/Contents/MacOS/diskforecast" /usr/local/bin/diskforecast

The command needs Disk Forecast 1.3 or later, and the Install button 1.4 or later, on macOS 14 Sonoma or later. Settings also has a Copy button for the agent prompt below.

Let your agent use it

Paste this into Claude Code or Codex, or add it to your CLAUDE.md or AGENTS.md so it applies every time:

When my Mac is low on disk space, use the `diskforecast` command (run `diskforecast --help`). Start with `diskforecast status` and `diskforecast changes --days 30` to explain what's filling the disk, then `diskforecast cleanup` to see what can be reclaimed. Show me what you'd move and ask before running `diskforecast trash <id> --yes`. Never delete files directly.

Then ask in plain words: “why is my disk almost full?”, “what grew this month?”, or “clear what's safe, but show me first.”

Why it's safe to hand to an agent

Only what's on the list. trash takes item IDs and paths from the cleanup list, and refuses everything else, including your Documents, Desktop, and anything outside your home folder.
Preview first. Without --yes, it only shows what it would move and how much space that is.
Trash, never gone. Everything goes to the Trash. You decide when to empty it.
Private. The command talks to the app over a socket only your user account can open, and nothing leaves your Mac.

Without the app: built-in Terminal commands

macOS has its own tools for a quick look. They show the disk right now, not where it's heading:

df -h /                          # free space on the startup disk
du -sh ~/* 2>/dev/null | sort -h   # folders in your home folder, biggest last
tmutil listlocalsnapshots /       # local Time Machine snapshots

How to check Mac storage explains each one, and why df and Finder can disagree.

What it looks like with an agent

Ask Claude Code why your disk is full. It reads the forecast and what changed, and tells you what's safe to clear before it moves anything.

Download free View source code

claude — ~

› My disk is almost full. What happened?

⏺ Bash(diskforecast changes --days 30)
  ⎿ What changed from Sep 13 to Oct 13:
       +22 GB   ~/Library
         +15 GB   Developer/CoreSimulator
       +14 GB   ~/.ollama
       +14 GB   ~/Downloads/macOS Installer.dmg (new)

⏺ Bash(diskforecast cleanup)
  ⎿ Safe to clear: 36 GB · Worth a look: 33 GB

⏺ Most of it is iOS simulators (+15 GB) and a new
  Ollama model (+14 GB). 36 GB is safe to clear:
  Xcode DerivedData, device support, and caches.
  Want me to move it to the Trash?

Questions

How do I install the diskforecast command?

Install Disk Forecast with Homebrew: brew install --cask coreyhaines31/tap/diskforecast. Homebrew links the command onto your PATH. If you installed from the DMG, open Settings › General in Disk Forecast and click Install, or link it once with sudo ln -sf "/Applications/Disk Forecast.app/Contents/MacOS/diskforecast" /usr/local/bin/diskforecast.

Can Claude Code or Codex use Disk Forecast?

Yes. Any agent that runs shell commands can. Ask it why your disk is filling up, or add a line to your CLAUDE.md or AGENTS.md telling it to use diskforecast when space is low.

Can an agent delete my files with it?

No. diskforecast trash only moves items that are on Disk Forecast's cleanup list, only to the Trash, and only shows what it would move until it's given --yes. Nothing is deleted until you empty the Trash yourself.

Does the command need the app running?

It talks to the Disk Forecast app, and opens it in the background if it isn't running. The app keeps the history the forecast is built from.

How do I check disk space on a Mac from Terminal without an app?

df -h / shows free space on the startup disk, and du -sh ~/* | sort -h lists the folders in your home folder by size. They show the current state, not how fast it's changing.

Related guides

Know before it's full.

Free. No account, no subscription.

Download free View source code

macOS 14 or later · Apple Silicon and Intel · brew install --cask coreyhaines31/tap/diskforecast