← Mac guides

How AI Stopper snapshots and recovers your configs safely

Moving developer config and auth files like ~/.claude.json, ~/.cursor/mcp.json, or ~/.codex/auth.json requires rock-solid crash recovery. Here is exactly how snapshots, conflict handling, and AI Stopper Recovery work.

Updated 2026-11-19 · Applies to AI Stopper 0.2.1+

Where paused snapshots live on your Mac

Everything stays strictly local inside ~/.aistopper/:

  • ~/.aistopper/paused.json — Atomic journal recording the current phase (preparing, paused, or restoring), exact source/destination paths for every moved file, and stopped Homebrew services.
  • ~/.aistopper/snapshots/SNAPSHOT_ID/ — Exact bytes of each temporarily moved config or credential file.

What happens if something goes wrong mid-pause or mid-resume

  • Interrupted during pause (power loss / crash): The journal stays in preparing. On the next start, AI Stopper detects the unfinished pause and automatically rolls back every moved file to its original path.
  • File recreated while paused: If an app or script writes a brand-new file at a snapshotted path while tools are paused, resuming restores your original file and preserves the newer file inside the snapshot directory as during_pause_*—nothing is silently overwritten.
  • Retryable restore: If a restore is interrupted in the restoring phase, running resume again picks up safely and completes the remaining files.

Using the standalone AI Stopper Recovery app

If the main AI Stopper app ever fails to start while your tools are paused:

  1. Open Finder, go to your home folder’s Applications folder (~/Applications/), and launch AI Stopper Recovery.app.
  2. Confirm Restore Access. Recovery bundles its own independent Python engine copy so it does not depend on the main app window.
  3. If you installed the optional AI-domain blocker (/Library/LaunchDaemons/ru.aistopper.netguard.plist), you can also tick Also uninstall the AI domain blocker inside the same dialog.

Inspect your local state directory read-only in Terminal anytime:

ls -la "$HOME/.aistopper"