claude-switcher

v1.0.6

Published

3 months ago

Cross-platform CLI tool for switching between different Claude AI model configurations. Supports automatic backup, rollback, and multi-platform configuration management for Claude API integrations.

Claude Model Switcher

🚀 A powerful cross-platform CLI tool for effortlessly switching between different AI model configurations

Seamlessly manage multiple Claude-compatible API configurations with automatic backup, rollback, and cross-platform support. Perfect for developers working with multiple AI providers like DeepSeek, Qwen, GLM, Kimi, and more.

✨ Key Features

🌍 Cross-Platform Support: Works seamlessly on Windows, macOS, and Linux
🔒 Safe Switching: Automatic backups before every configuration change
⚡ Ultra-Fast Commands: Use cs s -r to switch and reload in seconds
🎯 Smart Detection: Automatically finds Claude configuration directories
🔄 Rollback Protection: Instant recovery from failed switches
🎨 Dual Interface: Beautiful CLI + modern web interface for all preferences
✅ Validation: Ensures configuration integrity before applying changes
📦 Multiple Providers: Support for DeepSeek, Qwen, GLM, Kimi, and more

🎯 Why Use Claude Model Switcher?

Perfect For These Scenarios

🔬 AI Researchers: Quickly compare different models on the same task
💼 Enterprise Teams: Separate dev/staging/production configurations
🚀 Developers: Switch between cost-effective and high-performance models
🌍 Multi-Region: Different API endpoints for different geographical regions
🔐 Security: Isolate API keys for different projects or environments

Real-World Benefits

# Before: Manual config editing (error-prone, no backup)
vim ~/.claude/settings.json  # Edit manually, hope you don't break it

# After: Safe, instant switching with backup
cs s -r  # Interactive switch with automatic backup and reload

Time Savings

Manual switching: ~2-3 minutes per change (edit, backup, reload, verify)
With claude-switcher: ~10 seconds per change
Daily savings: 15-30 minutes for active AI developers

🌍 Cross-Platform Support

Automatically detects Claude configuration directories on all platforms:

| Platform | Supported Directories | |----------|----------------------| | Windows | %APPDATA%\.claude%USERPROFILE%\.claude%LOCALAPPDATA%\.claude | | macOS | ~/.claude~/Library/Application Support/claude~/Library/Preferences/claude | | Linux | ~/.config/claude (XDG compliant)~/.claude~/.local/share/claude |

🚀 Quick Installation

One-Line Install (Recommended)

npm install -g claude-switcher

That's it! Both claude-switch and cs commands are now available globally.

Verify Installation

cs --version
# Should display: claude-switcher v1.x.x

Alternative Installation Methods

npm install claude-switcher
npx claude-switch --help

git clone https://github.com/zhaoth/claude-switcher.git
cd claude-switcher
npm install && npm run build
npm link

System Requirements

Node.js: 14.0.0 or higher
Operating System: Windows, macOS, or Linux
Disk Space: ~10MB

⚡ Quick Start

Get up and running in 30 seconds:

1. Install and Test

npm install -g claude-switcher
cs --version

2. Create Your First Configuration

# Navigate to your Claude directory (auto-created if needed)
mkdir -p ~/.claude

# Create a sample configuration
cat > ~/.claude/settings_deepseek.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-token-here",
    "ANTHROPIC_MODEL": "deepseek-reasoner",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  }
}
EOF

3. Start Using

cs l        # List available configurations
cs s        # Switch configuration (interactive)
cs s -r     # Switch and reload terminal
cs st       # Check current status

🎯 Most Common Commands

| Command | Description | Example | |---------|-------------|---------| | cs l | List all configurations | Shows available configs in a table | | cs s -r | Switch with auto-reload | Switches and reloads terminal | | cs st | Show current status | Displays active configuration | | cs v | Verify environment | Checks if env matches config |

💡 Pro Tip: Always use cs s -r to switch configurations - it automatically reloads your terminal so changes take effect immediately!

💻 Usage Guide

Essential Commands (90% of daily usage)

cs l        # 📋 List all configurations
cs s -r     # 🔄 Switch configuration (with auto-reload)
cs st       # 📊 Show current status
cs v        # ✅ Verify environment consistency

Complete Command Reference

| Command | Short | Description | Example Output | |---------|-------|-------------|----------------| | cs l | cs list | List configurations | Table showing all configs | | cs s | cs switch | Interactive switch | Menu to select config | | cs s -r | cs switch --reload | Switch + reload terminal | Immediate effect | | cs st | cs status | Current config info | Detailed status display | | cs v | cs verify | Check environment | Validation results | | cs r | cs restore | Restore from backup | Backup selection menu | | cs ui | cs ui | Launch web interface | Opens browser with modern GUI |

