Claude Code node process deletes user-managed agent files from ~/.claude/agents/

Summary

Claude Code's node process is silently deleting all user-managed files from ~/.claude/agents/. Files committed to version control are unlinked in bulk, seemingly as part of an agent directory sync. This is a recurring issue that has happened multiple times.

Evidence

A root fs_usage watcher (LaunchDaemon + fswatch) was installed to catch the culprit. On 2026-03-30, it logged the following at 18:26:17:

18:26:17  unlink  ../dotfiles/claude/.claude/agents/change-compliance.md    node
18:26:17  unlink  ../dotfiles/claude/.claude/agents/compliant-planner.md    node
18:26:17  unlink  ../dotfiles/claude/.claude/agents/implementation.md       node
18:26:17  unlink  ../dotfiles/claude/.claude/agents/specification.md        node
18:26:17  unlink  ../dotfiles/claude/.claude/agents/team-lead.md            node
18:26:17  unlink  ../dotfiles/claude/.claude/agents/worker.md               node

All six files deleted by the node process in the same second. 47 minutes earlier, the same node process had been writing to the directory using the .tmp-then-rename atomic write pattern (CC's own file write signature):

17:23:01  rename  ./dotfiles/claude/.claude/agents/compliant-planner.md.tmp.10564.1774887793532    node
17:23:13  rename  ./dotfiles/claude/.claude/agents/compliant-planner.md.tmp.10564.1774887805065    node
17:23:21  rename  ./dotfiles/claude/.claude/agents/change-compliance.md.tmp.10564.1774887813423    node
...

Pattern: CC writes the files, then deletes them ~47 minutes later.

Environment

• macOS (Apple Silicon)
• Claude Code versions: 2.1.87 and 2.1.88 (both observed)
• ~/.claude/agents/ is a symlink to ~/dotfiles/claude/.claude/agents/
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS was set to both "0" and "1" — deletion occurred with both values

Impact

Every agent file in ~/.claude/agents/ is deleted. Files that are version-controlled in a dotfiles repo show as unstaged deletions. Subagent workflows (/dev, /dev-loop) fail because compliant-planner, change-compliance, and implementation agents no longer exist.

This has happened on multiple separate occasions (first observed 2026-03-27, recurred 2026-03-30).

Workaround Applied

Set macOS user-immutable flag (chflags uchg) on all agent files. This causes the unlink syscall to return EPERM, preventing deletion. This is not a real fix — it prevents CC from managing the directory at all.

Expected Behaviour

Claude Code should not delete files from ~/.claude/agents/ that it did not create in the current session. User-managed agent files should be treated as persistent configuration, not as transient state to be cleared.

If CC needs to manage a subset of agents (e.g. synced from a cloud account), it should merge with existing files rather than clearing the directory.