freespace

freespace

freespace frees disk space on a Mac. It clears caches and build output that your tools can rebuild, and git worktrees whose work is already merged.

It shows what it would remove before it removes anything. A plain freespace is always a dry run.

Install

curl -fsSL https://raw.githubusercontent.com/jcobhams/freespace/master/install.sh | bash

This downloads freespace into ~/.local/share/freespace and links the freespace command into ~/.local/bin. It also links the agent skill into every AI coding agent it finds, as described in Use it from an AI agent. Run the same command again to update.

To uninstall:

curl -fsSL https://raw.githubusercontent.com/jcobhams/freespace/master/install.sh | bash -s -- --uninstall

FREESPACE_BIN changes where the command goes, FREESPACE_HOME changes where the download goes, and FREESPACE_REF installs a branch or tag other than master. The installer never replaces a folder it didn't create.

If you'd rather work from a clone, run the installer from it. The links then point into the clone, so git pull updates them:

git clone https://github.com/jcobhams/freespace.git
cd freespace
./install.sh

You can also skip the installer and run ./freespace from the clone.

It needs macOS and git. It runs on the bash that ships with macOS. Each section checks for its tool first, so one you don't use (Docker, Rust, Xcode) skips itself.

Use

freespace                      # dry run: what would go, and how big it is
freespace --apply              # remove it
freespace --ask                # go through it item by item, asking before each one
freespace --only node,python   # just these sections
freespace --skip docker,xcode  # everything except these
freespace --help               # all sections and options

To choose what goes, pick sections with --only and --skip, and folders with --scan and --exclude. For example, this removes one old project's node_modules and nothing else:

freespace --only node --scan ~/code/old-project --project-days 0 --apply

--ask lets you decide item by item instead. It shows each item with its size and asks before removing it. Enter keeps it, so nothing goes unless you type y.

In a dry run, a line that starts with a size is something --apply removes. Lines that start with "kept" explain what it left alone and why. Commands it would run are shown as would run:.

Node and Next build output
  10.9 GB  ~/code/dash/.next
  802.5 MB  ~/code/videos/node_modules (project untouched for 14+ days)
  kept 55 folders in use now or in projects changed in the last 14 days

Git worktrees
  kept ~/code/api/.worktrees/deposits: used in the last 2 days
  183.0 MB  ~/code/api/.worktrees/search (feature/search, merged into main)
    would run: git -C ~/code/api worktree remove --force ~/code/api/.worktrees/search

Total
  281.4 GB  this run frees with --apply
  336.9 GB  with every option on:
    +35.9 GB  --project-days 0
    +3.5 GB  --days 0
    +8.3 GB  --include-unmerged
    +7.8 GB  --min-ios 27

The dry run ends with a total. The first line is what this run frees. The second is what you'd free with every opt-in option turned on, followed by what each option adds. Simulator clones, the pnpm store, conda and dangling Docker images aren't counted, because their size can't be measured reliably up front. A dry run that measures the options takes a few minutes, since it sizes everything it keeps too.

After --apply it prints your free space before and after.

Use it from an AI agent

skills/freespace is an Agent Skill: a folder with a SKILL.md that tells a coding agent when and how to run freespace. Once it's installed, you can ask your agent things like "why is my disk full?" or "free up some space". The skill tells the agent to run a dry run first, show you the total, and only run --apply after you say yes.

The installer links it for every agent it finds:

To add it to another agent that reads Agent Skills, link ~/.local/share/freespace/skills/freespace into the skills folder that agent's docs name, as a folder called freespace. From a clone, link skills/freespace inside the clone instead.

Copy it with cp -RL instead of cp -R if you'd rather not link it. The skill's scripts/freespace is a link to the script at the top of the repo, and -L copies the real file. Start a new agent session afterwards so it picks the skill up.

What it removes

node, rust, cpp, python and worktrees search every folder in your home folder except hidden ones, Library, Applications, Movies, Music, Pictures, Public, OrbStack and the Go module cache. They also search ~/.config/superpowers/worktrees. Use --scan to search only the folders you name, and --exclude to skip one.

How it stays safe

• Nothing is deleted without --apply or --ask, and the config file can't turn either on.
• It only deletes inside your home folder and the Claude Code temp folder. It resolves parent symlinks and .. before checking containment, then checks again before deletion. The roots themselves and final symlinks are kept.
• Build output written in the last hour is kept, so a running dev server or build keeps its files.
• node_modules, Rust target/ folders, C++ build folders and virtual environments are only removed from projects with no file changes in 14 days (--project-days).
• Worktree paths are resolved before checking them against scan roots, exclusions, and your home folder. These checks run again after confirmation, immediately before removal. The same boundaries apply to empty leftover worktree folders.
• A worktree is only removed when all of these hold:
  • its branch is merged into the repo's main or master;
  • it has no uncommitted changes (Finder's .DS_Store files don't count);
  • it had no commits or checkouts in the last 2 days (--days);
  • it isn't locked.
• Its branch is then deleted with git branch -d, which refuses anything unmerged.
• An unmerged worktree is kept. With --include-unmerged, its folder goes but its branch stays, and the output shows the command that brings it back.
• A worktree whose repo has moved gets its .git link repaired before it's checked.
• C++ builds inside the source folder (in-source builds) are never removed, and neither are virtual environments without a pyproject.toml, requirements*.txt, Pipfile, setup.py or uv.lock to rebuild them from.
• Docker volumes and poetry's virtualenvs are never removed.
• Nothing is removed from hidden folders in your home folder, so tools like ~/.nvm and ~/.vscode keep their own node_modules.
• The Xcode section waits while xcodebuild is running, and cargo's sources are kept while cargo is running.

Options

--days 0 and --project-days 0 drop the waiting period. The one-hour guard still applies.

Config file

Put options you always want in ~/.config/freespace/options, one per line. Command-line options override them.

# Docker keeps its data here
--exclude ~/docker-data
--min-ios 26
--project-days 30

FREESPACE_CONFIG points it at a different file. Use one option per line, with its value on the same line when required. Paths may contain spaces. Invalid lines stop the run; --apply and --ask are only allowed on the command line.

Good to know

• du over-reports simulator clones, because APFS copies share disk blocks. That's why the summary compares free space before and after instead of adding up folder sizes.
• macOS removes deleted simulator runtimes in the background. Check your free space again a few minutes later.
• Docker Desktop and OrbStack keep images inside a disk image. Space can take a while to return to your Mac after Docker deletes things.
• The Go build cache can grow by hundreds of gigabytes in a few days if you build in many worktrees. freespace --only go-cache --apply is worth running often.

License

MIT. See LICENSE.