macOS updates can silently change how ~/Documents resolves, causing AI coding tools to lose all project-scoped data.

The Problem

Claude Code (and likely other tools) keys project data - chat history, memory, session state - to the resolved filesystem path of the project directory. On macOS with iCloud Drive enabled, ~/Documents can resolve two different ways:

  • /Users/username/Documents/ (direct path)
  • /Users/username/Library/Mobile Documents/com~apple~CloudDocs/Documents/ (iCloud path)

Both point to the same files, but they produce different path keys. When a macOS update changes which resolution the system uses, Claude Code sees the project under a new path key and treats it as a brand-new project - all previous chats, memory files, and session state become invisible.

How I Found It

After a macOS update in February 2026, all Claude Code project history for the Alcanah AI workspace disappeared. Chats were gone, memory was empty, the project appeared freshly initialized. The actual data was intact on disk - just keyed under the old path.

The Fix

Claude Code stores project-scoped data in ~/.claude/projects/ using URL-encoded path keys:

~/.claude/projects/-Users-username-Documents-Alcanah-AI/           # new path
~/.claude/projects/-Users-username-Library-Mobile-Documents-com~apple~CloudDocs-Documents-Alcanah-AI/  # old path

The fix is to copy contents from the old directory to the new one:

# 1. Identify old and new project dirs
ls ~/.claude/projects/ | grep "Alcanah-AI"

# 2. Copy contents from old to new
cp -r ~/.claude/projects/-Users-username-Library-Mobile-Documents-*-Alcanah-AI/* \
      ~/.claude/projects/-Users-username-Documents-Alcanah-AI/

# 3. Keep old dir as backup until verified

Glob Patterns Fail Silently Too

The same root cause makes file-search tools quietly broken on iCloud-synced paths. Shallow patterns like mcp-guides/** return nothing - no error, no warning, just empty results. Deep patterns with **/ prefix (**/mcp-guides/**) work fine. So does ls via bash. The failure is specific to how certain tools resolve the iCloud path.

If you’re building anything that touches files on macOS, always use **/ prefix patterns as a default and never assume ~/Documents is a simple path.

Prevention

There’s no way to prevent macOS from changing path resolution. But you can detect it early:

  • If Claude Code suddenly has no memory of your project, check ~/.claude/projects/ for duplicate directories with different path encodings
  • The symptom is always the same: project data exists but is invisible because the path key changed

A nastier variant of the same trap: launchctl can’t access iCloud Drive paths at all. If your LaunchAgent references files in ~/Library/Mobile Documents/, it fails silently - the daemon never starts, no error surfaces in launchctl list, and you’re left wondering why nothing runs. Copy runtime files to a non-iCloud directory before installing any LaunchAgent.

Broader Lesson

Any tool that derives a storage key from a filesystem path is vulnerable to this on macOS with iCloud Drive. The path to the same directory is not stable across OS updates. Tools should either normalize paths before keying, or use a project identifier that’s independent of the filesystem path (like a UUID stored in the project directory).