Reduce token waste from redundant file change notifications

[shukebeta]

Problem

Claude Code currently sends <system-reminder> notifications with full file diffs every time a file changes, regardless of who modified it. This causes significant token waste in several scenarios:

1. AI's own edits are re-notified: When Claude uses eed/Edit tools, it sees the diff in the tool result, then receives the same diff again in a system-reminder on the next turn
2. User edits during session: When users manually edit files with sed, external editors, or other AI tools, Claude receives full diffs even when not actively working on those files
3. Large file changes: Long files with small changes still transmit the entire context repeatedly

Real-World Impact: Multi-Tool Workflows

Common scenario that wastes tokens:

1. User starts Claude Code session (context: 17k tokens)
2. User switches to another AI tool (Cursor/OpenCode/Aider) to do rapid iteration
3. User makes 10-15 file changes using the other tool
4. User returns to Claude Code
5. Claude receives full diffs of all 10-15 files via system-reminders
6. Context now at 66k+ tokens - Claude "watched" changes it didn't participate in
7. User paid for Claude to passively observe another AI's work

Why this hurts:

• Users are effectively paying for two AIs when only using one
• Token limits are reached faster, forcing new sessions
• Most of the transmitted diffs are never referenced in subsequent conversation

Better Alternative: On-Demand Change Review

Instead of automatic notifications, let users control when Claude should sync:

# User worked with another tool, now returning to Claude:
User: "Review what I changed in the last commit"

# Claude actively fetches when needed:
Claude: [runs] git diff HEAD~1
# OR
Claude: [runs] git log -p -1

# Token usage: pay only when context is needed

Benefits:

• User control: Decide when Claude needs to know about changes
• Batch efficiency: One git diff command > 10 separate file reminders
• Context awareness: User provides intent ("I refactored auth") instead of Claude inferring from raw diffs
• Token savings: 70%+ reduction in passive file-watching overhead

Proposed Solutions

Option 1: Add notification mode setting ⭐ (Strongly Preferred)

{
  "fileChangeNotifications": "manual",  
  // Modes:
  // - "off": No automatic notifications
  // - "auto": Current behavior (notify all changes)
  // - "manual": Only sync when user explicitly requests (e.g., "/sync" or "show me what changed")
}

Option 2: Smart deduplication

• Don't send reminder if the last tool result already showed the same diff
• Only notify for changes made outside Claude's own tool calls

Option 3: Minimal notifications

• Just notify "file X changed" without the full diff
• Users can explicitly Read if they need to see changes

Option 4: Scope-based notifications

• Only notify about files currently in the conversation context
• Ignore unrelated file changes

Why This Matters

Claude Code is often used alongside other tools:

• Cursor/Copilot for rapid coding
• Claude Code for architectural discussions and complex refactoring
• vim/vscode for quick fixes
• Formatters/linters that auto-modify files

Current behavior penalizes this workflow by charging users for Claude to passively observe all file system activity, even when Claude isn't the active assistant.

Impact Summary

Current behavior:

• Token consumption: 2x for AI-made changes, unlimited for external changes
• User cost: Pay for Claude to "watch" other tools work
• Session length: Artificially shortened by passive monitoring overhead

With manual mode:

• Token consumption: Only when context is needed
• User cost: Pay only for active assistance
• Session length: Determined by actual conversation, not file watching

This change would make Claude Code more efficient in multi-tool development workflows while giving users fine-grained control over token usage.