Storage and Disk Space

HQ keeps a backup history of your files so you can get old versions back, and that history grows over time. Big files and leftover coding folders can add up too. This article covers the two ways to free space: the Storage page in Settings, and the /free-disk-space command.

The Storage page#

To open it, click your picture at the bottom of the left rail, choose Settings, then click Storage. You can also press Cmd+, on a Mac (Ctrl+, on Windows).

At the top, the page shows how much space HQ backups use on your computer and how big your HQ folder itself is. Reading these sizes can take a few minutes on a big folder, so the page first shows the last figures it read, marked with their age (for example Figures from 20 min ago.), then updates them in place. Click Refresh to read them again. Looking at the page never deletes anything.

If you don't see Storage in Settings, it isn't turned on for your account yet.

Big files#

The Big files section is first on the page. It lists files over 50 MB that you can move to HQ cloud to free space on your computer:

• Old copies of big files in your backup history. HQ stores them in your HQ cloud instead, and you can still get any of them back.
• Big files you haven't opened in a while (14 days or more). They still show in your HQ folder and download again when you open them. This row only appears once your version of HQ can move them safely.

To move them:

1. Click Move to cloud and free ~X (X is the space you'll get back).
2. HQ checks which files would move and asks you to confirm. Click Move to cloud.
3. Each moved file leaves a small .hqcloud placeholder file in its place. Double-click it and HQ downloads the original and opens it in its usual app.

HQ uploads and checks each file before it frees any space. If something goes wrong partway, it tells you, and your files stay on your computer.

Backup history#

Below Big files are two tables, sorted by age bands (like the last 7 days, the last month, and older).

Local backup history is the snapshots HQ keeps on your computer every time your files change. Cloud file history is the old versions of files each of your companies keeps in the cloud. Your current files are never touched.

To free space:

1. Tick an age band. That band and everything older are selected together.
2. Check the total next to Free up ~X.
3. Click Delete selected, read the summary, and click Delete to confirm.

A few rules apply:

• The last 7 days are always kept. You can't tick that band.
• Only company owners and admins can delete a company's cloud history. If you're not one, that table is read-only for you.
• Deleted old versions can't be restored, so HQ always shows you what will go before it deletes anything.
• Space from local backups doesn't come back right away. HQ keeps recent undo history for a while, up to 30 days, and the confirm message tells you the date the space will be freed. Deleted cloud versions are gone at once.

Freeing space from coding work: /free-disk-space#

If you use HQ for coding, old copies of projects, build folders, and developer caches can take up far more space than your backups. Type this in a Claude Code or Codex session inside your HQ folder:

/free-disk-space

It scans your computer and shows a plain table of the biggest areas, how big each one is, and whether it's safe to clear. Then it asks what you'd like to clean up:

• Developer caches. Only a named list of caches that rebuild themselves, like the ones Homebrew, npm, pip, and Yarn keep.
• Extra project copies (linked worktrees) that are clean, fully pushed, and haven't been used in a while.
• Build and dependency folders inside project copies you haven't touched in a week or more. Your code and commits stay.

Every option starts as a dry run. HQ shows you exactly what it would remove and what it's keeping and why, and deletes nothing. It only removes files after you say yes, when it runs again with --apply.

It never deletes full project clones, .env files, or work you haven't pushed. Project copies with uncommitted changes or unpushed commits are left alone.

Common questions#

If you get stuck#

If the Storage page says to update HQ, install the latest version from Settings → Updates and try again. For sync questions, see the Sync Guide. Otherwise, see The "I'm Stuck" Guide, or report it with /hq-bug.