Restore Claude Code user configuration from a backup in ~/.claude-backups/
Restores Claude Code user configuration from a backup in ~/.claude-backups/
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-software[backup-name] [--list] [--mcp-only] [--dry-run]Restore Claude Code user configuration from a backup created by /user-config:backup.
| 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 |
--listList 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()
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))
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}")
--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}")
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")
# 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.
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.
/user-config:backup - Create a new backup/user-config:reset - Reset workflow with MCP preservation/user-config:status - Check configuration status after restoreThis command uses the user-config-management skill for: