Claude Config Protector 🛡️

Protect your Claude Code from configuration corruption that causes crash loops and service unavailability.

The Problem

Claude Code's configuration file (~/.claude.json) can grow unbounded and become corrupted, causing:

• 🔴 Service crashes and infinite restart loops (1200+ restarts observed)
• 🔴 Complete loss of Claude Code availability
• 🔴 Manual intervention required every time
• 🔴 Lost productivity and frustration

Users report this happening daily when the config exceeds 8MB. See issue #2810.

The Solution

This protector runs in the background and automatically:

• ✅ Monitors config file for size and corruption
• ✅ Prevents corruption with atomic write operations
• ✅ Recovers automatically from corrupted configs
• ✅ Truncates large configs before they hit the 8MB threshold
• ✅ Backs up valid configurations hourly

Quick Start

macOS / Linux

# Clone the repository
git clone https://github.com/yourusername/claude-config-protector.git
cd claude-config-protector

# Run the installer
./install.sh

# Verify it's working
./test.sh

Windows (WSL)

# In WSL terminal
git clone https://github.com/yourusername/claude-config-protector.git
cd claude-config-protector

# Run the installer
./install.sh

# Add to startup (WSL)
echo "node ~/claude-config-protector/protector.js &" >> ~/.bashrc

Manual Installation

1. Install Node.js (if not already installed):

   # macOS
   brew install node
      
   # Linux
   sudo apt install nodejs npm
      
   # Windows
   # Download from https://nodejs.org

2. Clone and setup:

   git clone https://github.com/yourusername/claude-config-protector.git
   cd claude-config-protector
   npm install

3. Run the protector:

   node protector.js

4. Set up auto-start (optional):

   macOS (Launch Agent):

   cp com.claude.config.protector.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.claude.config.protector.plist

   Linux (systemd):

   cp claude-protector.service ~/.config/systemd/user/
   systemctl --user enable claude-protector
   systemctl --user start claude-protector

Features

🔒 Atomic Write Protection

Prevents partial writes that cause corruption:

// Instead of direct writes that corrupt:
fs.writeFileSync(configPath, data)

// Uses atomic operations:
fs.writeFileSync(tempPath, data)
fs.renameSync(tempPath, configPath)  // Atomic operation

📦 Automatic Backups

• Creates backups before any risky operation
• Maintains hourly snapshots of valid configs
• Keeps last 10 backups with automatic rotation
• Stores in ~/.claude-backups/

🔧 Self-Healing Recovery

When corruption is detected:

1. Saves corrupted file for analysis
2. Finds latest valid backup
3. Restores automatically
4. Claude Code continues working

📏 Size Management

• Monitors file size continuously
• Truncates at 5MB (well below 8MB danger zone)
• Removes old history and cached data
• Preserves essential configuration

How It Works

graph TD
    A[Monitor ~/.claude.json] --> B{Valid JSON?}
    B -->|No| C[Restore from Backup]
    B -->|Yes| D{Size > 5MB?}
    D -->|Yes| E[Truncate Old Data]
    D -->|No| F{Hour Passed?}
    F -->|Yes| G[Create Backup]
    F -->|No| A
    C --> A
    E --> A
    G --> A

Verification

Run the test suite to verify everything works:

./test.sh

Expected output:

✅ Corruption Recovery
✅ Size Limit Enforcement  
✅ Atomic Write Protection
✅ Backup Creation
✅ Missing File Handling

All tests passed!

Configuration

Edit protector.js to customize:

const MAX_SIZE = 5 * 1024 * 1024;  // Max file size (5MB default)
const MAX_BACKUPS = 10;             // Number of backups to keep
const CHECK_INTERVAL = 5000;        // Check frequency (5s default)

Troubleshooting

Check if protector is running

macOS:

launchctl list | grep claude.config

Linux:

systemctl --user status claude-protector

All platforms:

ps aux | grep protector.js

View logs

tail -f ~/.claude-backups/protector.log

Manually fix corrupted config

node fix-config.js

Emergency recovery

# Stop Claude
pkill -f claude

# Remove corrupted config
rm ~/.claude.json

# Restore from backup
cp ~/.claude-backups/claude-*.json ~/.claude.json

# Restart Claude
claude

File Structure

claude-config-protector/
├── protector.js              # Main protection daemon
├── fix-config.js             # One-time fixer for corrupted configs
├── test.sh                   # Test suite
├── install.sh                # Automated installer
├── com.claude.config.plist   # macOS Launch Agent
├── claude-protector.service  # Linux systemd service
└── README.md                 # This file

Performance

• Memory: < 10MB
• CPU: < 0.1%
• Disk: ~100KB for backups (10 files max)
• Network: None (completely local)

Why This Works

1. Atomic Operations: POSIX-compliant rename is atomic, preventing partial writes
2. Size Limits: Keeps config well below the 8MB corruption threshold
3. Proactive Monitoring: Catches issues before Claude crashes
4. Automatic Recovery: No manual intervention needed

Contributing

Pull requests welcome! Please:

1. Test your changes with ./test.sh
2. Update documentation
3. Follow existing code style

License

MIT - Use freely, no warranty provided.

Acknowledgments

• Thanks to the Claude Code community for reporting issue #2810
• Inspired by database write-ahead logging and journaling filesystems

Status

This is a community workaround until Anthropic implements the fix in Claude Code itself. Once the official fix is released, this tool will no longer be necessary.

Note: This tool is not affiliated with Anthropic. It's a community solution to help users experiencing configuration corruption issues.