🌟 UI Command Options

cs ui                    # Default: localhost:3001, auto-open browser
cs ui --port 8080        # Custom port
cs ui --host 0.0.0.0     # Allow external network access
cs ui --no-open          # Start server without opening browser
cs ui --help             # Show all UI options

🌐 Web Interface (NEW!)

Launch a beautiful, modern web-based interface for visual configuration management:

cs ui                    # Start UI server (opens browser automatically)
cs ui --port 8080        # Use custom port
cs ui --no-open          # Start server without opening browser
cs ui --host 0.0.0.0     # Allow external access

🎯 Key Features:

🎨 Visual Configuration Editor: Create and edit configs with intuitive forms instead of JSON
🔧 Smart Provider Templates: Pre-configured templates for 8+ AI providers (DeepSeek, Qwen, GLM, Kimi, Claude, OpenAI, Ollama, etc.)
🧪 Real-time Connection Testing: Test API connections with latency measurement before saving
📊 Live Status Dashboard: Real-time updates when configs change (CLI ↔ UI sync)
💾 Visual Backup Management: Browse, create, and restore backups with timestamps
🌙 Adaptive Themes: Auto dark/light theme with manual override
🔍 Configuration Validation: Real-time JSON validation and error highlighting
📚 Integrated Documentation: Provider-specific setup guides and API key links
🚀 Model Discovery: Automatically fetch available models from each provider
⚡ Instant Switching: One-click configuration activation with terminal reload

🎪 Perfect For:

👥 Teams: Visual interface for non-technical team members
🔧 Complex Setups: Managing 10+ configurations with ease
🧪 Testing: Quick A/B testing between different AI providers
📱 Remote Access: Web-based access from any device on your network

The web interface provides all CLI functionality plus additional visual features, making it perfect for users who prefer graphical interfaces or need to manage complex multi-provider configurations.

🔥 Pro Usage Patterns

Daily Developer Workflow

# Morning: Check what's available and switch to work config
cs l && cs s -r

# During development: Quick status checks
cs st

# End of day: Switch to personal config
echo "personal" | cs s -r

Team Environment Management

# Development environment
cs s -r  # Select 'dev' config

# Staging testing
cs s -r  # Select 'staging' config

# Production deployment
cs s -r  # Select 'prod' config

Model Comparison Workflow

# Test with different models
cs s -r  # Switch to DeepSeek
# Run your tests...

cs s -r  # Switch to Qwen
# Run same tests...

cs s -r  # Switch to GLM
# Compare results...

Configuration Directory Detection

The tool automatically detects your Claude configuration directory based on your operating system. If you have a custom setup, you can specify the directory manually:

import { ConfigManager } from 'claude-switcher';

// Automatic detection (recommended)
const manager = await ConfigManager.createWithAutoDetection();

// Manual directory specification
const customManager = new ConfigManager('/path/to/custom/claude/dir');

// Platform-specific detection
const detectedDir = ConfigManager.detectClaudeConfigDir();

📝 Configuration Examples

Basic Configuration Format

Configuration files use the pattern settings_<name>.json in your Claude directory:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.provider.com",
    "ANTHROPIC_AUTH_TOKEN": "your-api-token",
    "ANTHROPIC_MODEL": "primary-model-name",
    "ANTHROPIC_SMALL_FAST_MODEL": "fast-model-name"
  }
}

🔥 Popular AI Provider Configurations

File: ~/.claude/settings_deepseek.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-deepseek-token",
    "ANTHROPIC_MODEL": "deepseek-reasoner",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  }
}

Get API keys at: https://platform.deepseek.com/

File: ~/.claude/settings_qwen.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-qwen-token",
    "ANTHROPIC_MODEL": "qwen-max",
    "ANTHROPIC_SMALL_FAST_MODEL": "qwen-turbo"
  }
}

Get API keys at: https://dashscope.aliyuncs.com/

File: ~/.claude/settings_glm.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4",
    "ANTHROPIC_AUTH_TOKEN": "your-glm-token",
    "ANTHROPIC_MODEL": "glm-4-plus",
    "ANTHROPIC_SMALL_FAST_MODEL": "glm-4-flash"
  }
}

Get API keys at: https://open.bigmodel.cn/

File: ~/.claude/settings_kimi.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-kimi-token",
    "ANTHROPIC_MODEL": "moonshot-v1-128k",
    "ANTHROPIC_SMALL_FAST_MODEL": "moonshot-v1-8k"
  }
}

Get API keys at: https://platform.moonshot.cn/

File: ~/.claude/settings_local.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434/v1",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_MODEL": "llama3.1:70b",
    "ANTHROPIC_SMALL_FAST_MODEL": "llama3.1:8b"
  }
}

