User Configuration Reset

Reset Claude Code configuration with MCP server preservation. This command helps you perform a clean reinstall while keeping your MCP server configurations intact.

Arguments

Argument	Description
--backup	Create backup of MCP servers and settings (Step 1)
--restore	Restore MCP servers from backup (Step 3, after relaunch)
--list-backups	List available backups
(no args)	Interactive wizard guiding through full reset workflow

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│                    Reset Workflow                           │
├─────────────────────────────────────────────────────────────┤
│ Step 1: /user-config:reset --backup                         │
│   → Extracts MCP servers from ~/.claude.json                │
│   → Saves to ~/.claude-backups/                             │
│                                                             │
│ Step 2: User Action (Manual)                                │
│   → Delete ~/.claude/ directory                             │
│   → Delete ~/.claude.json                                   │
│   → Relaunch Claude Code (creates fresh config)             │
│                                                             │
│ Step 3: /user-config:reset --restore                        │
│   → Injects MCP servers into fresh ~/.claude.json           │
│   → Optionally restores settings.json                       │
└─────────────────────────────────────────────────────────────┘

Task: Execute Based on Arguments

Mode: --backup

Create a backup before reset:

import json
import shutil
from datetime import datetime, timezone
from pathlib import Path

# Setup paths
home = Path.home()
claude_dir = home / ".claude"
claude_json = home / ".claude.json"
backup_root = home / ".claude-backups"

# Create timestamped backup directory
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d-%H%M%S")
backup_dir = backup_root / f"backup-{timestamp}"
backup_dir.mkdir(parents=True, exist_ok=True)

backed_up = []

# 1. Extract and save MCP servers from ~/.claude.json
if claude_json.exists():
    with open(claude_json) as f:
        config = json.load(f)
    mcp_servers = config.get("mcpServers", {})
    if mcp_servers:
        mcp_backup = backup_dir / "mcp-servers.json"
        with open(mcp_backup, "w") as f:
            json.dump(mcp_servers, f, indent=2)
        backed_up.append(f"MCP servers ({len(mcp_servers)} servers) → {mcp_backup}")

# 2. Copy settings.json if exists
settings_path = claude_dir / "settings.json"
if settings_path.exists():
    settings_backup = backup_dir / "settings.json"
    shutil.copy2(settings_path, settings_backup)
    backed_up.append(f"settings.json → {settings_backup}")

# 3. Optionally copy history.jsonl (user choice)
# history_path = claude_dir / "history.jsonl"
# if history_path.exists():
#     shutil.copy2(history_path, backup_dir / "history.jsonl")

print(f"\n✅ Backup created: {backup_dir}")
for item in backed_up:
    print(f"   • {item}")

Output:

✅ Backup created: ~/.claude-backups/backup-2025-12-30-165217/
   • MCP servers (5 servers) → mcp-servers.json
   • settings.json → settings.json

Next steps:
1. Delete ~/.claude/ directory
2. Delete ~/.claude.json
3. Relaunch Claude Code
4. Run: /user-config:reset --restore

Mode: --restore

Restore MCP servers after fresh install:

import json
from pathlib import Path

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

# Find most recent backup
backups = sorted(backup_root.glob("backup-*"), reverse=True)
if not backups:
    print("❌ No backups found in ~/.claude-backups/")
    exit(1)

latest_backup = backups[0]
mcp_backup = latest_backup / "mcp-servers.json"

if not mcp_backup.exists():
    print(f"❌ No MCP servers backup found in {latest_backup}")
    exit(1)

# Load backed-up MCP servers
with open(mcp_backup) as f:
    mcp_servers = json.load(f)

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

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

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

print(f"\n✅ Restored {len(mcp_servers)} MCP servers from {latest_backup.name}")
for name in mcp_servers.keys():
    print(f"   • {name}")
print("\n⚠️  Restart Claude Code to activate MCP servers")

Mode: --list-backups

List available backups:

from pathlib import Path
import json

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:
        mcp_file = backup / "mcp-servers.json"
        settings_file = backup / "settings.json"

        contents = []
        if mcp_file.exists():
            with open(mcp_file) as f:
                mcp = json.load(f)
            contents.append(f"{len(mcp)} MCP servers")
        if settings_file.exists():
            contents.append("settings.json")

        print(f"  {backup.name}")
        print(f"    Contents: {', '.join(contents) if contents else 'empty'}")

Mode: Interactive (no args)

Guide user through the full reset workflow:

1. Check current state - Show what exists
2. Create backup - Run --backup logic
3. Show deletion commands - Provide exact commands for user to run manually
4. Explain next steps - Instructions for restore after relaunch

IMPORTANT: This command does NOT perform the actual deletion. It prepares the backup and provides instructions. The user must manually delete files to prevent accidental data loss.

Safety Features

• No automatic deletion - User must manually delete files
• Backup before any changes - MCP servers preserved
• Confirmation required - Use AskUserQuestion before proceeding
• Clear instructions - Step-by-step guidance

Backup Location

All backups stored in ~/.claude-backups/:

• Sibling to .claude/ - not affected by cleanup operations
• Timestamped directories: backup-YYYY-MM-DD-HHmmss/
• Persists across reinstalls

What Gets Backed Up

Item	Backed Up	Rationale
MCP servers	✅ Always	Critical - hard to recreate
settings.json	✅ Always	User preferences
history.jsonl	❓ Optional	Large, less critical
credentials	❌ Never	Security - will re-auth
sessions	❌ Never	Ephemeral, large
debug logs	❌ Never	Ephemeral

Related Commands

• /user-config:backup - Full backup (coming soon)
• /user-config:restore - Full restore (coming soon)
• /user-config:status - Check current configuration state
• /user-config:audit - Validate configuration health