Stop Time Machine from eating your disk when you run AI agents (macOS) — asimov + exclusions walkthrough

Written together with my AI coding agent — it's what actually diagnosed and fixed this on my machine, then drafted this writeup and the prompt below. Sharing it in that spirit, not pretending I hand-typed every word.

⚠️ Correction (2026-07-03): the folder-exclusion approach in this walkthrough (asimov / tmutil addexclusion) only slims your final backed-up output — what gets copied to an external backup drive. It does NOT reduce ongoing disk usage from macOS local snapshots, which is the thing that actually fills your disk during agent churn. A local APFS snapshot is a whole-volume image; individual folders can't be excluded from it (only a whole volume can). To reclaim the ongoing disk space, schedule tmutil thinlocalsnapshots /, isolate churn on a dedicated excluded APFS volume, or sudo tmutil disable. Keep the steps below for lean backups — just not for this.

Your AI agents + Time Machine are quietly eating your disk — here's a prompt to fix it

If you run AI coding agents on a Mac, you're generating a lot of file churn: git worktrees, node_modules, local databases, caches, thousands of ephemeral files an hour. macOS Time Machine takes an hourly local snapshot (even with no backup drive attached), and because APFS snapshots are copy-on-write, each one pins every block as of that hour — so your disk fills overnight with frozen copies of work your agents already threw away. (du even lies about it — only df sees the truth.)

Instead of a step-by-step guide, here's the modern way to share a fix: a prompt. Copy the block below and paste it into whatever coding agent drives your terminal (Claude Code, Cursor, Codex, …). It diagnoses your machine and walks you through the fix — adapted to your setup, with guardrails so nothing important gets excluded.

📋 The prompt — copy this and paste it into your coding agent to get started

NOTE: The steps below exclude folders from Time Machine, which only slims your
BACKED-UP OUTPUT (what's copied to an external drive). They do NOT reduce ongoing
disk usage from macOS LOCAL SNAPSHOTS — the hourly whole-volume copies that fill
your internal disk during agent churn. For that, use ONE of: schedule
`tmutil thinlocalsnapshots /`, put high-churn data on a dedicated excluded APFS
volume, or `sudo tmutil disable`.

You are helping me stop macOS Time Machine from filling my disk with local
snapshots of high-churn, regenerable files created by my dev tools / AI agents.
Work INTERACTIVELY and SAFELY — confirm with me before changing anything.

1. Diagnose (read-only first): run `df -h /` for real free space and
   `tmutil listlocalsnapshots /` to count hourly local snapshots. Explain briefly
   how APFS copy-on-write snapshots pin churned blocks so the disk fills — and why
   `du` misleads (only `df` is accurate here).

2. Find my high-churn, REGENERABLE directories. Ask me about my setup and look for:
   dependency dirs (node_modules, vendor, .venv…), build/output dirs, caches, git
   worktrees, and any local database stores (sqlite/dolt/etc.) my tools write to.
   Show me the candidate list before touching anything.

3. Install asimov (https://github.com/stevegrunwell/asimov): `brew install asimov`.
   It auto-excludes dependency dirs from Time Machine by sentinel (e.g. node_modules
   next to package.json). Explain what it will and won't cover.

4. For the extra high-churn dirs asimov doesn't catch (worktrees, local DB stores,
   runtime/cache dirs), exclude each with `tmutil addexclusion <path>` — this runs
   at USER level, NO sudo. Verify each with `tmutil isexcluded <path>`.

5. Make it stick: set asimov to run on a schedule (a launchd agent) so newly
   created dirs get excluded automatically.

6. Optional but recommended: add a tiny `df`-based watchdog (launchd/cron) that
   warns me when free disk drops below a threshold, so a low-disk situation
   NOTIFIES me early instead of silently wedging the machine mid-run.

GUARDRAILS — do not skip:
- Only exclude REGENERABLE or independently-backed-up dirs. NEVER exclude my source
  code or .git.
- Before excluding any DATABASE store, confirm with me that it has an independent
  backup (a remote or replica). If it doesn't, do NOT exclude it — Time Machine may
  be its only backup.
- Show me the candidate list and get my OK before excluding anything.
- If my disk is already critically full, tell me the emergency reclaim command is
  `sudo tmutil thinlocalsnapshots / 500000000000 4` (needs sudo) — but explain it
  before I run it.

What you'll end up with

Dependency dirs auto-excluded from Time Machine (asimov, on a schedule).
Your extra high-churn dirs (worktrees, local DB stores) excluded too — each verified.
A disk watchdog that warns you early.
Snapshots that stay small no matter how hard your agents churn.

Why this matters

The friendly defaults we've trusted for a decade were tuned for human-paced change. Agents don't move at human pace. As we hand more of our machines to agents, the boring infrastructure underneath — backups, snapshots, caches — deserves a second look. The defaults aren't wrong; they're just from a different era.

(This bit me hard running a large parallel agent setup — ~80 GB gone overnight — but the prompt works for any dev machine that churns a lot of files.)

wbern/tm-agents-walkthrough.md

Select an option