User Configuration Restore

Restore Claude Code user configuration from a backup created by /user-config:backup.

Arguments

Argument	Description
backup-name	Name of backup directory (e.g., backup-2025-12-30-153045)
--list	List available backups without restoring
--mcp-only	Only restore MCP server configurations
--dry-run	Show what would be restored without making changes
(no args)	Interactive selection from available backups

Workflow

Mode: --list

List all available backups with details:

import json
from pathlib import Path

backup_root = Path.home() / ".claude-backups"
backups = sorted(backup_root.glob("backup-*"), reverse=True)

if not backups:
    print("No backups found in ~/.claude-backups/")
else:
    print(f"Found {len(backups)} backup(s):\n")
    for backup in backups:
        manifest_path = backup / "manifest.json"
        if manifest_path.exists():
            manifest = json.load(open(manifest_path))
            created = manifest.get("created_at", "Unknown")
            backup_type = manifest.get("backup_type", "unknown")
            file_count = len(manifest.get("files", []))
            print(f"  {backup.name}")
            print(f"    Created: {created}")
            print(f"    Type: {backup_type}")
            print(f"    Files: {file_count}")
            print()

Mode: Interactive (no args)

1. List available backups
2. Use AskUserQuestion to let user select
3. Proceed with restore

Mode: Restore Specific Backup

import json
import shutil
from pathlib import Path

home = Path.home()
claude_dir = home / ".claude"
backup_root = home / ".claude-backups"

# Find specified backup
backup_name = "backup-2025-12-30-153045"  # From argument
backup_dir = backup_root / backup_name

if not backup_dir.exists():
    print(f"❌ Backup not found: {backup_name}")
    exit(1)

# Load manifest
manifest_path = backup_dir / "manifest.json"
if not manifest_path.exists():
    print(f"❌ Invalid backup (no manifest.json): {backup_name}")
    exit(1)

manifest = json.load(open(manifest_path))

Step 1: Restore MCP Servers

mcp_backup = backup_dir / "mcp-servers.json"
claude_json = home / ".claude.json"

if mcp_backup.exists():
    # Load backed-up MCP servers
    mcp_servers = json.load(open(mcp_backup))

    # Load or create current config
    if claude_json.exists():
        config = json.load(open(claude_json))
    else:
        config = {}

    # Merge MCP servers (backup takes precedence)
    existing_mcp = config.get("mcpServers", {})
    merged_count = len(set(existing_mcp.keys()) | set(mcp_servers.keys()))
    config["mcpServers"] = {**existing_mcp, **mcp_servers}

    # Save updated config
    json.dump(config, open(claude_json, "w"), indent=2)

    print(f"✅ Restored {len(mcp_servers)} MCP servers")
    for name in mcp_servers.keys():
        print(f"   • {name}")

Step 2: Restore Settings (if not --mcp-only)

restore_mappings = [
    ("settings.json", claude_dir / "settings.json"),
    ("settings.local.json", claude_dir / "settings.local.json"),
    ("CLAUDE.md", claude_dir / "CLAUDE.md"),
    ("CLAUDE-home.md", home / "CLAUDE.md"),
    ("claudeignore", home / ".claudeignore"),
]

restored = []
for backup_file, dest in restore_mappings:
    source = backup_dir / backup_file
    if source.exists():
        # Create parent directory if needed
        dest.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source, dest)
        restored.append((backup_file, str(dest)))

if restored:
    print(f"\n✅ Restored {len(restored)} configuration files:")
    for name, dest in restored:
        print(f"   • {name} → {dest}")

Step 3: Restore History (if present)

history_backup = backup_dir / "history.jsonl"
if history_backup.exists():
    dest = claude_dir / "history.jsonl"
    shutil.copy2(history_backup, dest)
    print(f"✅ Restored history.jsonl")

Output Format

# Restore Complete

**Source:** ~/.claude-backups/backup-2025-12-30-153045/
**Backup Type:** Essential config
**Backup Created:** 2025-12-30T15:30:45Z

## Restored Items

### MCP Servers (5 restored)
- perplexity
- microsoft-learn
- firecrawl
- context7
- ref

### Configuration Files
| File | Restored To |
|------|-------------|
| settings.json | ~/.claude/settings.json |
| CLAUDE.md | ~/.claude/CLAUDE.md |

## Next Steps

⚠️ **Restart Claude Code** to activate restored MCP servers.

## Verification

Run `/user-config:status` to verify configuration health.

Safety Features

• Non-destructive merge: MCP servers are merged, not replaced
• Existing config preserved: Only missing/backed-up items restored
• Dry-run mode: Preview changes before applying
• Manifest validation: Only restores from valid backups
• No credential restore: .credentials.json is never restored

Conflict Resolution

When restoring to an existing configuration:

Item	Behavior
MCP servers	Merged (backup overrides existing with same name)
settings.json	Replaced entirely
CLAUDE.md	Replaced entirely

Note: If you want to preserve existing settings, use --mcp-only to only restore MCP servers.

Related Commands

• /user-config:backup - Create a new backup
• /user-config:reset - Reset workflow with MCP preservation
• /user-config:status - Check configuration status after restore

Related Skill

This command uses the user-config-management skill for:

• Backup structure knowledge
• Restore procedures
• Cross-platform path handling