Requires Ollama running locally

📚 Need more examples? Check out CONFIG_EXAMPLES.md for comprehensive configuration examples for 10+ AI providers.

🔧 Quick Troubleshooting

Most Common Issues (95% of problems)

| Issue | Quick Fix | Command | |-------|-----------|---------| | 🚫 Command not found | Reinstall globally | npm install -g claude-switcher | | 🔄 Config not taking effect | Use reload flag | cs s -r | | 📁 No configs found | Check file naming | Files must be settings_name.json | | ❌ Invalid JSON | Validate syntax | cat file.json \| jq . | | 🔐 Permission denied | Fix permissions | chmod 755 ~/.claude |

🚨 Emergency Recovery

# If something goes wrong, restore from backup
cs r

# If that fails, check what backups exist
ls -la ~/.claude/*.backup.*

# Manual restore (replace TIMESTAMP with actual timestamp)
cp ~/.claude/settings.json.backup.TIMESTAMP ~/.claude/settings.json

🔍 Debug Mode

When things aren't working as expected:

# Enable detailed logging
DEBUG=claude-switcher cs l

# Check environment consistency
cs v

# Verify current status
cs st

💡 Pro Tips for Avoiding Issues

Always use -r flag: cs s -r (auto-reloads terminal)
Validate JSON first: Use online JSON validator before adding configs
Check status after switching: Run cs st to confirm changes
Keep backups: They're created automatically, use cs r to restore

📚 Need more help? Check out our comprehensive TROUBLESHOOTING.md guide for detailed solutions.

❓ Frequently Asked Questions

A: Create a new JSON file in your Claude directory:

cd ~/.claude
cp settings_existing.json settings_newprovider.json
# Edit the new file with your provider's API details
# It will automatically appear in `cs l`

A: Built-in safety mechanisms protect you:

✅ Automatic backup before switching
✅ Configuration validation
✅ Automatic rollback on failure
✅ Original configuration preserved

A: Yes! Use it as a library:

import { ConfigManager } from 'claude-switcher';

const manager = await ConfigManager.createWithAutoDetection();
await manager.switchToConfig('deepseek');

A: Automatic timestamped backups:

📅 Format: settings.json.backup.YYYYMMDD_HHMMSS
📍 Location: Same directory as configurations
🔄 Restore: Use cs r to restore any backup

A: Yes! All commands work in scripts:

# Non-interactive switching
echo "production" | cs s

# Or use the API for full control

A: Simple npm update:

npm update -g claude-switcher
cs --version  # Verify new version

📚 More questions? Check our comprehensive FAQ.md for detailed answers to 20+ common questions.

Getting Help

Command Line Help

claude-switch --help     # Full help
cs --help               # Short help
cs <command> --help     # Command-specific help

📚 Complete Documentation

| Document | Description | Best For | |----------|-------------|----------| | ⚡ Quick Start | 2-minute setup guide | New users | | 🚀 Usage Examples | Most common usage patterns | Daily workflows | | 💻 API Documentation | Programmatic usage examples | Developers | | ⚙️ Installation Guide | Detailed setup for all platforms | Setup issues | | 📖 Complete Help | Comprehensive command reference | Power users | | 🔧 Troubleshooting | Common issues and solutions | When things break | | 📝 Config Examples | 10+ AI provider configurations | Adding new providers | | ⌨️ Command Shortcuts | Quick reference for all commands | Daily usage | | ❓ FAQ | 20+ frequently asked questions | Common questions |

🌟 Why Developers Love Claude Model Switcher

"Saves me 30 minutes daily switching between AI providers for different projects" - @developer123

"The automatic backup feature saved me when I accidentally broke my config" - @airesearcher

"Ultra-fast cs s -r command is a game-changer for my workflow" - @mlops_engineer

🤝 Contributing & Support

💡 Feature Requests & Bug Reports

Found a bug or have a feature idea? Open an issue on GitHub.

🛠️ Contributing

We welcome contributions! Check out our contributing guidelines to get started.

💬 Community

📧 Email: [email protected]
🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions

🎉 Ready to Get Started?

1. Install Now

npm install -g claude-switcher

2. Verify Installation

cs --version
# Should show: claude-switcher v1.x.x

3. Create Your First Config

mkdir -p ~/.claude
# Add your first configuration file (see examples above)

4. Start Switching

cs l        # List configurations
cs s -r     # Switch with auto-reload

🚀 Next Steps

⭐ Star this repo if you find it useful
📖 Read the Quick Start Guide for common patterns
🔧 **Check out [Config Examples](CONFIG_EXAMPLES your AI provider
💬 Join the discussion and share your use cases

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by developers, for developers

Happy AI model switching! 🤖✨